Redis subkey notifications

Monitor changes to individual subkeys in real time

Subkey notifications, added in Redis 8.8, extend Redis's existing keyspace notification system to include the key, the subkey (for example, the field for hashes, the path for JSON documents, and the element for arrays), and the event type.

With standard keyspace notifications, when a hash field is modified via HSET, HDEL, or HEXPIRE, the subscriber receives the key name and the event type but not which specific fields were affected. Subkey notifications solve this by carrying the affected field names in the message payload.

Subkey notifications are delivered through Pub/Sub channels and are independent of the standard keyspace/keyevent notification channels. Enabling subkey notifications does not implicitly enable standard keyspace notifications, and vice versa.

Note: Redis Pub/Sub is fire and forget. If your Pub/Sub client disconnects and reconnects later, all events delivered during the disconnection period are lost.

Notification channels

Four new channel types are available, each suited to a different subscription pattern:

Design rationale:

• Subkeyspace (__subkeyspace@<db>__:<key>): Subscribe to a specific key; each message contains an event type and subkey names.
• Subkeyevent (__subkeyevent@<db>__:<event>): Subscribe to a specific event type; each message contains a key name and subkey names.
• Subkeyspaceitem (__subkeyspaceitem@<db>__:<key>\n<subkey>): Subscribe to a specific key and subkey name combination; each message contains an event type.
• Subkeyspaceevent (__subkeyspaceevent@<db>__:<event>|<key>): Subscribe to a specific event and key combination; each message contains subkey names.

Subkeys in the payload are encoded in a length-prefixed format (<len>:<subkey>) to support binary-safe subkey names that may contain delimiter characters.

Safeguards:

• Events whose name contains | are skipped for the __subkeyspace and __subkeyspaceevent channels to avoid parsing ambiguity.
• Keys containing \n are skipped for the __subkeyspaceitem channel because newline is the key/subkey separator.
• Subkey events are only published when at least one subkey is present.

Configuration

Subkey notifications are controlled by the existing notify-keyspace-events configuration string. Four new flag characters are added:

S     Subkeyspace events, published with __subkeyspace@<db>__ prefix.
T     Subkeyevent events, published with __subkeyevent@<db>__ prefix.
I     Subkeyspaceitem events, published with __subkeyspaceitem@<db>__ prefix.
V     Subkeyspaceevent events, published with __subkeyspaceevent@<db>__ prefix.
h     Hash commands.

These flags are independent from the existing key-level flags (K, E, and so on). You may enable any combination. For example, to enable only the subkeyspace and subkeyevent channels:

$ redis-cli config set notify-keyspace-events ST

To enable all four subkey channel types:

$ redis-cli config set notify-keyspace-events STIV

Commands emitting subkey notifications

The following commands emit subkey notifications. Currently, only hash commands are supported; support for additional data types is planned for future releases.

Watching events in real time

To observe subkey notifications, enable the desired channel types and use redis-cli to subscribe with a glob pattern:

$ redis-cli config set notify-keyspace-events ST
$ redis-cli --csv psubscribe '__subkey*'
Reading messages... (press Ctrl-C to quit)
"psubscribe","__subkey*",1

Then, in another terminal, run a command:

$ redis-cli hset myhash field1 val1 field2 val2

You will see messages similar to the following:

"pmessage","__subkey*","__subkeyspace@0__:myhash","hset|7:field1,7:field2"
"pmessage","__subkey*","__subkeyevent@0__:hset","5:myhash|7:field1,7:field2"