Increments the numeric value of a key with an option to expire. Uses 0 as initial value if the key doesn’t exist.
INCREX key
[NX | XX]
[EX ex |
PX px |
EXAT unix-time-seconds |
PXAT unix-time-milliseconds |
PERSIST]
[ENX] [BYINT
integer | BYFLOAT float]
[LBOUND lowerbound]
[UBOUND upperbound]
[SATURATE]
Increments the numeric value stored at key, optionally
setting or updating its expiration in the same atomic operation. If the
key does not exist, its value is treated as 0. An error is
returned if the key contains a value of the wrong type or contains a
string that cannot be represented as an integer, or as a floating-point
number with BYFLOAT.
By default the increment is 1. Use BYINT to
increment by a 64 bit signed integer, or BYFLOAT to
increment by a floating-point number.
INCREX combines what is usually done with
INCR/INCRBY/INCRBYFLOAT plus
EXPIRE (or a MULTI/EXEC block or
Lua script) into a single command, and adds optional lower and upper
bounds on the resulting value.
NX – Only perform the operation if the key does not
already exist.XX – Only perform the operation if the key already
exists.EX seconds – Set the expire time, in seconds.PX milliseconds – Set the expire time, in
milliseconds.EXAT unix-time-seconds – Set the expire time to a Unix
timestamp, in seconds.PXAT unix-time-milliseconds – Set the expire time to a
Unix timestamp, in milliseconds.PERSIST – Remove the existing expiration from the
key.ENX – Only set the expiration if the key currently has
no TTL. Requires one of EX, PX,
EXAT or PXAT, and cannot be combined with
PERSIST.Without an expiration option, the key keeps its existing TTL. With
EX, PX, EXAT or
PXAT, the TTL is set on every applied increment unless
ENX is given. A call that is skipped or rejected never
changes the TTL.
BYINT increment – Increment by a 64 bit signed
integer.BYFLOAT increment – Increment by a floating-point
number.LBOUND lowerbound – The minimum allowed value of the
result.UBOUND upperbound – The maximum allowed value of the
result.SATURATE – If the result would be out of bounds, clamp
it to LBOUND/UBOUND (or to the limits of the
numeric type when no explicit bound is given) instead of rejecting the
operation.The bound values are integers by default and with BYINT,
and floating-point numbers when used with BYFLOAT.
Without SATURATE, an operation that would take the value
out of bounds is rejected: the value is left unchanged and the reply is
[current_value, 0]. This includes an increment that would
overflow a 64 bit signed integer, which INCRBY reports as
an error instead.
Bounds are checked against the result, not the current value. If the
value is already out of bounds, an increment that leaves it out of
bounds is rejected even if it moves the value toward the range, and with
SATURATE the value is set to the bound, so the applied
increment can have the opposite sign. For example, if the value is
50, INCREX mykey BYINT 1 UBOUND 20 SATURATE
replies [20, -30].
Array: a two-element array of Integers, or of Doubles when
BYFLOAT is used.
0 if
the operation was skipped (for example because of
NX/XX) or rejected because it was out of
bounds, and may differ from the requested increment when
SATURATE clamps the result.O(1)
@fast @string @write
127.0.0.1:6379> SET mykey "10"
OK
127.0.0.1:6379> INCREX mykey
1) (integer) 11
2) (integer) 1
127.0.0.1:6379> INCREX myfloat BYFLOAT 2.5
1) "2.5"
2) "2.5"
127.0.0.1:6379> INCREX mykey BYINT 5 EX 60
1) (integer) 16
2) (integer) 5
127.0.0.1:6379> INCREX mykey BYINT 100 UBOUND 20
1) (integer) 16
2) (integer) 0
127.0.0.1:6379> INCREX mykey BYINT 100 UBOUND 20 SATURATE
1) (integer) 20
2) (integer) 4
A rate limiter built with INCR needs a
MULTI/EXEC block or a Lua script to make sure
the counter always gets an expiration, otherwise the key can be leaked
if the client fails between the two commands. INCREX does
this in one atomic command. With ENX, the expiration is set
only when the counter is created, so the window is not extended by later
requests:
FUNCTION LIMIT_API_CALL(ip)
current, applied = INCREX(ip, EX 1, ENX, BYINT 1, UBOUND 10)
IF applied == 0 THEN
ERROR "too many requests per second"
ELSE
PERFORM_API_CALL()
END
The counter lives for one second from the first request in the
window. Once it reaches the upper bound of 10, further
calls are rejected (the reply is [10, 0]) without modifying
the counter.
Use LBOUND, UBOUND and
SATURATE to keep a value inside a range, for example an
inventory level or a score that must never go below zero:
127.0.0.1:6379> SET stock:item42 2
OK
127.0.0.1:6379> INCREX stock:item42 BYINT -3 LBOUND 0 SATURATE
1) (integer) 0
2) (integer) -2
If only 2 units remain, the key is set to 0 and the
second element of the reply is -2, telling the caller how
much was actually applied.
APPEND, DECR, DECRBY, DELEX, DELIFEQ, GET, GETDEL, GETEX, GETRANGE, GETSET, INCR, INCRBY, INCRBYFLOAT, LCS, MGET, MSET, MSETEX, MSETNX, PSETEX, SET, SETEX, SETNX, SETRANGE, STRLEN, SUBSTR.