Incremental hash traversal
Enumerate a large hash in bounded batches without requesting every field at once.
Redis · Module
HSCAN
HSCAN incrementally iterates through the fields of a Redis hash. It supports glob matching, a COUNT hint, and NOVALUES for returning field names without values.
- Since
- 2.8.0
How it works
HSCAN incrementally walks the fields of a hash. Begin with cursor 0, optionally filter field names with a glob pattern, suggest a batch size, or request names without values; continue using each returned cursor until it becomes 0.
Syntax
HSCAN key cursor [MATCH pattern] [COUNT count] [NOVALUES]Parameters
| Name | Type | Description |
|---|---|---|
key | key | Name of the key holding the hash. |
cursor | unsigned 64-bit cursor | Cursor for the current scan; begin with 0 and reuse the returned cursor. |
MATCH pattern | glob pattern | Optional glob-style pattern for matching field names. |
COUNT count | integer | Optional hint for the number of fields returned per iteration; default 10. |
NOVALUES | flag | Optional flag that returns field names without values. |
Returns
A two-element array containing the next cursor and the scanned fields with values, or only fields when NOVALUES is used.
Key points
- The command takes a hash key and cursor, with optional MATCH, COUNT, and NOVALUES modifiers.
- Initialize the scan with cursor 0 and continue with the cursor returned by Redis.
- If COUNT is omitted, Redis uses 10 as the default iteration-size hint.
- The reply has two top-level parts: the next cursor and the scanned results.
- Normal results contain hash fields and their values as pairs.
- Each individual HSCAN call has constant time complexity; completing a full iteration is O(N).
Common mistakes
- MATCH filters field names using glob-style matching; it does not perform a general-purpose search.
- COUNT is only a per-iteration hint, so a call may return fewer or more fields than requested.
- Do not depend on the order of returned fields; collect or sort results when ordering matters.
- NOVALUES changes the response shape by omitting values, so consumers must handle fields rather than field/value pairs.
Example: Scan matching hash fields
HSET user:42 name Ada role engineer
HSCAN user:42 0 MATCH r* COUNT 10Run the command repeatedly with the returned cursor until it is 0; the example filters hash fields beginning with r.
When to use it
Pattern-filtered inspection
Select only fields whose names match a glob-style naming pattern.
Field-only enumeration
Discover hash field names while avoiding value transfer.
Interview questions
QHow does HSCAN iteration work?
HSCAN iterates a hash incrementally instead of returning the entire collection in one call. Start with cursor 0 and pass each returned cursor into the next call until the cursor returns to 0.
Follow-up: How would you avoid blocking work on a large hash? Use repeated HSCAN calls and process each batch as it arrives, rather than using a single bulk retrieval operation.
QWhat do MATCH and COUNT do?
MATCH accepts a glob-style pattern and limits returned fields to matching names. COUNT supplies a suggested number of fields for an iteration, with a default of 10.
Follow-up: Can MATCH guarantee that every call returns matching fields? No; filtering can produce an empty batch even while the cursor has not returned to 0.
QWhat does NOVALUES change?
Without NOVALUES, the response contains a cursor and scanned field/value pairs. With NOVALUES, Redis returns only field names; the option was introduced in Redis 7.4.
Follow-up: When is NOVALUES useful? Use it when values are unnecessary, reducing the response data needed to enumerate hash fields.
Related
SCANSSCANZSCANHGETHSET