Counters
Maintain a request, job, or event total that changes by an arbitrary integer amount.
Redis · Module
INCRBY
INCRBY adds an integer increment to a key's integer value and returns the updated value. Missing keys begin at zero, while wrong types, non-integer strings, and out-of-range values cause errors.
How it works
INCRBY adds a signed integer increment to the integer value held by a key and returns the resulting value. A missing key is treated as zero before the addition; invalid types, non-integer strings, and values outside the signed 64-bit range produce errors.
Syntax
INCRBY key incrementParameters
| Name | Type | Description |
|---|---|---|
key | key | The name of the key. |
increment | integer | The integer amount to add to the value. |
Returns
Integer reply: the value of the key after the increment.
Key points
- Adds the specified integer amount to the number stored under the key.
- A missing key starts at zero, so the first INCRBY can create a counter.
- The increment argument is the integer quantity applied to the stored value.
- A successful call returns the updated counter value.
- Both the stored integer and resulting arithmetic are constrained to signed 64-bit integers.
Common mistakes
- The target must hold a Redis string representing an integer; other Redis types cause an error.
- Numeric text must be representable as an integer, not arbitrary numeric or floating-point text.
- The operation cannot represent results outside the signed 64-bit integer range.
Example: Increment a counter
redis> SET mykey "10"
OK
redis> INCRBY mykey 5
(integer) 15Adds 5 to the integer stored in mykey and returns the updated value.
When to use it
Decrements
Apply a negative increment to reduce a stored integer.
Lazy initialization
Create a counter lazily without initializing it first.
Interview questions
QWhat does INCRBY do when the key does not exist?
INCRBY atomically adds the supplied integer to the integer stored at the key and returns the new value. If the key is absent, Redis first treats it as zero.
Follow-up: What happens when the key contains a list? Redis returns a wrong-type error because INCRBY requires an integer-compatible string value.
QWhat is the command syntax and return value?
The command takes a key and an integer increment: INCRBY key increment. Its return is an integer reply containing the value after the increment.
Follow-up: How would you decrement a counter? Supply a negative increment, provided the resulting value remains within the supported signed 64-bit range.
QWhat constraints apply to the stored value and result?
INCRBY works with signed 64-bit integers and rejects values that cannot be represented as integers. It also rejects keys containing values of the wrong Redis type.
Follow-up: What value is returned after a successful update? Redis returns the key's value after applying the increment, rather than the increment itself.
Related
INCRDECRDECRBYINCRBYFLOAT