ZGETRANGE

Retrieves an ordered range of key-value pairs from the ZMap ordered key-value store.

Syntax

ZGETRANGE <begin> <end> [LIMIT limit] [REVERSE] [BEGIN-KEY-SELECTOR selector] [END-KEY-SELECTOR selector]

Arguments

The first two arguments are positional. The rest are keywords. Keyword names are not case-sensitive, and each keyword can appear at most once.

Argument	Type	Required	Description
begin	bytes	Yes	The start key of the range. Use * for unbounded start (from the beginning of the subspace).
end	bytes	Yes	The end key of the range. Use * for unbounded end (to the end of the subspace).
LIMIT limit	integer	No	Maximum number of key-value pairs to return. Must be greater than zero. Default is 100.
REVERSE	flag	No	When present, reverses the scan direction so results are returned in descending key order.
BEGIN-KEY-SELECTOR	string	No	Controls how the begin boundary is resolved. Default is first_greater_or_equal.
END-KEY-SELECTOR	string	No	Controls how the end boundary is resolved. Default is first_greater_than.

Key Selectors

Key selectors control exactly which keys are included at the range boundaries.

Selector	Description
first_greater_or_equal	The first key greater than or equal to the specified key. This is the default for BEGIN-KEY-SELECTOR.
first_greater_than	The first key strictly greater than the specified key. This is the default for END-KEY-SELECTOR.
last_less_than	The last key strictly less than the specified key.
last_less_or_equal	The last key less than or equal to the specified key.

Selector names are not case-sensitive.

With the default selectors, the begin key is inclusive and the end key is also inclusive. This is because first_greater_than on the end key resolves to the first key after the specified end key, and FoundationDB uses a half-open interval on resolved keys, so the specified end key itself is included.

Return Value

Array: a list of [key, value] pairs. Each pair is a two-element array containing the key and its associated value as bulk strings. Returns an empty array if no keys match the range.

Behavior

ZGETRANGE reads an ordered range of key-value pairs from the ZMap subspace of the session’s current namespace, backed by FoundationDB.

With the default key selectors, the range is both endpoints inclusive: both the begin and end keys are included in the results. FoundationDB natively uses half-open intervals; the default END-KEY-SELECTOR first_greater_than resolves the end boundary to the key after the specified end key, which makes the specified end key inclusive within that half-open interval.

The special value * can be used as a wildcard to represent an unbounded boundary:

• * as begin: starts the range from the very first key in the subspace.
• * as end: extends the range to the very last key in the subspace.

The LIMIT keyword caps the number of returned pairs. Combined with REVERSE, you can retrieve the last N entries in a range.

Key selectors allow fine-tuning of the range boundaries. For example, using BEGIN-KEY-SELECTOR first_greater_than excludes the begin key from the results.

A begin key larger than the end key is not an error. The command returns an empty array.

The command supports two transaction modes:

• Auto-commit (one-off): When no explicit transaction is active, Kronotop creates a transaction, performs the range read, and commits it immediately. This is the default mode.
• Explicit transaction: When a BEGIN has been issued, the range read is performed within the current transaction.

ZGETRANGE also supports snapshot reads. When snapshot mode is enabled on the session, the read does not conflict with concurrent writes, allowing higher throughput for read-heavy workloads.

All data is scoped to the session’s active namespace. The same keys in different namespaces refer to different entries.

Errors

Argument errors:

Error Code	Error message	Cause
ERR	wrong number of arguments for 'ZGETRANGE' command	-
ERR	Unknown '<keyword>' argument	-
ERR	Duplicate '<keyword>' argument	-
ERR	LIMIT argument must be followed by a positive integer	-
ERR	value is not an integer or out of range	-
ERR	<keyword> argument must be followed by a valid key selector	-
ERR	Unknown range key selector: '<value>'	-

Examples

Get an explicit key range (both-inclusive by default):

> ZSET key-0 "a"
OK
> ZSET key-1 "b"
OK
> ZSET key-2 "c"
OK
> ZSET key-3 "d"
OK
> ZSET key-4 "e"
OK
> ZSET key-5 "f"
OK

> ZGETRANGE key-0 key-5
1) 1) "key-0"
   2) "a"
2) 1) "key-1"
   2) "b"
3) 1) "key-2"
   2) "c"
4) 1) "key-3"
   2) "d"
5) 1) "key-4"
   2) "e"
6) 1) "key-5"
   2) "f"

Limit results:

> ZGETRANGE key-0 key-5 LIMIT 3
1) 1) "key-0"
   2) "a"
2) 1) "key-1"
   2) "b"
3) 1) "key-2"
   2) "c"

Reverse with limit (last 3 entries):

> ZGETRANGE key-0 key-5 LIMIT 3 REVERSE
1) 1) "key-5"
   2) "f"
2) 1) "key-4"
   2) "e"
3) 1) "key-3"
   2) "d"

Full subspace scan with * *:

> ZGETRANGE * *
1) 1) "key-0"
   2) "a"
2) 1) "key-1"
   2) "b"
...
6) 1) "key-5"
   2) "f"

Partial wildcard (from a specific key to the end):

> ZGETRANGE key-2 *
1) 1) "key-2"
   2) "c"
2) 1) "key-3"
   2) "d"
3) 1) "key-4"
   2) "e"
4) 1) "key-5"
   2) "f"

Use within an explicit transaction:

> BEGIN
OK

> ZSET mykey-a "alpha"
OK

> ZSET mykey-b "bravo"
OK

> COMMIT
OK

> BEGIN
OK

> ZGETRANGE mykey-a mykey-b
1) 1) "mykey-a"
   2) "alpha"
2) 1) "mykey-b"
   2) "bravo"

> COMMIT
OK