Skip to content
DiceDB

PFCOUNT.WATCH

The PFCOUNT.WATCH command is a novel feature designed to provide real-time updates to clients whenever the cardinality of a HyperLogLog changes. This enables clients to track approximate set cardinality in real-time as new data is added or merged.

Protocol Support

ProtocolSupported
TCP-RESP✅
HTTP❌
WebSocket❌

Syntax

Terminal window
PFCOUNT.WATCH <key>

Parameters

ParameterDescriptionTypeRequired
keyThe key of the HyperLogLog the client wants to monitorStringYes

Return Value

ConditionReturn Value
Command is successfulReturns a message indicating subscription, similar to subscribe

Behavior

  • The client establishes a subscription to the specified HyperLogLog key.
  • The current cardinality of the HyperLogLog is sent to the client.
  • DiceDB continuously monitors the specified key for changes in its cardinality.
  • Updates are triggered by operations such as PFADD and PFMERGE that affect the cardinality.
  • Whenever the cardinality of the HyperLogLog changes, the updated value is sent to the client.

Errors

  1. Missing Key
    • Error Message: (error) ERROR wrong number of arguments for 'pfcount.watch' command
    • Occurs if no key is provided.

Example Usage

Basic Usage

Here’s an example of using the PFCOUNT.WATCH command to monitor the approximate cardinality of a HyperLogLog in real-time.

Terminal window
127.0.0.1:7379> PFCOUNT.WATCH users:hll
Press Ctrl+C to exit watch mode.
0

This query does the following:

  • Monitors the HyperLogLog key users:hll.

When the HyperLogLog is updated using the following commands from another client:

Terminal window
127.0.0.1:7379> PFADD users:hll "user1"
OK
127.0.0.1:7379> PFADD users:hll "user2" "user3"
OK
127.0.0.1:7379> PFADD users:hll "user4"
OK
127.0.0.1:7379> PFADD other:hll "user5"
OK
127.0.0.1:7379> PFMERGE users:hll users:hll other:hll
OK

The subscribing client will receive messages similar to the following:

Terminal window
127.0.0.1:7379> PFCOUNT.WATCH users:hll
Press Ctrl+C to exit watch mode.
0
1
3
4
5
  • The PFADD commands add elements to the users:hll key, incrementally increasing the cardinality.
  • The PFMERGE command merges users:hll with other:hll, updating the cardinality of users:hll based on the union of both HyperLogLogs.

Notes

Use the PFCOUNT.UNWATCH command to unsubscribe from a HyperLogLog key. This will stop the client from receiving updates on the cardinality. Refer to the PFCOUNT.UNWATCH command documentation for more details.

The following commands are related to PFCOUNT.WATCH: