Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

BITFIELD

Last updated 
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
Arity
-2 (at least 2 words, counting the command name)
Flags
write
Keys
first 1, last 1, step 1
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

Section titled “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

Section titled “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

Section titled “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

Section titled “Compatibility”

Same as Redis 7 and Valkey 8.

See also

Section titled “See also”

BITFIELD_RO, SETBIT, GETBIT, BITCOUNT