INCREX

Usage:
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 ]
Complexity:
O(1)
Since:
9.2.0
ACL Categories:
@fast, @string, @write

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.

Options

Condition

  • NX -- Only perform the operation if the key does not already exist.
  • XX -- Only perform the operation if the key already exists.

Expiration

  • 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.

Increment

  • BYINT increment -- Increment by a 64 bit signed integer.
  • BYFLOAT increment -- Increment by a floating-point number.

Bounds

  • 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].

Reply

Array: a two-element array of Integers, or of Doubles when BYFLOAT is used.

  1. The value of the key after the operation. If the increment was not applied, this is the current value of the key.
  2. The increment that was actually applied. This is 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.

Examples

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

Pattern: Fixed-window rate limiter

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.

Pattern: Bounded 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.