BuildDocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Mzscan
Bun

method

RedisClient.zscan

key: KeyLike,
cursor: string | number,
...options: string[]
): Promise<[string, string[]]>;

Incrementally iterate sorted set elements and their scores

The ZSCAN command is used in order to incrementally iterate over sorted set elements and their scores. ZSCAN is a cursor based iterator. This means that at every call of the command, the server returns an updated cursor that the user needs to use as the cursor argument in the next call.

An iteration starts when the cursor is set to 0, and terminates when the cursor returned by the server is 0.

ZSCAN and the other SCAN family commands are able to provide to the user a set of guarantees associated to full iterations:

  • A full iteration always retrieves all the elements that were present in the collection from the start to the end of a full iteration. This means that if a given element is inside the collection when an iteration is started, and is still there when an iteration terminates, then at some point ZSCAN returned it.
  • A full iteration never returns any element that was NOT present in the collection from the start to the end of a full iteration. So if an element was removed before the start of an iteration, and is never added back to the collection for all the time an iteration lasts, ZSCAN ensures that this element will never be returned.

Options:

  • MATCH pattern: Only return elements matching the pattern (glob-style)
  • COUNT count: Amount of work done at every call (hint, not exact)
@param key

The sorted set key

@param cursor

The cursor value (use 0 to start a new iteration)

@param options

Additional ZSCAN options (MATCH pattern, COUNT hint, etc.)

@returns

Promise that resolves with a tuple [cursor, [member1, score1, member2, score2, ...]]

// Basic scan - iterate all elements
let cursor = "0";
const allElements: string[] = [];
do {
  const [nextCursor, elements] = await redis.zscan("myzset", cursor);
  allElements.push(...elements);
  cursor = nextCursor;
} while (cursor !== "0");

Referenced types

type KeyLike = string | ArrayBufferView | Blob