# *********************************************************************
# Written by and copyright Carlo Strozzi <carlos@linux.it>.
#
# update.txt: help text
# Copyright (C) 2001-2002 Carlo Strozzi <carlos@linux.it>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
#
# *********************************************************************
# $Id: update.txt,v 1.2 2003/03/17 10:10:45 carlo Exp $

                      NoSQL operator: update

Inserts/updates/deletes table rows based on the contents
of an edit table.

Usage: update [options] table_1 < table_2

Options:
    --delete (-d) 'string'
      By default, rows where the key columns match and the data
      value in the delete column is equal to '..DEL..' are
      deleted. This option allows 'string' to be used as the delete
      string as opposed to '..DEL..'.

    --no-header (-N)
      Strip the table header from output.

    --help (-h)
      Display this help text.

    --write-size (-w) 'file'
      The number of records found in the update table is
      written to 'file' upon exit. This can be used by
      an invoking program as an indication that it is
      time for permanently merge the updates into the
      main table (table reorganisation).

    --last (-l)
      If the input tables contain duplicated column names
      pick the last occurrence of each. The default is to
      pick the first one. This is sometimes useful after
      the 'jointable' operator.

    --stdin (-s)
      In the normal case, 'table_1' is the table with the
      updates, while 'table_2' is the one being updated.
      This option exchanges the two tables, thus making
      the program expect to read the updates from stdin
      and the main table from a file.

Notes:

This operator updates/deletes rows in 'table_2', based on the rows
in 'table_1' that match on the key column. Neither table needs to
be sorted nor be unique on any particular fields. If more than one
record with the same key value is present in 'table_1', the last
occurrence takes over. Fields of 'table_1' that are not present in
'table_2' are silently ignored. Key (leftmost) and delete (second)
columns do not need to have matching names across the two tables.

An existing row in 'table_2' will be deleted if there is a key
column match and the data in the delete column is equal to the delete
string, "..DEL.."  (without the quotes) by default. The delete column
is the first non-key column (i.e. the 2nd column) in 'table_1'.

Records in 'table_1' that do not have correspondents in 'table_2',
and that do not have the delete string in the field next to the key,
are inserted in key order in the output stream. Again, fields in
'table_1' that do not have correspondent ones in 'table_2' are ignored.

The header for the resulting table is taken from 'table_2'.

If output sorting is desired on any of the fields of the resulting
table, for instance to make it 'joinable' on-the-fly, it will have
to be done by the invoking program.

Hint: if all you need is to delete records that match a list of primary 
keys, then a better/faster alternative would be to use the 'filter'
operator, like this:

      filter -- grep -v -f remove_list < input_table

where 'remove_list' is a file containing one key per line, each
prepended by a caret (^) and followed by a TAB, to make sure that it
matches the table leftmost field, that is the primary key.

