Close #14278

Overview

Rate limiters, sliding windows, request counters, and numerous other network-facing patterns share a common primitive: atomically increment a counter and set its expiration. Achieving this in Redis requires either multiple round-trips or a Lua script that bundles INCR / INCRBY / INCRBYFLOAT with EXPIRE / PEXPIRE.

We propose a new command, INCREX, that collapses this two-step pattern into a single, native, O(1) command. INCREX atomically:

1. Increments (or decrements) a key's numeric value — by integer or float.
2. Optionally enforces lower and/or upper bounds, with a configurable overflow policy (error out, saturate, or no-op), enabling built-in cap enforcement (e.g., max request count) without additional client logic.
3. Optionally sets or removes the key's expiration.
4. Returns both the new value and the actual increment applied, giving the caller immediate feedback on whether the operation was saturated or skipped.

Use Cases

Basic Usage

# Increment by 1 (default) and set a 60-second TTL.
> SET mykey 10
> INCREX mykey EX 60
1) (integer) 11        # new value
2) (integer) 1         # actual increment

# Use 0 as initial value if the key doesn't exist.
> DEL mykey
> INCREX mykey
1) (integer) 1         # new value
2) (integer) 1         # actual increment

# Default policy (OVERFLOW FAIL): exceeding a bound returns an error.
> SET mykey 5
> INCREX mykey BYINT 20 UBOUND 10
(error) value is out of bounds

# Opt into saturation with OVERFLOW SAT.
> INCREX mykey BYINT 20 UBOUND 10 OVERFLOW SAT
1) (integer) 10     # saturated to upper bound
2) (integer) 5      # only 5 was actually applied

# Skip the operation with OVERFLOW REJECT — the key and its TTL are
# untouched, and the reply reports the current value with a zero delta.
> SET mykey 5
> INCREX mykey BYINT 20 UBOUND 10 OVERFLOW REJECT
1) (integer) 5      # current (unchanged) value
2) (integer) 0      # nothing was applied

# Increment by a float
> SET mykey 1
> INCREX mykey BYFLOAT 0.5
1) "1.5"
2) "0.5"

Use Case: Rate Limiter

Before (Lua script):

-- KEYS[1] = rate limit key, ARGV[1] = limit, ARGV[2] = window in seconds
local current = redis.call('INCR', KEYS[1])
if current > tonumber(ARGV[1]) then
    return 0  -- rejected
end
if current == 1 then
    redis.call('EXPIRE', KEYS[1], ARGV[2])
end
return 1  -- allowed

Client invocation:

result = redis.eval(LUA_SCRIPT, 1, f"ratelimit:{user_id}", 100, 60)
if result == 0:
    reject_request()

After (INCREX):

new_val, actual_incr = redis.execute_command(
    "INCREX", f"ratelimit:{user_id}", "UBOUND", 100, "OVERFLOW", "REJECT", "EX", 60, "ENX"
)
if actual_incr == 0:
    # Rate limit exceeded — key left unchanged.
    reject_request()

ENX means: set expiration only if the key doesn't already have an expiration. This ensures the sliding window's TTL is only set on the first request.

Use Case: Token Bucket Refill

Refill tokens periodically up to a capacity ceiling, saturating at the cap instead of erroring:

> INCREX tokens:user123 BYINT 10 UBOUND 100 OVERFLOW SAT EX 3600 ENX
1) (integer) 10
2) (integer) 10

Tokens cannot exceed 100, and the key auto-expires after inactivity.

Use Case: Countdown / Resource Consumption

Decrement a resource counter down to zero, saturating at the floor:

> SET credits:user123 50
> INCREX credits:user123 BYINT -1 LBOUND 0 OVERFLOW SAT
1) (integer) 49
2) (integer) -1

When credits are exhausted, OVERFLOW SAT prevents negative balances without client-side checks.

Parameter Reference

Syntax

INCREX key
      [BYFLOAT increment | BYINT increment]
      [LBOUND lowerbound] [UBOUND upperbound] [OVERFLOW <FAIL | SAT | REJECT>]
      [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | PERSIST] [ENX]

Parameters

If neither BYINT nor BYFLOAT is specified, the increment defaults to integer 1.

Return Value

An array of two elements:

1. New value — the value of the key after the increment (or the unchanged current value under OVERFLOW REJECT).
2. Actual increment — the increment that was actually applied. May differ from the requested increment when OVERFLOW SAT saturates the result to a bound, and is always 0 when OVERFLOW REJECT skipped the operation.

• In integer mode (default or BYINT): both elements are integers.
• In float mode (BYFLOAT): both elements are bulk strings representing the float values on RESP2, and RESP3 Doubles on RESP3.

Overflow Policy (FAIL vs. SAT vs. REJECT)

Controlled by the optional OVERFLOW argument. A bound violation includes both exceeding an explicit LBOUND/UBOUND and overflowing the type limits when no explicit bound is given. The same policy also applies when the stored value is already out of bounds before the increment is applied (e.g. the key was set directly via SET, or the bounds have been tightened since the previous write).

• OVERFLOW FAIL (default): if the computed result would violate a bound — or if the existing value is already out of bounds — the command returns an error and the key is left unchanged. This matches the existing semantics of INCRBY / INCRBYFLOAT on overflow.
• OVERFLOW SAT: the result is silently capped at UBOUND / floored at LBOUND (or saturated to the type limits when no explicit bound is given). If the stored value is already out of bounds, it is still saturated to the nearest bound (LBOUND or UBOUND) — the second element of the reply reflects the actual delta that was applied to reach the bound, which may be larger in magnitude than the requested increment. If the delta cannot be represented as a 64-bit signed integer (default or BYINT), or would produce Infinity (BYFLOAT), an error is returned.
• OVERFLOW REJECT: the operation is silently skipped — the key value and its TTL are left unchanged, no keyspace notification is fired, and nothing is replicated. This also applies when the stored value is already out of bounds: the original value is preserved untouched. The reply is [current_value, 0], allowing the caller to detect the rejection without handling an error.

Notes

• If no expiration option is given, the key's existing TTL is preserved (like INCR).
• ENX requires one of EX/PX/EXAT/PXAT.
• If the result is saturated by OVERFLOW SAT, the expiration is still applied as specified.
• Under OVERFLOW REJECT the expiration option is ignored on the rejected branch — TTL is preserved exactly as it was before the call.
• BYINT requires an integer-typed existing value; BYFLOAT accepts both.
  Integers can be promoted to floats losslessly, but a stored float (e.g. "1.5") cannot be parsed back as an integer. This is consistent with INCR/INCRBY (integer-only) and INCRBYFLOAT (accepts both).