# *********************************************************************
#  Written by and copyright Carlo Strozzi <carlos@linux.it>.
#
#  filter.txt: help text
#  Copyright (C) 2001 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.
#
# *********************************************************************

                     NoSQL operator: filter

Runs standard utilities, such as grep(1), sed(1), etc., on a NoSQL
table passed via STDIN.

Usage: filter [options --] command [args]

Options:
    --input (-i) 'file'
      Read input from 'file' instead of STDIN.

    --output (-o) 'file'
      Write output to 'file' instead of STDOUT.

    --help (-h)
      Print this help info.

    --no-header (-N)
      Suppress header from output table.

    --
      Marks the end of 'filter' options and the beginning
      of the actual filtering utility.

'command': the utility to be run (grep, sed, ...).

'args': any extra arguments and options for 'command'.

Notes:

This operator reads a NoSQL table via STDIN and runs the specified
'filter' program on the table body. Any options and arguments that
are suitable for the specified filter can be given on the command
line.

This operator can also be used as a pre-processor for other NoSQL
commands, to boost performaces on large tables. For instance, on
a 20000+ record table I got these results:

time row 'Field ~ /keyword/' < bigtable.rdb
real    0m0.400s
user    0m0.350s
sys     0m0.050s

time filter grep keyword < bigtable.rdb | row 'Field ~ /keyword/'
real    0m0.079s
user    0m0.030s
sys     0m0.040s

i.e. a performance improvement of 500% !

$Id$
