Skip to content

Commit 2121cad

Browse files
zackcamzackcam
committed
First round of rewording and changes to documentation. Added ability to generate bloom man pages
Signed-off-by: zackcam <[email protected]>
1 parent 6f84713 commit 2121cad

15 files changed

+110
-94
lines changed

‎Makefile

+20-5
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ DATE ?= 2025-01-08
88

99
# Path to the code repo.
1010
VALKEY_ROOT ?= ../valkey
11-
11+
VALKEY_BLOOM_ROOT ?= ../valkey-bloom
1212
# Where to install man pages
1313
INSTALL_MAN_DIR ?= /usr/local/share/man
1414

@@ -30,6 +30,10 @@ ifeq ("$(wildcard $(VALKEY_ROOT))","")
3030
$(error Please provide the VALKEY_ROOT variable pointing to the Valkey source code)
3131
endif
3232

33+
ifeq ("$(wildcard $(VALKEY_BLOOM_ROOT))","")
34+
$(error Please provide the VALKEY_ROOT variable pointing to the Valkey source code)
35+
endif
36+
3337
ifeq ("$(shell which pandoc)","")
3438
$(error Please install pandoc)
3539
endif
@@ -54,7 +58,9 @@ endif
5458

5559
documented_commands = $(wildcard commands/*.md)
5660
commands_json_files = $(wildcard $(VALKEY_ROOT)/src/commands/*.json)
57-
existing_commands = $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md)
61+
bloom_commands_json_files = $(wildcard $(VALKEY_BLOOM_ROOT)/src/commands/*.json)
62+
existing_commands = $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md) \
63+
$(bloom_commands_json_files:$(VALKEY_BLOOM_ROOT)/src/commands/%.json=commands/%.md)
5864

5965
topics = $(wildcard topics/*)
6066
commands = $(filter $(existing_commands),$(documented_commands))
@@ -65,7 +71,13 @@ topics_pics = $(filter-out %.md,$(topics))
6571
# ---- Temp files ----
6672

6773
# JSON files for the commands that have a .md file (excluding undocumented commands).
68-
json_for_documented_commands = $(commands:commands/%.md=$(VALKEY_ROOT)/src/commands/%.json)
74+
json_for_documented_commands = \
75+
$(patsubst commands/%.md,$(VALKEY_ROOT)/src/commands/%.json,$(filter $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md),$(commands))) \
76+
$(patsubst commands/%.md,$(VALKEY_BLOOM_ROOT)/src/commands/%.json,$(filter $(bloom_commands_json_files:$(VALKEY_BLOOM_ROOT)/src/commands/%.json=commands/%.md),$(commands)))
77+
$(info NOOOOOOOOOOO)
78+
$(info $(json_for_documented_commands))
79+
$(info NOOOOOOOOOOO)
80+
6981

7082
$(BUILD_DIR)/.commands-per-group.json: $(VALKEY_ROOT)/src/commands/. utils/build-command-groups.py | $(BUILD_DIR)
7183
utils/build-command-groups.py $(json_for_documented_commands) > $@~~
@@ -175,11 +187,14 @@ $(MAN_DIR)/man1/valkey-%.1.gz: topics/%.md $(man_scripts)
175187
utils/preprocess-markdown.py --man --page-type program \
176188
--version $(VERSION) --date $(DATE) \$< \
177189
| utils/links-to-man.py - | $(to_man) > $@
178-
$(MAN_DIR)/man3/%.3valkey.gz: commands/%.md $(VALKEY_ROOT)/src/commands/%.json $(BUILD_DIR)/.commands-per-group.json $(man_scripts)
190+
$(MAN_DIR)/man3/%.3valkey.gz: commands/%.md $(BUILD_DIR)/.commands-per-group.json $(man_scripts)
191+
$(eval VALKEY_ROOTS := $(VALKEY_ROOT) $(VALKEY_BLOOM_ROOT))
192+
$(eval FINAL_ROOT := $(firstword $(foreach root,$(VALKEY_ROOTS),$(if $(wildcard $(root)/src/commands/$*.json),$(root)))))
193+
$(if $(FINAL_ROOT),,$(eval FINAL_ROOT := $(lastword $(VALKEY_ROOTS))))
179194
utils/preprocess-markdown.py --man --page-type command \
180195
--version $(VERSION) --date $(DATE) \
181196
--commands-per-group-json $(BUILD_DIR)/.commands-per-group.json \
182-
--valkey-root $(VALKEY_ROOT) $< \
197+
--valkey-root $(FINAL_ROOT) $< \
183198
| utils/links-to-man.py - | $(to_man) > $@
184199
$(MAN_DIR)/man5/%.5.gz: topics/%.md $(man_scripts)
185200
utils/preprocess-markdown.py --man --page-type config \

‎commands/bf.add.md

+3-4
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
1-
Adds an item to a bloom filter, if the specified filter does not exist creates a default bloom filter with that name.
2-
## Arguments
3-
* key (required) - A Valkey key of Bloom data type
4-
* item (required) - Item to add
1+
Adds an item to a bloom filter, if the specified bloom filter does not exist creates a bloom filter with default configurations with that name.
2+
3+
If you want to create a bloom filter with non-standard options, use the `BF.INSERT` or `BF.RESERVE` command.
54

65
## Examples
76
```

‎commands/bf.card.md

-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
11
Gets the cardinality of a Bloom filter - number of items that have been successfully added to a Bloom filter.
2-
## Arguments
3-
* key (required) - A Valkey key of Bloom data type
42

53
## Examples
64
```

‎commands/bf.exists.md

+7-5
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
1-
Determines if a specified item has been added to the specified bloom filter.
2-
Syntax
1+
Determines if an item has been added to the bloom filter.
2+
3+
A Bloom filter has two possible responses when you check if an item exists:
4+
5+
* "No" (Definite) - If the filter says an item is NOT present, this is 100% certain. The item is definitely not in the set.
6+
7+
* "Maybe" (Probabilistic) - If the filter says an item IS present, this is uncertain. There's a chance it's a false positive. The item might be in the set, but may not be
38

4-
## Arguments
5-
* key (required) - A Valkey key of Bloom data type
6-
* item (required) - The item that we are checking if it exists in the bloom object
79

810
## Examples
911
```

‎commands/bf.info.md

+10-10
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
Returns information about a bloomfilter
1+
Returns information about a bloom filter
2+
3+
## Info Fields
4+
* CAPACITY - Returns the number of unique items that would need to be added before scaling would happen
5+
* SIZE - Returns the number of bytes allocated
6+
* FILTERS - Returns the number of filters in the specified key
7+
* ITEMS - Returns the number of unique items that have been added the the bloom filter
8+
* ERROR - Returns the false positive rate for the bloom filter
9+
* EXPANSION - Returns the expansion rate
10+
* MAXSCALEDCAPACITY - Returns the maximum capacity that can be reached before an error occurs
211

3-
## Arguments
4-
* key (required) - A valkey key of bloom data type
5-
* CAPACITY (optional) - Returns the number of unique items that would need to be added before scaling would happen
6-
* SIZE (optional) - Returns the memory size which is the number of bytes allocated
7-
* FILTERS (optional) - Returns the number of filters in the specified key
8-
* ITEMS (optional) - Returns the number of unique items that have been added the the Bloom filter
9-
* ERROR (optional) - Returns the false positive rate for the bloom filter
10-
* EXPANSION (optional) - Returns the expansion rate
11-
* MAXSCALEDCAPACITY (optional) - Returns the maximum capacity that can be reached before an error occurs
1212
If none of the optional fields are specified, all the fields will be returned. MAXSCALEDCAPACITY will be an unrecognized argument on non scaling filters
1313

1414
## Examples

‎commands/bf.insert.md

+18-18
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
1-
Creates a bloom object with the specified parameters. If a parameter is not specified then the default value will be used. If ITEMS is specified then it will also attempt to add all items specified after
1+
Creates a bloom filter with the specified parameters. If a parameter is not specified then the default value will be used. If ITEMS is specified then it will also attempt to add all items specified
2+
3+
## Insert Fields
4+
* CAPACITY capacity - capacity for the initial bloom filter
5+
* ERROR `fp_error` - The false positive rate for the bloom filter
6+
* EXPANSION expansion - The expansion rate for a scaling filter
7+
* NOCREATE - Will not create the bloom filter and add items if the filter does not exist already
8+
* TIGHTENING `tightening_ratio` - The tightening ratio for the bloom filter
9+
* SEED seed - The seed the hash functions will use
10+
* NONSCALING - Will make it so the filter can not scale
11+
* VALIDATESCALETO `validatescaleto` - Checks if the filter could scale to this capacity and if not show an error and don’t create the bloom filter
12+
* ITEMS item - One or more items we will add to the bloom filter
213

3-
## Arguments
414
Due to the nature of NONSCALING and VALIDATESCALETO arguments, specifying NONSCALING and VALIDATESCALETO isn't allowed
5-
* key (required) - Is the key name for a Bloom filter to add the item to
6-
* CAPACITY capacity (optional) - capacity for the inital bloom filter
7-
* ERROR fp_error (optional)- The false positive rate for the bloom filter
8-
* EXPANSION expansion(optional) - The expansion rate for a scaling filter
9-
* NOCREATE (optional) - Will not create the bloom filter and add items if the filter does not exist already
10-
* TIGHTENING (optional) - The tightening ratio for the bloom filter
11-
* SEED (optional) - The seed the hash functions will use
12-
* NONSCALING (optional) - Will make it so the filter can not scale
13-
* VALIDATESCALETO validatescaleto (optional) - Checks if the filter could scale to this capacity and if not show an error and don’t create the bloom filter
14-
* ITEMS (optional) - Items we will add to the bloom filter
1515

1616
## Examples
1717
```
@@ -28,13 +28,13 @@ Due to the nature of NONSCALING and VALIDATESCALETO arguments, specifying NONSC
2828

2929
```
3030
127.0.0.1:6379> BF.INSERT key NONSCALING VALIDATESCALETO 100
31-
cannot use NONSCALING and VALIDATESCALETO options together
32-
127.0.0.1:6379> BF.INSERT key CAPACITY 1000 VALIDATESCALETO 999999999999999999999 ITEMS item2 item3
33-
provided VALIDATESCALETO causes bloom object to exceed memory limit
34-
127.0.0.1:6379> BF.INSERT key VALIDATESCALETO 999999999999999999999 EXPANSION 1 ITEMS item2 item3
35-
provided VALIDATESCALETO causes false positive to degrade to 0
31+
(error) ERR cannot use NONSCALING and VALIDATESCALETO options together
32+
127.0.0.1:6379> BF.INSERT key CAPACITY 1000 VALIDATESCALETO 999999999999999999 ITEMS item2 item3
33+
(error) ERR provided VALIDATESCALETO causes bloom object to exceed memory limit
34+
127.0.0.1:6379> BF.INSERT key VALIDATESCALETO 999999999999999999 EXPANSION 1 ITEMS item2 item3
35+
(error) ERR provided VALIDATESCALETO causes false positive to degrade to 0
3636
```
3737
```
3838
127.0.0.1:6379> BF.INSERT key NOCREATE ITEMS item1 item2
39-
not found
39+
(error) ERR not found
4040
```

‎commands/bf.load.md

-3
Original file line numberDiff line numberDiff line change
@@ -1,4 +1 @@
11
Loads a bloom filter from a dump of an existing bloom object with all the properties and bit vector dump.
2-
## Arguments
3-
* key (required) - Is the key name for a Bloom filter to add the item to
4-
* dump (required) - Is the dump we are restoring

‎commands/bf.madd.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
Adds one or more items to a Bloom Filter, if the specified filter does not exist creates a default bloom filter with that name.
2-
## Arguments
3-
* key (required) - Is the key name for a Bloom filter to add the item to
4-
* item (requires at least 1 item but can add as many as wanted ) - Is the item/s to add
1+
Adds one or more items to a Bloom Filter, if the bloom filter does not exist creates a default bloom filter.
2+
3+
If you want to create a bloom filter with non-standard options, use the `BF.INSERT` or `BF.RESERVE` command.
4+
55
## Examples
66
```
77
127.0.0.1:6379> BF.MADD key item1 item2

‎commands/bf.mexists.md

+8-4
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
1-
Determines if one or more items has been added to the specified bloom filter
2-
## Arguments
3-
* key (required) - A Valkey key of Bloom data type
4-
* item (requires at least 1 item but can add as many as desired) - The item/s that we are checking if it exists in the bloom object
1+
Determines if one or more items has been added to a bloom filter.
2+
3+
A Bloom filter has two possible responses when you check if an item exists:
4+
5+
* "No" (Definite) - If the filter says an item is NOT present, this is 100% certain. The item is definitely not in the set.
6+
7+
* "Maybe" (Probabilistic) - If the filter says an item IS present, this is uncertain. There's a chance it's a false positive. The item might be in the set, but may not be
8+
59
## Examples
610
```
711
127.0.0.1:6379> BF.MADD key item1 item2

‎commands/bf.reserve.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
Creates an empty bloom object with the capacity and false positive rate specified
2-
## Arguments
3-
* key (required) - A Valkey key of Bloom data type
4-
* error_rate (required) - The fp rate the bloom filter will be created with
5-
* capacity (required) - The starting capacity the bloom filter will be created with
6-
* EXPANSION expansion(optional)- The rate in which filters will increase by
7-
* NONSCALING (optional) - Setting this will make it so the bloom object can’t expand past its initial capacity
2+
3+
## Reserve fields
4+
* error_rate - The false positive rate the bloom filter will be created with
5+
* capacity - The starting capacity the bloom filter will be created with
6+
* EXPANSION expansion - The rate in which filters will increase by
7+
* NONSCALING - Setting this will make it so the bloom object can’t expand past its initial capacity
88

99
## Examples
1010
```

‎groups.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"description": "Operations on the Bitmap data type"
55
},
66
"bloom": {
7-
"display": "Bloom",
7+
"display": "Bloom filter",
88
"description": "Operations on the Bloom filter data type"
99
},
1010
"cluster": {

‎resp2_replies.json

+8-8
Original file line numberDiff line numberDiff line change
@@ -64,8 +64,8 @@
6464
],
6565
"BF.ADD": [
6666
"One of the following:",
67-
"* [Integer reply](../topics/protocol.md#integers): '1'. The item was successfully added",
68-
"* [Integer reply](../topics/protocol.md#integers): '0'. The item already existed in the bloom filter",
67+
"* [Integer reply](../topics/protocol.md#integers): `1` if the item was successfully added",
68+
"* [Integer reply](../topics/protocol.md#integers): `0` if the item already existed in the bloom filter",
6969
"",
7070
"The command may fail with an error for several reasons: if the wrong number of arguments are provided, if attempting to add to a non scaling filter that is full"
7171
],
@@ -76,23 +76,23 @@
7676
],
7777
"BF.EXISTS": [
7878
"One of the following:",
79-
"* [Integer reply](../topics/protocol.md#integers): '1'. The item exists in the bloom filter",
80-
"* [Integer reply](../topics/protocol.md#integers): '0'. The bloom filter does not exist or the item has not been added to the bloom filter",
79+
"* [Integer reply](../topics/protocol.md#integers): `1` if the item exists in the bloom filter",
80+
"* [Integer reply](../topics/protocol.md#integers): `0` if the bloom filter does not exist or the item has not been added to the bloom filter",
8181
"",
8282
"The command will fail if the wrong number of arguments are provided"
8383
],
8484
"BF.INFO": [
8585
"When no optional arguments are provided:",
86-
"[Array reply](../topics/protocol.md#arrays): List of information about the bloom filter.",
87-
"When an optional argument is provided:",
86+
"* [Array reply](../topics/protocol.md#arrays): List of information about the bloom filter.",
87+
"When an optional argument excluding ERROR is provided:",
8888
"* [Integer reply](../topics/protocol.md#integers): argument value",
89-
"* [String reply??](../topics/protocol.md#simple-strings): argument value",
89+
"When ERROR is provided as an optional argument:",
90+
"* [String reply](../topics/protocol.md#simple-strings): argument value",
9091
"",
9192
"The command may fail with an error for several reasons: if the wrong number of arguments are provided, if trying to get MAXSCALEDCAPACITY of a non scaling filter"
9293
],
9394
"BF.INSERT": [
9495
"[Array reply](../topics/protocol.md#arrays): Array of ints (1’s and 0’s) - if filter already exists or if creation was successful. An empty array if no items are provided",
95-
"[String reply??](../topics/protocol.md#simple-strings): not found, if the filter does not exist and NOCREATE is specified",
9696
"",
9797
"The command may fail with an error for several reasons: if the wrong number of arguments are provided, if the provided VALIDATESCALETO is not possible, if the provided optional args are not valid"
9898
],

‎resp3_replies.json

+8-8
Original file line numberDiff line numberDiff line change
@@ -64,8 +64,8 @@
6464
],
6565
"BF.ADD": [
6666
"One of the following:",
67-
"* [Integer reply](../topics/protocol.md#integers): '1'. The item was successfully added",
68-
"* [Integer reply](../topics/protocol.md#integers): '0'. The item already existed in the bloom filter",
67+
"* [Integer reply](../topics/protocol.md#integers): `1` if the item was successfully added",
68+
"* [Integer reply](../topics/protocol.md#integers): `0` if the item already existed in the bloom filter",
6969
"",
7070
"The command may fail with an error for several reasons: if the wrong number of arguments are provided, if attempting to add to a non scaling filter that is full"
7171
],
@@ -76,23 +76,23 @@
7676
],
7777
"BF.EXISTS": [
7878
"One of the following:",
79-
"* [Integer reply](../topics/protocol.md#integers): '1'. The item exists in the bloom filter",
80-
"* [Integer reply](../topics/protocol.md#integers): '0'. The bloom filter does not exist or the item has not been added to the bloom filter",
79+
"* [Integer reply](../topics/protocol.md#integers): `1` if the item exists in the bloom filter",
80+
"* [Integer reply](../topics/protocol.md#integers): `0` if the bloom filter does not exist or the item has not been added to the bloom filter",
8181
"",
8282
"The command will fail if the wrong number of arguments are provided"
8383
],
8484
"BF.INFO": [
8585
"When no optional arguments are provided:",
86-
"[Array reply](../topics/protocol.md#arrays): List of information about the bloom filter.",
87-
"When an optional argument is provided:",
86+
"* [Array reply](../topics/protocol.md#arrays): List of information about the bloom filter.",
87+
"When an optional argument excluding ERROR is provided:",
8888
"* [Integer reply](../topics/protocol.md#integers): argument value",
89-
"* [String reply??](../topics/protocol.md#simple-strings): argument value",
89+
"When ERROR is provided as an optional argument:",
90+
"* [String reply](../topics/protocol.md#simple-strings): argument value",
9091
"",
9192
"The command may fail with an error for several reasons: if the wrong number of arguments are provided, if trying to get MAXSCALEDCAPACITY of a non scaling filter"
9293
],
9394
"BF.INSERT": [
9495
"[Array reply](../topics/protocol.md#arrays): Array of ints (1’s and 0’s) - if filter already exists or if creation was successful. An empty array if no items are provided",
95-
"[String reply??](../topics/protocol.md#simple-strings): not found, if the filter does not exist and NOCREATE is specified",
9696
"",
9797
"The command may fail with an error for several reasons: if the wrong number of arguments are provided, if the provided VALIDATESCALETO is not possible, if the provided optional args are not valid"
9898
],

0 commit comments

Comments
 (0)