# BF.RESERVE

> Create an empty Bloom filter with a chosen error rate and capacity.

URL: https://docs.hotkv.com/commands/bf-reserve/

```
BF.RESERVE key error_rate capacity [EXPANSION expansion] [NONSCALING]
```

- Group: Bloom filter
- Complexity: O(1)
- HotKV Cloud: all plans
- On-Premise: no license needed

`BF.RESERVE` creates an empty Bloom filter at `key`. A Bloom filter answers
"have I seen this item?" using far less memory than a set: it never misses an
item that was added, but may wrongly report an item that was not, at about
the error rate you choose.

You only need `BF.RESERVE` to pick non-default settings. [BF.ADD](https://docs.hotkv.com/commands/bf-add/index.md),
[BF.MADD](https://docs.hotkv.com/commands/bf-madd/index.md) and [BF.INSERT](https://docs.hotkv.com/commands/bf-insert/index.md) create a
filter on demand, with capacity 100, error rate 0.01 and expansion 2.

## Arguments and options

| Argument | Effect |
| --- | --- |
| `error_rate` | The false positive rate to aim for, between 0 and 1 (exclusive), for example `0.001` for 0.1%. Lower rates use more memory. |
| `capacity` | How many items the filter is sized for, from 1 to 1073741824. |
| `EXPANSION expansion` | When the filter is full, the next item adds a new layer this many times larger than the last one, keeping the overall error rate. Default 2, range 0 to 32768. `0` makes the filter non-scaling. |
| `NONSCALING` | Never grow: once `capacity` items are in, adding a new item fails. |

`EXPANSION` and `NONSCALING` cannot be combined. Other extra arguments are
ignored.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Created | Simple string `OK` | Simple string `OK` |

Error replies:

- `ERR item exists` if a Bloom filter already exists at the key.
- `ERR bad error rate` and `ERR error rate must be in the range (0.000000, 1.000000)`
- `ERR bad capacity` and `ERR capacity must be in the range [1, 1073741824]`
- `ERR no expansion`, `ERR bad expansion` and `ERR expansion must be in the range [0, 32768]`
- `Nonscaling filters cannot expand` when `EXPANSION` and `NONSCALING` are both given.
- `ERR Insufficient memory to create filter` when the filter would not fit in memory.
- `WRONGTYPE` if the key holds another type.

## Examples

```
127.0.0.1:6379> BF.RESERVE signups 0.01 1000
OK
127.0.0.1:6379> BF.RESERVE signups 0.01 1000
(error) ERR item exists
127.0.0.1:6379> BF.RESERVE fixed 0.001 5000 NONSCALING
OK
127.0.0.1:6379> BF.RESERVE bad 1.5 100
(error) ERR error rate must be in the range (0.000000, 1.000000)
```

## Compatibility

Same arguments, limits and errors as `BF.RESERVE` in RedisBloom.

## See also

[BF.ADD](https://docs.hotkv.com/commands/bf-add/index.md), [BF.INSERT](https://docs.hotkv.com/commands/bf-insert/index.md), [BF.INFO](https://docs.hotkv.com/commands/bf-info/index.md),
[BF.EXISTS](https://docs.hotkv.com/commands/bf-exists/index.md)