website/docs/commands/garnet-specific.md
Apart from Garnet's server extensions, we support many API calls that are not available in other RESP servers. These are described below.
COMMITAOF [DBID]
Issues a manual commit of the append-only-file (for all active databases in the Garnet instance). This is useful when auto-commits are turned off, but you need the system to commit at specific times. If a DB ID is specified, a manual commit of the append-only-file of that specific database will be issues.
Simple string reply: OK.
HCOLLECT key [key ...]
Manualy trigger cleanup of expired field from memory for a given Hash set key.
Use * as the key to collect it from all hash keys.
Simple reply: OK response Error reply: ERR HCOLLECT scan already in progress
ZCOLLECT key [key ...]
Manualy trigger cleanup of expired member from memory for a given Hash set key.
Use * as the key to collect it from all sorted set keys.
Simple reply: OK response Error reply: ERR ZCOLLECT scan already in progress
COSCAN key cursor [MATCH pattern] [COUNT count] [NOVALUES]
Custom Object Scan is similar to HSCAN and SSCAN. It iterates over the fields and values of a custom object stored at a given key.
The match parameter allows to apply a filter to elements after they have been retrieved from the collection. The count option sets a limit to the maximum number of items returned from the server to this command. This limit is also set in conjunction with the object-scan-count-limit of the global server settings.
You can use the NOVALUES option to make Garnet return only the keys without their corresponding values.
Configures a server as secondary of another, or promotes it to a primary. Same as REPLICAOF.
This allows registering specific custom commands and transactions implemented in C#, in a server side DLL library. See this page for details.
RUNTXP txid [args]
Runs the specific custom transactional procedure indetified by its ID.
WATCHMS key [key ...]
Same as WATCH, but specifies that the key holds a raw string value.
WATCHOS key [key ...]
Same as WATCH, but specifies that the key holds an object value.
Async interface to Garnet when accessing larger-than-memory data. See this link for details.
This the equivalent of MODULE LOAD in the original RESP protocol. This loads a self-contained module in which the module
initialization code registers all relevant commands and transactions automatically. See this page
for details.
EXPDELSCAN [dbid]
Scans the mutable region of the store and deletes all expired keys on demand. This lets you trigger expired-key deletion yourself (for example, from your own scheduler tuned to your workload) rather than relying on the background scan.
dbid selects the logical database to scan (default: 0).
This command is rejected when the background expired-key deletion scan is enabled, that is, when the ExpiredKeyDeletionScanFrequencySecs (--expired-key-deletion-scan-freq) option is greater than 0.
Array reply: two integers — the number of expired records deleted, followed by the number of records scanned.
Error reply: ERR Cannot execute EXPDELSCAN with background expired key deletion scan enabled.
Garnet provides support for ETags on raw strings. By using the ETag-related commands outlined below, you can associate any string based key-value pair inserted into Garnet with an automatically updated ETag.
Compatibility with non-ETag commands and the behavior of data inserted with ETags are detailed at the end of this document.
To initialize a key value pair with an ETag, use the SETWITHETAG command. You can also take any existing Key value pair and call SETIFMATCH with the ETag argument as 0 (Any key value pair without an explicit ETag has an ETag of 0 implicitly). Read more about Etag use cases and patterns here
SETWITHETAG key value [EX seconds | PX milliseconds]
Set key to hold the string value along with an ETag. If the key already holds a value, it is overwritten. If the key had an existing ETag, the ETag is incremented; otherwise, a new ETag of 1 is assigned.
Options:
GETWITHETAG key
Retrieves the value and the ETag associated with the given key.
One of the following:
SETIFMATCH key value etag [EX seconds | PX milliseconds] [NOGET]
Sets/updates a key value pair with the given etag only if (1) the etag given in the request matches the already existing etag ; or (2) there was no existing value; or (3) the existing value was not associated with any etag and the sent etag was 0.
Options:
SETIFGREATER key value etag [EX seconds | PX milliseconds] [NOGET]
Sets/updates a key value pair with the given etag only if (1) the etag given in the request is greater than the already existing etag ; or (2) there was no existing value; or (3) the existing value was not associated with any etag and the sent etag was greater than 0.
Options:
GETIFNOTMATCH key etag
Retrieves the value if the ETag associated with the key has changed; otherwise, returns a response indicating no change.
One of the following:
DELIFGREATER key etag
Deletes a key only if the provided Etag is strictly greater than the existing Etag for the key.
ETags are currently not supported for servers running in Cluster mode. This will be supported soon.
:::warning Important: Key Partitioning Required All non-ETag commands (SET, GET, APPEND, INCR, MSET, BITOP, RENAME, etc.) are completely ETag-blind. They do not read, check, update, or preserve ETags.
Users MUST partition their keys: use ONLY ETag commands (SETWITHETAG, GETWITHETAG, SETIFMATCH, SETIFGREATER, GETIFNOTMATCH, DELIFGREATER) on ETag-managed keys.
Mixing ETag and non-ETag commands on the same key (e.g., using SET on a key created with SETWITHETAG) will result in undefined ETag behavior — the ETag may be lost, stale, or corrupted. This is by design for maximum performance: non-ETag commands pay zero overhead for ETag functionality.
:::
Correct usage:
# ETag keys — use only ETag commands
SETWITHETAG etag:user:1 "data" # Initialize with ETag
GETWITHETAG etag:user:1 # Read with ETag
SETIFMATCH etag:user:1 "new" 1 # Conditional update
# Non-ETag keys — use normal commands
SET user:2 "data"
GET user:2
APPEND user:2 " more"
Incorrect usage (undefined behavior):
SETWITHETAG mykey "data" # Sets ETag
SET mykey "other" # ETag behavior is UNDEFINED
GETWITHETAG mykey # May return stale/missing ETag
ZEXPIRE key seconds [NX | XX | GT | LT] MEMBERS nummembers member [member ...]
Sets a timeout on one or more members of a sorted set key. After the timeout has expired, the members will automatically be deleted. The timeout is specified in seconds.
The command supports several options to control when the expiration should be set:
The NX, XX, GT, and LT options are mutually exclusive.
Array reply: For each member, returns:
ZEXPIREAT key unix-time-seconds [NX | XX | GT | LT] MEMBERS nummembers member [member ...]
Sets an absolute expiration time (Unix timestamp in seconds) for one or more sorted set members. After the timestamp has passed, the members will automatically be deleted.
The command supports several options to control when the expiration should be set:
The NX, XX, GT, and LT options are mutually exclusive.
Array reply: For each member, returns:
ZPEXPIRE key milliseconds [NX | XX | GT | LT] MEMBERS nummembers member [member ...]
Similar to HEXPIRE but the timeout is specified in milliseconds instead of seconds.
The command supports several options to control when the expiration should be set:
The NX, XX, GT, and LT options are mutually exclusive.
Array reply: For each member, returns:
ZPEXPIREAT key unix-time-milliseconds [NX | XX | GT | LT] MEMBERS nummembers member [member ...]
Similar to HEXPIREAT but uses Unix timestamp in milliseconds instead of seconds.
The command supports several options to control when the expiration should be set:
The NX, XX, GT, and LT options are mutually exclusive.
Array reply: For each member, returns:
ZTTL key MEMBERS nummembers member [member ...]
Returns the remaining time to live in seconds for one or more sorted set members that have a timeout set.
Array reply: For each member, returns:
ZPTTL key MEMBERS nummembers member [member ...]
Similar to HTTL but returns the remaining time to live in milliseconds instead of seconds.
Array reply: For each member, returns:
ZEXPIRETIME key MEMBERS nummembers member [member ...]
Returns the absolute Unix timestamp (in seconds) at which the specified sorted set members will expire.
Array reply: For each member, returns:
ZPEXPIRETIME key MEMBERS nummembers member [member ...]
Similar to HEXPIRETIME but returns the expiry timestamp in milliseconds instead of seconds.
Array reply: For each member, returns:
ZPERSIST key MEMBERS nummembers member [member ...]
Removes the expiration from the specified sorted set members, making them persistent.
Array reply: For each member, returns:
ZCOLLECT key [key ...]
Manualy trigger cleanup of expired member from memory for a given Hash set key.
Use * as the key to collect it from all sorted set keys.
Simple reply: OK response Error reply: ERR ZCOLLECT scan already in progress