.\" Text automatically generated by txt2man
.TH bloom 1 "18 July 2021" "bloom 0.2.3" ""
.SH NAME
\fBbloom \fP- utility to work with Bloom filters
\fB
.SH SYNOPSIS
.nf
.fam C
\fBbloom\fP [\fIglobal\fP \fIoptions\fP] \fIcommand\fP [\fIcommand\fP \fIoptions\fP] [arguments\.\.\.]

.fam T
.fi
.fam T
.fi
.SH DESCRIPTION

This is the main tool to interact with Bloom filters, e.g. to create, fill and
query them.
.SH BASIC USAGE

To create a new Bloom filter with a desired capacity and false positive
probability, you can use `create`:
.PP
.nf
.fam C
    #will create a gzipped Bloom filter with 100.000 capacity and a 0.1 % false positive probability
    bloom --gzip create -p 0.001 -n 100000 test.bloom.gz

.fam T
.fi
To insert values, you can use the insert \fIcommand\fP and pipe some input to it
(each line will be treated as one value):
.PP
.nf
.fam C
    cat values | bloom --gzip insert test.bloom.gz

.fam T
.fi
You can also interactively add values to the filter by specifying the
\fB--interactive\fP option:
.PP
.nf
.fam C
    bloom --gzip --interactive insert test.bloom.gz

.fam T
.fi
To check if a given value or a list of values is in the filter, you can use
`check`:
.PP
.nf
.fam C
    cat values | bloom --gzip check test.bloom.gz

.fam T
.fi
This will return a list of all values in the filter.
.SH ADVANCED USAGE

Sometimes it is useful to attach additional information to a string that we
want to check against the Bloom filter, such as a timestamp or the original
line content. To make passing along this additional information easier within
a shell context, the Bloom tool provides an option for splitting the input
string by a given delimiter and checking the filter against the resulting
field values.
.PP
.nf
.fam C
    # will check the Bloom filter for the values foo, bar and baz
    cat "foo,bar,baz" | bloom -s filter.bloom

    # uses a different delimiter (--magic-delimiter--)
    cat "foo--ac5ba--bar--ac5ba--baz" | bloom  -d "--ac5ba--" -s filter.bloom

    # will check the Bloom filter against the second field value only
    cat "foo,bar,baz" | bloom -f 1 -s filter.bloom

    # will check the Bloom filter against the second and third field values only
    cat "foo,bar,baz" | bloom -f 1,2 -s filter.bloom

    # will print one line for each field value that matched against the filter
    cat "foo,bar,baz" | bloom -e -s filter.bloom

    # will print the last field value for each line whose fields matched against the filter
    cat "foo,bar,baz" | bloom -e -s --pf -1 filter.bloom

.fam T
.fi
This functionality is especially handy when using CSV data, as it allows you
to filter CSV rows by checking individual columns against the filter without
having to use external tools to split and reassemble the lines.
.SH COMMANDS

.TP
.B
* create
Create a new Bloom filter and store it in the given file.
.TP
.B
* insert
Inserts new values into an existing Bloom filter.
.TP
.B
* join, merge
Joins two Bloom filters into one.
.TP
.B
* check
Checks values against an existing Bloom filter.
.TP
.B
* set-data
Sets the data associated with the Bloom filter.
.TP
.B
* get-data
Prints the data associated with the Bloom filter.
.TP
.B
* show
Shows various details about a given Bloom filter.
.TP
.B
* help
Shows a list of commands or help for one \fIcommand\fP
.RE
.PP

.SH OPTIONS

.TP
.B
\fB--gzip\fP, \fB--gz\fP
compress \fBbloom\fP file with gzip
.TP
.B
\fB--interactive\fP, \fB-i\fP
interactively add values to the filter
.TP
.B
\fB--split\fP, \fB-s\fP
split the input string
.TP
.B
\fB--each\fP, \fB-e\fP
print each match of a split string individually
.TP
.B
\fB--delimiter\fP value, \fB-d\fP value
delimiter to use for splitting (default: ",")
.TP
.B
\fB--fields\fP value, \fB-f\fP value
fields of split output to use in filter (a single number or a comma-separated list of numbers, zero-indexed)
.TP
.B
\fB--print-fields\fP value, \fB--pf\fP value
fields of split output to print for a successful match (a single number or a comma-separated list of numbers, zero-indexed).
.TP
.B
\fB--help\fP, \fB-h\fP
show help
.TP
.B
\fB--version\fP, \fB-v\fP
print the version