BITFIELD
Syntax
Parameters
Parameter | Description | Type | Required |
---|---|---|---|
key | The name of the key containing the bitfield. | String | Yes |
GET type offset | Retrieves bits starting at the specified offset with the specified type. Type defines the signed/unsigned integer format. | String | Optional |
SET type offset value | Sets bits at the specified offset to the given value using the specified integer type. | String | Optional |
INCRBY type offset increment | Increments bits at the specified offset by the increment value and wraps around on overflow based on type. | String | Optional |
OVERFLOW WRAP|SAT|FAIL | Defines overflow behavior. | String | Optional |
Return values
Condition | Return Value |
---|---|
Command is successful | Array of results corresponding to each subcommand |
Syntax or specified constraints are invalid | error |
Behaviour
The BITFIELD command in DiceDB allows for direct bitwise manipulation within a binary string stored in a single key. It works by treating the string as an array of integers and performs operations on specific bits or groups of bits at specified offsets:
- SET: Sets the value of bits at a specific offset.
- GET: Retrieves the value of bits at a specific offset.
- INCRBY: Increments the value at a specific offset by a given amount, useful for counters.
- OVERFLOW: Defines the overflow behavior (WRAP, SAT, FAIL) for INCRBY, determining how to handle values that exceed the bitfield’s limits.
Overflow Options:
- WRAP: Cycles values back to zero on overflow (default behavior).
- SAT: Saturates to the maximum or minimum value for the bit width.
- FAIL: Prevents overflow by causing INCRBY to fail if it would exceed the limits.
- Supports unsigned (u) with bit widths between 1 and 63 and signed (i) integers with bit widths between 1 and 64.
- The offset specifies where the bitfield starts within the key’s binary string.
- If an offset is out of range (far beyond the current size), DiceDB will automatically expand the binary string to accommodate it, which can impact memory usage.
Errors
-
Syntax Error
:- Error Message:
(error) ERR syntax error
- Occurs if the commands syntax is incorrect.
- Error Message:
-
Invalid bitfield type
:- Error Message:
(error) ERR Invalid bitfield type. Use something like i16 u8. Note that u64 is not supported but i64 is
- Occurs when attempting to use the command on a wrong type.
- Error Message:
-
Non-integer value
:- Error Message:
(error) ERR value is not an integer or out of range
- Occurs when attempting to use the command on a value that contains a non-integer value.
- Error Message:
-
Invalid OVERLOW type
:- Error Message:
(error) ERR Invalid OVERFLOW type specified
- Occurs when attempting to use a wrong OVERFLOW type.
- Error Message:
-
Wrong type of value or key
:- Error Message:
(error) WRONGTYPE Operation against a key holding the wrong kind of value
- Occurs when attempting to use the command on a key that contains a non-string value.
- Error Message:
-
Invalid bIT offset
:- Error Message:
(error) ERR bit offset is not an integer or out of range
- Occurs when attempting to use the command with an invalid bit offset.
- Error Message:
Example Usage
Basic Usage:
Overflow control:
Example of OVERFLOW FAIL returning nil:
Invalid usage:
Notes
Where an integer encoding is expected, it can be composed by prefixing with i for signed integers and u for unsigned integers with the number of bits of our integer encoding. So for example u8 is an unsigned integer of 8 bits and i16 is a signed integer of 16 bits.
The supported encodings are up to 64 bits for signed integers, and up to 63 bits for unsigned integers. This limitation with unsigned integers is due to the fact that currently RESP is unable to return 64 bit unsigned integers as replies.
Subcommands
- subcommand: Optional. Available subcommands include:
GET
<type>
<offset>
: Returns the specified bit field.SET
<type>
<offset>
<value>
: Set the specified bit field and - returns its old value.INCRBY
<type>
<offset>
<increment>
: Increments or decrements (if a negative increment is given) the specified bit field and returns the new value.OVERFLOW
[WRAP
|SAT
|FAIL
]