bloom(1)

💖 bloom(1) 💖

okay bestie, sit down, hydrate, because we're about to talk about the bloom utility — it's the main character of the Bloom filter world and it lives in section 1 of the manual. periodt ✨

---

✨ SYNOPSIS ✨

bloom [global options] command [command options] [arguments...]

like, that's the whole shape of it: global options first, then a command, then that command's own options, then whatever arguments you're throwing at it. no cap. 🫶

---

🌸 DESCRIPTION 🌸

This is THE main tool for interacting with Bloom filters, bestie. Creating them, filling them, querying them — the whole glow-up pipeline. 💅

---

🎀 BASIC USAGE 🎀

creating one, because duh

To spin up a brand new Bloom filter with a capacity and a false positive probability that you choose, you use create:

#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

yes, she's gzipped, yes she's 100.000 capacity, yes she's 0.1 %. iconic behaviour honestly. ✨

filling her up

To insert values, use the insert command and pipe some input into it. Every single line gets treated as one value, so don't be out here adding random blank lines unless you mean it:

cat values | bloom --gzip insert test.bloom.gz

the interactive route 🦋

You can also add values to the filter interactively, live, one at a time, by specifying the --interactive option:

bloom --gzip --interactive insert test.bloom.gz

it's giving conversational, it's giving intimate, we love that for her.

the vibe check (a.k.a. checking)

To check whether a given value — or a whole list of values — is in the filter, use check:

cat values | bloom --gzip check test.bloom.gz

This will return a list of all values in the filter. so you get your little roster back and you can go "oh okay so THOSE ones" 💜

---

🔥 ADVANCED USAGE 🔥

okay so sometimes you wanna attach extra info to a string that you're checking against the Bloom filter. like a timestamp, or the original line content, whatever. and to make passing that extra info around in a shell context easier, the Bloom tool has an option for splitting the input string by a given delimiter and checking the filter against the resulting field values. chef's kiss 🧚

# 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

This functionality is especially handy when you're working with CSV data, because it lets you filter CSV rows by checking individual columns against the filter — no external tools needed to split and reassemble the lines. you just... do it. in one go. slay. 😭💖

---

👑 COMMANDS 👑

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

---

💅 OPTIONS 💅

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

quick reminder bestie: those field numbers are zero-indexed, so the "second field" is 1. don't come for me when 0 gets you the first one. 🍓

---

and that's the whole page!! this was bloom 0.2.4, dated 24 August 2023, and she ate every single time. go forth, filter your little hearts out, ily 🎀💖✨🦋🌸