CLIENT TRACKING

CLIENT TRACKING ON makes HotKV remember which keys this connection reads, and send the connection an invalidation when one of them changes. A client can then keep the values it read in its own memory and drop each one when it is told the key changed. OFF stops it. The client-side caching guide explains the model and shows it at work.

Options

Option	Effect
REDIRECT client-id	Send the invalidations to the connection with this id (see CLIENT ID) instead of this one. That connection must exist when the command runs. Needed on a RESP2 connection, which cannot be pushed to.
BCAST	Tell the client of every key that starts with one of its prefixes, whether it read the key or not. Nothing is remembered per key.
PREFIX prefix	A key prefix for BCAST. Can be repeated. Without a prefix, BCAST covers every key.
OPTIN	Only remember the keys read by a command that comes right after CLIENT CACHING YES.
OPTOUT	Remember the keys of every read except a command that comes right after CLIENT CACHING NO.
NOLOOP	Leave out the changes made by this connection’s own commands.

Rules:

• PREFIX needs BCAST.
• BCAST cannot be combined with OPTIN or OPTOUT, and OPTIN cannot be combined with OPTOUT.
• The prefixes of one client must not overlap: a prefix that starts with another, or the same prefix twice, is refused.
• While tracking is on, BCAST cannot be switched on or off, and OPTIN and OPTOUT cannot be switched for each other. Turn tracking off first.
• CLIENT TRACKING ON on a connection that already tracks replaces its redirect and options (and clears a broken redirect) and adds any new prefixes. Asking for BCAST with no prefix adds the empty prefix, which covers every key, even to a client that had other prefixes.
• A connection stops tracking with OFF, with RESET, or when it closes.

Return value

Simple string OK, in RESP2 and RESP3. The invalidations come later, as pushes on a RESP3 connection, or as messages on __redis__:invalidate on a connection a RESP2 client redirects to.

Errors:

Error	Cause
ERR syntax error	An unknown option, or something other than ON or OFF where it belongs.
ERR wrong number of arguments for 'client|tracking' command	Nothing after CLIENT TRACKING.
ERR value is not an integer or out of range	The REDIRECT id is not an integer.
ERR The client ID you want redirect to does not exist	No connection has that id.
ERR A client can only redirect to a single other client	REDIRECT was given twice.
ERR PREFIX option requires BCAST mode to be enabled	PREFIX without BCAST.
ERR OPTIN and OPTOUT are not compatible with BCAST	BCAST with OPTIN or OPTOUT.
ERR You can't specify both OPTIN mode and OPTOUT mode	Both given.
ERR You can't switch BCAST mode on/off before disabling tracking for this client, and then re-enabling it with a different mode.	BCAST differs from the mode tracking is already in.
ERR You can't switch OPTIN/OPTOUT mode before disabling tracking for this client, and then re-enabling it with a different mode.	OPTIN or OPTOUT differs from the one already on.
ERR Prefix 'a:' overlaps with another provided prefix 'a:b:'. Prefixes for a single client must not overlap.	Two prefixes in the command overlap. The text names both.
ERR Prefix 'user:x' overlaps with an existing prefix 'user:'. Prefixes for a single client must not overlap.	A prefix overlaps one the client already has.

Examples

A RESP3 connection, told of a change:

# Connection A (after HELLO 3)
127.0.0.1:6379> CLIENT TRACKING ON
OK
127.0.0.1:6379> GET user:1
"alice"

# Connection B
127.0.0.1:6379> SET user:1 bob
OK

# Connection A is sent, without asking:
push> 1) "invalidate"
      2) 1) "user:1"

Broadcasting two prefixes, and what the options refuse:

127.0.0.1:6379> CLIENT TRACKING ON BCAST PREFIX user: PREFIX order:
OK
127.0.0.1:6379> CLIENT TRACKING ON BCAST PREFIX user:x
(error) ERR Prefix 'user:x' overlaps with an existing prefix 'user:'. Prefixes for a single client must not overlap.
127.0.0.1:6379> CLIENT TRACKING ON
(error) ERR You can't switch BCAST mode on/off before disabling tracking for this client, and then re-enabling it with a different mode.
127.0.0.1:6379> CLIENT TRACKING OFF
OK
127.0.0.1:6379> CLIENT TRACKING ON PREFIX a:
(error) ERR PREFIX option requires BCAST mode to be enabled

A RESP2 connection redirecting to a subscriber (connection 52):

127.0.0.1:6379> CLIENT TRACKING ON REDIRECT 52
OK

Compatibility

The options, replies and error texts follow Redis 8 and Valkey 9. Tracking is per node; see the guide for clusters and replicas.

See also

CLIENT CACHING, CLIENT TRACKINGINFO, CLIENT GETREDIR, CLIENT ID, Client-side caching