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.
FORCEGC [generation]
Invoke garbage collection on the server side. Optionally, specify the generation level for the collection. For more information, see this article.
Simple string reply: OK.
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 is only present in the main (raw string) store.
WATCHOS key [key ...]
Same as WATCH, but specifies that the key is only present in the object store.
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.
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 you can use either the SET command with the newly added "WITHETAG" optional flag, or you can 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
SET key value [NX | XX] [EX seconds | PX milliseconds] [KEEPTTL] WITHETAG
Set key to hold the string value along with an ETag. If key already holds a value, it is overwritten, regardless of its type. Any previous time to live associated with the key is discarded on successful SET operation.
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.
Below is the expected behavior of ETag-associated key-value pairs when non-ETag commands are used.
MSET, BITOP: These commands will replace an existing ETag-associated key-value pair with a non-ETag key-value pair, effectively removing the ETag.
SET: Only if used with additional option "WITHETAG" will calling SET update the etag while inserting the new key-value pair over the existing key-value pair.
RENAME: RENAME takes an option for WITHETAG. When called WITHETAG it will rename the key with an etag if the key being renamed to did not exist, else it will increment the existing etag of the key being renamed to.
Custom Commands: While etag based key value pairs can be used blindly inside of custom transactions and custom procedures, ETag set key value pairs are not supported to be used from inside of Custom Raw String Functions.
All other commands will update the etag internally if they modify the underlying data, and any responses from them will not expose the etag to the client. To the users the etag and it's updates remain hidden in non-etag commands.
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