# BITFIELD

> Read, write and increment integer fields of any width inside a string.

URL: https://docs.hotkv.com/commands/bitfield/

```
BITFIELD key [GET encoding offset | [OVERFLOW WRAP | SAT | FAIL] SET encoding offset value | [OVERFLOW WRAP | SAT | FAIL] INCRBY encoding offset increment ...]
```

- Group: Bitmap
- Complexity: O(1) for each operation
- HotKV Cloud: all plans
- On-Premise: no license needed

`BITFIELD` treats the string at `key` as an array of integer fields and runs a
list of operations on it in one step, returning one result per operation. Use
it to pack many small counters or flags into a single key.

Each field has an encoding: `i` for signed or `u` for unsigned, followed by
the width in bits, for example `u8` or `i16`. Signed fields can be 1 to 64
bits wide, unsigned fields 1 to 63. The offset is a bit position, or `#n` to
mean "the n-th field of this width" (`#2` with `u8` is bit offset 16).

A missing key reads as zeros. An operation list that only uses `GET` does not
create the key; one with `SET` or `INCRBY` creates it and grows the string to
fit every field it writes, even if `OVERFLOW FAIL` stops the write. The key
keeps its time to live.

## Options

| Operation | Effect |
| --- | --- |
| `GET encoding offset` | Return the field's value. |
| `SET encoding offset value` | Write the field and return its previous value. |
| `INCRBY encoding offset increment` | Add `increment` (may be negative) and return the new value. |
| `OVERFLOW WRAP` | Following `INCRBY` operations wrap around on overflow (the default). |
| `OVERFLOW SAT` | Following `INCRBY` operations stop at the field's minimum or maximum. |
| `OVERFLOW FAIL` | Following `INCRBY` operations that would overflow do nothing and return nil. |

`OVERFLOW` applies to the operations after it, until the next `OVERFLOW`. All
operations are checked before any of them runs.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Always | Array with one integer per `GET`, `SET` or `INCRBY`; a nil bulk string for an `INCRBY` refused by `OVERFLOW FAIL` | Array of integers and nulls |

Errors:

- `ERR Invalid bitfield type. Use something like i16 u8. Note that u64 is not supported but i64 is.`
- `ERR bit offset is not an integer or out of range` when the offset is
  negative or the field would end past the largest allowed string (2^32 bits
  with the default `proto-max-bulk-len`).
- `ERR Invalid OVERFLOW type specified`
- `ERR value is not an integer or out of range` for a bad `value` or
  `increment`.
- `ERR syntax error` for an unknown operation or a missing argument.
- `WRONGTYPE` when the key holds a value that is not a string.

## Examples

```
127.0.0.1:6379> BITFIELD counters SET u8 0 200 GET u8 0
1) (integer) 0
2) (integer) 200
127.0.0.1:6379> BITFIELD counters INCRBY u8 0 100
1) (integer) 44
127.0.0.1:6379> BITFIELD counters OVERFLOW SAT INCRBY u8 0 300
1) (integer) 255
127.0.0.1:6379> BITFIELD counters OVERFLOW FAIL INCRBY u8 0 1
1) (nil)
127.0.0.1:6379> BITFIELD counters INCRBY i8 #1 -5
1) (integer) -5
```

## Compatibility

Same as Redis 7 and Valkey 8.

## See also

[BITFIELD_RO](https://docs.hotkv.com/commands/bitfield_ro/index.md), [SETBIT](https://docs.hotkv.com/commands/setbit/index.md),
[GETBIT](https://docs.hotkv.com/commands/getbit/index.md), [BITCOUNT](https://docs.hotkv.com/commands/bitcount/index.md)