Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

HSCAN

Last updated 
HSCAN key cursor [MATCH pattern] [COUNT count] [NOVALUES]
Group
Hash
Complexity
O(1) for every call, O(N) for a full iteration
Arity
-3 (at least 3 words, counting the command name)
Flags
read-only
Keys
first 1, last 1, step 1
HotKV Cloud
All plans
On-Premise
no license needed

HSCAN walks the hash at key a few fields at a time. Start with cursor 0; each reply gives you the next cursor to pass in. The iteration is complete when the server returns cursor 0 again.

Fields that stay in the hash for the whole iteration are returned at least once. A field can be returned more than once, and fields added or removed during the iteration may or may not be returned, so make your processing tolerate repeats.

Options

Section titled “Options”
Option Effect
MATCH pattern Return only fields whose name matches the glob-style pattern. Filtering happens after fields are fetched, so a call can return no fields and still have a non-zero cursor.
COUNT count A hint for how much work to do per call. Default 10. Must be at least 1.
NOVALUES Return only field names, without values.

Options can be given in any order. The cursor is checked first, then the key’s type, then the options; when the key does not exist, the options are not checked and the reply is an empty page.

Return value

Section titled “Return value”
Case RESP2 RESP3
Success Two-element array: the next cursor as a bulk string, then a flat array of field, value, field, value, … (field names only with NOVALUES) Same
Key does not exist ["0", []] Same

Errors:

  • ERR invalid cursor if cursor is not an unsigned integer.
  • WRONGTYPE if key holds a value that is not a hash.
  • ERR value is not an integer or out of range if the COUNT value is not an integer, and ERR syntax error if it is below 1, an option is unknown, or an option is missing its value.
  • ERR NOSCORES option can only be used in ZSCAN if you pass NOSCORES.

Examples

Section titled “Examples”
127.0.0.1:6379> HSET user:1 name "Ada" lang "en" city "London"
(integer) 3
127.0.0.1:6379> HSCAN user:1 0
1) "0"
2) 1) "name"
   2) "Ada"
   3) "lang"
   4) "en"
   5) "city"
   6) "London"
127.0.0.1:6379> HSCAN user:1 0 MATCH "l*" NOVALUES
1) "0"
2) 1) "lang"

Compatibility

Section titled “Compatibility”

Same as Redis 7.4 and Valkey 8.

See also

Section titled “See also”

HGETALL, HKEYS, SCAN, SSCAN, ZSCAN