Query Subscriptions

Subscribe to real-time query change notifications instead of polling using the OBSERVE command

DiceDB's Observe feature lets clients subscribe to the result of a read command and receive push notifications (with result set) whenever the observed key changes, eliminating the need to poll for updates.

Use OBSERVE <cmd> key [args...] to subscribe (e.g., OBSERVE GET mykey, OBSERVE ZRANGE myzset 0 -1). The arguments after the command name are identical to the base command.

How It Works

The client sends an OBSERVE command (e.g., OBSERVE GET mykey).
DiceDB evaluates the command immediately and sends back the current result.
Whenever the observed key is modified by any write command, DiceDB re-evaluates the command and pushes a new result to the client.
If observe-debounce-period-ms is configured, rapid successive writes are coalesced and a single notification is emitted after the debounce window expires.
The client can cancel a subscription at any time with UNOBSERVE.

Response Format

Every message pushed to an observing client, both the initial result and subsequent change notifications, uses a 5-element array:

["observe", "fingerprint", "<hex-fingerprint>", "result", <command-result>]

Field	Description
`observe`	Constant string that identifies the message type
`fingerprint`	Constant label for the next field
`<hex-fingerprint>`	CRC64 hex hash of the command name + arguments; used to match notifications to subscriptions
`result`	Constant label for the next field
`<command-result>`	The return value of the observed command, identical to what the base command would return

Example

# Terminal 1 - subscribe
127.0.0.1:7379> OBSERVE GET counter
1) "observe"
2) "fingerprint"
3) "218585a66813d005"
4) "result"
5) (nil)

# Terminal 2 - write a value
127.0.0.1:7379> SET counter 42

# Terminal 1 - receives push notification automatically
1) "observe"
2) "fingerprint"
3) "218585a66813d005"
4) "result"
5) "42"

Debounce

When observe-debounce-period-ms is set to a value greater than 0 in the server configuration, multiple writes to the same key within the debounce window are merged and trigger only a single notification. This reduces noise for keys that are updated at a high rate.

observe-debounce-period-ms 50

Commands Supported

See OBSERVE for the full command reference, including syntax, return values, and the complete list of supported commands.

Cancelling Subscriptions

Use UNOBSERVE with one or more fingerprints to remove active subscriptions:

127.0.0.1:7379> UNOBSERVE 218585a66813d005
(integer) 1