Preface
Rai DS (https://github.com/raitechnology/raids) is an abreviation for Rai Distribution Server. It is the consumer end of a data hub. It is built on Rai KV, which is a shared memory Key Value store. The other components which shape a Rai data hub are the messaging codecs, Rai MD (https://github.com/raitechnology/raimd), and the multicast data distribution services, Rai MS (https://github.com/raitechnology/raims (not public yet)). These are direct analogs of a classic Market Data system, in which the center is the data hub which servers communicate typically with multicast or RDMA protocols, and the edge are the servers which manage the client consumption of data (Rai DS).
The commands are broken up into categories. Each category operates on a different data type (string, list, hash) or utilizes a special mechanism (pubsub, script, transaction). This is how Redis (https://github.com/antirez/redis) organizes it’s feature set, and Rai DS follows this convention. Much or the behavior of the commands listed here and implemented in Rai DS is derived from the documenation of Redis (https://github.com/antirez/redis-doc).
Common Return Values
These are common return values which are used by name in this document (and other Redis documents), but have a encoded representation where this is not clear.
Name | RESP encoding |
---|---|
OK |
+OK\r\n |
nil |
$-1\r\n |
"" |
$0\r\n\r\n |
null |
*-1\r\n |
[] |
*0\r\n |
0 |
:0\r\n |
1 |
:1\r\n |
-1 |
:-1\r\n |
The nil value is a null string value, and null is a null array value, but the empty string "" and the empty array [] are also valid and different than the nulls. A nil is common when the result is a bulk string, a null is common when the result is an array, and -1 is common when the result is an integer.
Notation used by the Examples
The Redis RESP protocol has 5 basic elements. Each of these is displayed in a JSON-like format that is compact and easy to parse.
Type | RESP | Display |
---|---|---|
A simple string |
+OK\r\n |
'OK' |
An error string |
-ERR reason\r\n |
`ERR reason` |
An integer value |
:1234\r\n |
1234 |
A bulk string |
$5\r\nhello\r\n |
"hello" |
A bulk array |
*2\r\n+array\r\n:1234\r\n |
['array',1234] |
Format of the Command Arity Table
Each category lists the commands in a 6 column table: command, arity, first key, last key, step, flags.
The arity is the number of terms present in a command. A positive arity is exact, a negative arity means that it must have at least this number of terms.
The first key, last key are the positions in the command terms where the keys are located. The last key may be negative, this indicates that it is a position from the end of the command.
The step is the offset added to index the next key, so this loop would find the keys in the command:
end = last_key; if ( last_key < 0 ) end = argc + last_key; /* index from argc */ for ( index = first_key; index <= end; index += step ) next_key = argv[ index ];
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
example |
-2 |
1 |
-1 |
1 |
read |
The example command has at least 2 terms, the 1st position is the first key and the last key is greater or equal to the 1st. The step between keys is 1. The following are valid commands. Note that the positions are zero based and the term at position 0 is the command.
example key_one example key_one key_two key_three
The flags indicate:
-
admin — must have admin privileges.
-
read — there are keys which need read access.
-
write — there are keys which need write access.
-
movable — some of the keys in the command are not static and need to be parsed according to the command syntax in order to locate them.
Differences with Redis
There are some differences with the way Rai DS works compared to Redis.
-
Decimal is used instead of floating point. This avoids precision errors inherent in floating point to decimal conversion.
-
The geo hash used is Uber H3 (https://eng.uber.com/h3/), which uses a hexigon based mapping, not a grid.
-
All of the blocking commands are implemented as pubsub notifications, since multiple threads are possible.
-
All of the data structures are implemented as contiguous messages, allowing speculative read operations, avoiding locking overhead.
-
Many of the memory and latency monitoring commands are different, since the basic structures of system are different.
Connection
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
2 |
0 |
0 |
0 |
||
-1 |
0 |
0 |
0 |
||
-1 |
0 |
0 |
0 |
||
2 |
0 |
0 |
0 |
echo | echo string
echo string
> echo hello "hello"
Echo the string.
The string is sent back.
ping | reply with pong
ping [string]
> ping 'PONG' > ping hello "hello"
Ping sends PONG when used without a string. Reply with the string when it is present.
Either PONG or the string.
quit | close connection
quit
> quit 'OK' (connection closed)
Close the connection.
An OK is returned, then the connection is closed.
select | choose db
select db
Change the working database to db, where db is a number between 0 and 255.
OK or range or parse error.
Server
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
-2 |
0 |
0 |
0 |
admin |
|
-1 |
0 |
0 |
0 |
||
-2 |
0 |
0 |
0 |
admin |
|
1 |
0 |
0 |
0 |
||
-1 |
0 |
0 |
0 |
admin |
|
-1 |
0 |
0 |
0 |
admin |
|
-1 |
0 |
0 |
0 |
admin |
|
-1 |
0 |
0 |
0 |
||
1 |
0 |
0 |
0 |
admin |
|
1 |
0 |
0 |
0 |
admin |
|
1 |
0 |
0 |
0 |
admin |
|
-1 |
0 |
0 |
0 |
admin |
|
1 |
0 |
0 |
0 |
client | query connected clients
client [setname name | getname | id | kill match | list match | reply state]
> client setname AAA 'OK'
Set the current connection name.
> client getname "AAA"
Get the current connection name.
> client id 12
Get the current connection id.
> client list type tcp id=12 addr=[::1]:58806 fd=14 name=AAA kind=redis age=150 idle=0 rbuf=0 rsz=16384 imsg=7 br=257 wbuf=0 wsz=5120 omsg=6 bs=1082 flags=N db=0 sub=0 psub=0 multi=-1 cmd=client id=13 addr=[::1]:58808 fd=15 name= kind=redis age=74 idle=74 rbuf=0 rsz=16384 imsg=0 br=0 wbuf=0 wsz=5120 omsg=0 bs=0 flags=N db=0 sub=0 psub=0 multi=-1 cmd=none
List the clients. The filters that match the clients which are listed are:
-
type [ tcp | udp | unix | listen | redis | pubsub | normal | http ] — filter by connection class.
-
id N — filter by id number
-
addr IP — filter by IP address
-
skipme — skip the current connection
> client kill id 13 1 > client kill type redis skipme 0
Kill clients. The filters that match the clients which are listed the same as the filters that list.
> client reply skip > ping > ping 'PONG' > client reply off > ping > client reply on 'OK' > ping 'PONG'
Alter the reply behavior of the connection. If skipped or off, output will be muted.
command | query command info
command [count | getkeys <cmd-full> | info [cmd] | help]
> command info get [["get",2,['readonly','fast'],1,1,1]] > command count 193 > command help get ['GET','key ; Get value']
Get command details and help.
Array of strings, command info.
config | query config
config [get <param> | rewrite | set <param> <value> | resetstat]
Get, set config parameters. There is no configuration, so these are not functional except get, which returns sane values.
Array of config key values.
dbsize | get number of keys
dbsize
> dbsize 299999
Get number of keys in db.
An integer number of keys.
debug | run debug
debug [object key | htstats]
> set hello world 'OK' > debug object hello key: "hello" hash: 2aa73a1eeb0b2d45:fd102121185ce157 pos: [732172]+0.0 update_time: -4s flags: string-Upd-Ival-Key-Stmp db: 0 val: 0 seqno: 3 size: 5
Get debug info about key.
> debug htstats db_num: 0 -= totals =- read: 8896064 write: 2045184 spins: 0 chains: 0 add: 303 drop: 2 expire: 0 htevict: 0 afail: 0 hit: 511040 miss: 0 cuckacq: 0 cuckfet: 0 cuckmov: 0 cuckret: 0 cuckmax: 0 -= self =- read: 8896064 write: 2045184 spins: 0 chains: 0 add: 303 drop: 2 expire: 0 htevict: 0 afail: 0 hit: 511040 miss: 0 cuckacq: 0 cuckfet: 0 cuckmov: 0 cuckret: 0 cuckmax: 0
Get information about the hash table counters.
A string description of debug info or bad command error.
flushall | remove keys
flushall [async]
Remove keys from all dbs.
OK if successful, error otherwise.
flushdb | remove keys from db
flushdb [async]
Remove keys from selected db
OK if successful, error otherwise.
info | query server stats
info [server | clients | memory | persistence | stats | replication | cpu | commandstats | cluster | keyspace]
> info server raids_version: 1.0.0-11 raids_git: fee49cdd gcc_version: 9.1.1 process_id: 32167 > info clients redis_clients: 1 pubsub_clients: 0 > info memory vm_peak: 8204MB vm_size: 8204MB > info stats ht_operations: 505M ht_chains: 1.0 ht_read: 505M ht_write: 287 > info cpu used_cpu_sys: 0.069951 used_cpu_user: 1.445196 used_cpu_total: 1.515147
Get version info and counters.
A text string with newlines that has the requested info.
monitor | monitor commands
monitor
> monitor ["pmessage","__monitor_@*","__monitor_@0__:127.0.0.1:60646", [["get","k"],"value","1580125101.975300"]]
Monitor commands executed by server from all clients. This is an
alias for psubscribe _monitor_@*
. Running once enables, running
twice disables the monitor. In order to monitor just one client, or
just one ip address, use a pattern that includes the address:
psubscribe _monitor_@0__:127.0.0.1*
An array which indicates the db number and client connected address
("__monitor_@0__:127.0.0.1:60646"
), the command executed
(["get","k"]
), and the result of executing the command ("value"
).
save | sync save
save
Synchronously save to rdb format file.
OK or error if save fails.
load | sync load
load
Synchronously load from rdb format file.
OK or error if load fails.
shutdown | shutdown server
shutdown
Shutdown server. This will cause the connected instance to quit.
time | get server time
time
> time ["1580125969","562228"]
Get server time.
An array, UTC seconds and microseconds (1 usec = 1/1000000 second).
Key
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
-2 |
1 |
-1 |
1 |
write |
|
2 |
1 |
1 |
1 |
read |
|
-2 |
1 |
-1 |
1 |
read |
|
3 |
1 |
1 |
1 |
write |
|
3 |
1 |
1 |
1 |
write |
|
2 |
0 |
0 |
0 |
read |
|
-2 |
2 |
2 |
2 |
read |
|
2 |
1 |
1 |
1 |
write |
|
3 |
1 |
1 |
1 |
write |
|
3 |
1 |
1 |
1 |
write |
|
2 |
1 |
1 |
1 |
read |
|
1 |
0 |
0 |
0 |
read |
|
3 |
1 |
2 |
1 |
write |
|
3 |
1 |
2 |
1 |
write |
|
-4 |
1 |
1 |
1 |
write |
|
-2 |
1 |
1 |
1 |
write |
|
2 |
1 |
1 |
1 |
read |
|
2 |
1 |
1 |
1 |
read |
|
-2 |
1 |
-1 |
1 |
write |
|
-2 |
0 |
0 |
0 |
read |
del | delete keys
del key [key ...]
> del h hl hl2 hl3 4
Delete one or more keys.
An integer count of the number of keys deleted is returned.
dump | dump key
dump key
> set k sophisticateduniverse 'OK' > dump k "\u0000\u0021sophisticateduniverse\t\u0000!y0\u00022ZD\u0163"
Serialize value at key.
The binary value of the key slot as a bulk string or nil when key does not exist.
exists | test if key exists
exists key [key ...]
> exists k l m 3
Test if one or more keys exists.
An integer count of the number of keys that exist.
expire | set key expire secs
expire key secs
> expire k 10 1
Set expire seconds.
The integer 1 if key expire time was set, 0 if not.
expireat | set key expire utc
expireat key stamp
> expireat k 1580076128 1 > ttl k 67
Set expire at time.
The integer 1 if key expire time was set, 0 if not.
keys | get keys matching pattern
keys pattern
> keys k* ["k","kkk","kk"]
Find all keys matching pattern.
An array of key strings that match the pattern.
object | inspect key
object [refcount key | encoding key | idletime key | freq key | help]
> object freq k nil > set k hello 'OK' > object freq k 0 > set k world 'OK' > object freq k 1 > object idletime k 6 > object encoding k "string"
Inspect key value attributes maintained and stored with the data.
If key does not exist, then nil. Otherwise an integer value indicating one of the following based on the command:
-
refcount, valid values are always 1.
-
encoding, the type of data.
-
idletime, the number seconds since the value was updated.
-
freq, the number of times key was updated. The inital value resets this to zero, and every subsequent update increments.
persist | clear expire stamp
persist key
> persist k 1
Remove expiration time.
The integer 1 if key exists was cleared, 0 if not.
pexpire | set expire millisecs
pexpire key ms
> pexpire k 10000 1 > ttl k 7 > pttl k 3986
Set expire ttl in milliseconds.
The integer 1 if key expire time was set, 0 if not.
pexpireat | set expire ms utc
pexpireat key ms
> pexpireat k 1580077977700 1 > ttl k 59 > pttl k 51395
Set expire at ms stamp.
The integer 1 if key expire time was set, 0 if not.
pttl | get the ms time left
pttl key
> pttl k 51395
Get expire time in milliseconds.
The amount of milliseconds left or -1 when key doesn’t expire, and -2 when key doesn’t exist.
randomkey | get a random key
randomkey
> randomkey "bf" > randomkey "jjj"
Get a random key.
A string key, if any exists, nil if not.
rename | rename key to new name
rename key newkey
> rename jjj j 'OK'
Rename key to a new name.
OK when successful, error otherwise.
renamenx | rename key if not exist
renamenx key newkey
> renamenx k j 0 > del j 1 > renamenx k j 1
Rename key if new key doesn’t exists.
An integer 1 if success, 0 if not, error if key doesn’t exist.
restore | restore key from dump
restore key ttl value [replace] [absttl] [idletime idle] [freq lfu]
Restore key using dump format. The value argument is in a specific binary format that is constructed by the dump command, which has a version and a crc checksum attached (not easily constructed without a program).
OK when successful, error otherwise.
touch | set last access time
touch key [key ...]
> touch j 1 > object idletime j 4
Set update time of key.
An integer 1 if success, 0 if not.
ttl | get ttl secs
ttl key
> ttl j -1 > expire j 100 1 > ttl j 98
Get expire time in seconds.
The amount of seconds left or -1 when key doesn’t expire, and -2 when key doesn’t exist.
type | get type of key
type key
> pfadd hl 1 2 3 4 5 6 10 1 > type hl 'hyperloglog'
Get the type of a key.
The type of key in a string or the string none.
unlink | delete key
unlink key [key ...]
> unlink j k l m 2
Non-blocking delete, mark deleted.
An integer count of the number of keys deleted is returned.
scan | scan matching keys
scan curs [match pat] [count int]
> scan 0 match j* count 1 ["18521679",["jjj"]] > scan 18521679 match j* count 1 ["25519714",["j"]] > scan 25519714 match j* count 1 ["0",[]]
Get the keys which match a pattern. The cursor is the offset into the scan where the results will start. If the cursor is equal to 18521679 from the example, then the match will start at the 18521679th element in the key hash.
An array within an array. The outer array is the cursor counter, the inner array is the keys matched.
String
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
3 |
1 |
1 |
1 |
write |
|
-2 |
1 |
1 |
1 |
read |
|
-2 |
1 |
1 |
1 |
write |
|
-4 |
2 |
-1 |
1 |
write |
|
-3 |
1 |
1 |
1 |
read |
|
2 |
1 |
1 |
1 |
write |
|
3 |
1 |
1 |
1 |
write |
|
2 |
1 |
1 |
1 |
read |
|
3 |
1 |
1 |
1 |
read |
|
4 |
1 |
1 |
1 |
read |
|
3 |
1 |
1 |
1 |
write |
|
2 |
1 |
1 |
1 |
write |
|
3 |
1 |
1 |
1 |
write |
|
3 |
1 |
1 |
1 |
write |
|
-2 |
1 |
-1 |
1 |
read |
|
-3 |
1 |
-1 |
2 |
write |
|
-3 |
1 |
-1 |
2 |
write |
|
4 |
1 |
1 |
1 |
write |
|
-3 |
1 |
1 |
1 |
write |
|
4 |
1 |
1 |
1 |
write |
|
4 |
1 |
1 |
1 |
write |
|
3 |
1 |
1 |
1 |
write |
|
4 |
1 |
1 |
1 |
write |
|
2 |
1 |
1 |
1 |
read |
append | append to value
append key value
> append s string 5 > append s value 9 > get s "stringvalue"
Append value to key.
The integer strlen of the key after value appended.
bitcount | count bits
bitcount key [start end]
> set s string 'OK' > bitcount s 0 0 5 > bitfield s get u8 0 115 > getrange s 0 0 "s"
Count the bits in string from byte offset start to offset end, inclusive.
An integer count of bits set in the byte range.
bitfield | manipulate bits
bitfield key [get type off] [set type off value] [incrby type off incr] [overflow wrap | sat | fail]
> bitfield bf set u8 0 1 set u8 8 2 set u8 16 3 set u8 24 4 [0,0,0,0]
Set integer value at bit offset off as type, where type is signed (iN) or unsigned (uN) with bit size 1 through 63, 64 for signed.
An array of the integers that existed before setting the new values.
> bitfield bf get u8 0 get u8 8 get u8 16 get u8 24 [1,2,3,4]
Get integer value at bit offset, using signed or unsigned type.
An array of integers that are requested.
> bitfield bf incrby u8 0 1 incrby u8 8 1 incrby u8 16 1 incrby u8 24 1 [2,3,4,5] > bitfield bf incrby u8 0 255 overflow wrap [1] > bitfield bf incrby u8 8 255 overflow sat [255] > bitfield bf incrby u8 16 255 overflow fail [nil]
Increment integer values at bit offsets. The overflow arument modifies the behavior of increment in the case that the result wraps around zero. Wrap is the default, saturate (sat) caps the value at the highest and lowest point, fail discards the new value and uses the old value, returning nil.
An array of the integers after incrementing.
bitop | bitwise operator
bitop (and | or | xor | not) dest src [src src ...]
> bitfield i set u8 0 3 [0] > bitfield j set u8 0 1 [0] > bitop xor k j i 1 > bitfield k get u8 0 [2]
Bitwise store to dest from srcs by performing logical operations on each bit.
The number of bytes stored in dest, which is the minimum size of i and j, since the trailing zeros are not stored.
bitpos | find a bit
bitpos key bit [start end]
> bitfield k set u8 0 16 [0] > bitpos k 1 0 1 4 > bitpos k 0 0 1 0
Find first bit set or clear between start offset and end offset.
The position of the bit set or clear, or -1 when not found.
decr | decr by one
decr key
> set k 10 'OK' > decr k 9 > decr k 8
Decrement integer at key by one.
The value after decrementing it. If key is created, then it is initialized to -1.
decrby | decr by integer
decrby key int
> set k 10 'OK' > decrby k -1 11 > decrby k 10 1
Decrement integer at key by the integer argument.
The value after decrementing it. If key is created, then it is initialized to the negative of the integer argument.
get | get key value
get key
> set k val 'OK' > get k "val" > del k 1 > get k nil
Get the key value.
The string value or nil when not found.
getbit | git bit at offset
getbit key off
> bitfield k set u8 0 16 [0] > getbit k 0 0 > getbit k 3 0 > getbit k 4 1
Get value at bit offset in the string stored at the key.
A 1 if the bit is set, a 0 if not set or not found.
getrange | get range in string
getrange key start end
> set k 0123456789 'OK' > getrange k 3 7 "34567" > getrange k 12 13 "" > getrange k 7 -3 "7" > getrange k 0 -1 "0123456789"
Get a substring of the string value at key. Start and/or end may be negative to index from the end of the string.
A string with the characters in the range start to end, inclusive.
getset | swap values
getset key value
> getset k 2 nil > getset k 3 "2"
Swap new value with current value and return it.
The value currently stored with the key, or nil if the key is created.
incr | incr by one
incr key
> incr k 4 > incr k 5 > del k 1 > incr k 1
Increment integer at key by one.
The value after it is incremented. If key is created, then it is initialized to 1.
incrby | incr by integer
incrby key int
> del k 1 > incrby k 100 100 > incrby k 100 200
Increment integer at key by the integer argument.
The value after it is incremented. If key is created, then it is initialized to the integer argument.
incrbyfloat | incr by decimal
incrbyfloat key decimal
> incrbyfloat n 1.1 "1.1" > incrbyfloat n 1.1 "2.2" > incrbyfloat n 1.1 "3.3"
Increment number at key by decimal value. This uses 128 bit decimal arithmetic which has a 34 digit range and an exponent from -6143 to +6144. https://en.wikipedia.org/wiki/Decimal128_floating-point_format
The number after it is incremented. If key is created, then it is initialized to the decimal argument.
mget | get multiple values
mget key [key ...]
> mset j 1 k 2 l 3 m 4 'OK' > mget j k l m mm ["1","2","3","4",nil]
Get the values of multiple keys.
An array of values or nil when key doesn’t exist or is not a string type.
mset | set multiple values
mset key val [key val ...]
> mset j 1 k 2 l 3 m 4 'OK'
Set the values of multiple keys.
OK.
msetnx | set if not exist
msetnx key val [key val ...]
> del j k l m 4 > msetnx j 1 k 2 l 3 m 4 1 > msetnx j 1 k 2 l 3 m 4 0
Set the values of keys if all keys do not exist.
If all keys are created a 1 is returned, otherwise no kesy are created and a 0 is returnd;
psetex | set with expiration
psetex key ms val
> psetex k 1580166892000 hello 'OK' > ttl k 80 > psetex k 15000 hello 'OK' > ttl k 13 > pttl k 11991
Set the value with expiration of key in milliseconds. The expiration argument is either stamp or relative time.
OK.
set | set value
set key val [ex secs] [px ms] [nx | xx]
> set k one 'OK' > set k one xx 'OK' > set k one nx nil > set k one px 15000 xx 'OK' > ttl k 11 > pttl k 4260
Set the key value optionally with expiration and nx or xx test. The nx option tests that the key does not exist before setting. The xx tests that the key does exist before setting.
OK on success, nil when failed.
setbit | set bits
setbit key off 1 | 0
> setbit k 0 1 0 > setbit k 1 1 0 > setbit k 1 0 1 > getbit k 0 1 > getbit k 1 0
Swap the value at bit offset in string with the new bit value.
A 1 or 0 is returned, the previous value held by bit.
setex | set with expiration
setex key secs val
> setex k 1580166892 hello 'OK' > ttl k 80 > setex k 15 hello 'OK' > ttl k 13 > pttl k 11991
Set the value with expiration of key in seconds. The expiration argument is either stamp or relative time.
OK.
setnx | set if not exist
setnx key val
> del k 1 > setnx k value 'OK' > setnx k value nil
Set the value if key does not exist.
OK if success, nil if key already exists.
setrange | set value range
setrange key off val
> del k 1 > setrange k 5 waterbuffalo 17 > get k "\u0000\u0000\u0000\u0000\u0000waterbuffalo"
Overwrite or create a range in a string stored with the key at the offset specified. The data implicitly created by the setrange is zero padded.
The length of key after modification.
strlen | get strlen
strlen key
> del k 1 > setrange k 5 waterbuffalo 17 > strlen k 17 > get k "\u0000\u0000\u0000\u0000\u0000waterbuffalo"
Get length of value, which is the maximum extent, not the strlen function.
The length of value, which could be 0 if the key does not exist.
List
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
-3 |
1 |
-2 |
1 |
write |
|
-3 |
1 |
-2 |
1 |
write |
|
4 |
1 |
2 |
1 |
write |
|
3 |
1 |
1 |
1 |
read |
|
5 |
1 |
1 |
1 |
write |
|
2 |
1 |
1 |
1 |
read |
|
2 |
1 |
1 |
1 |
write |
|
-3 |
1 |
1 |
1 |
write |
|
-3 |
1 |
1 |
1 |
write |
|
4 |
1 |
1 |
1 |
read |
|
4 |
1 |
1 |
1 |
write |
|
4 |
1 |
1 |
1 |
write |
|
4 |
1 |
1 |
1 |
write |
|
2 |
1 |
1 |
1 |
write |
|
3 |
1 |
2 |
1 |
write |
|
-3 |
1 |
1 |
1 |
write |
|
-3 |
1 |
1 |
1 |
write |
blpop | block and lpop list
blpop key [key ...] timeout
> brpop l m 0 ["l","one"]
Left pop the list and return the pair of list name and value. If the list is empty, block and wait for timeout seconds. When the timeout is zero, the command blocks indefinitely.
An array with the name of the list follwed by the left most item popped from the list. If timeout expires, null is returned.
brpop | block and rpop list
brpop key [key ...] timeout
> brpop l m 0 ["l","three"]
Right pop the list and return the pair of list name and value. If the list is empty, block and wait for timeout seconds. When the timeout is zero, the command blocks indefinitely.
An array with the name of the list follwed by the right most item popped from the list. If timeout expires, null is returned.
brpoplpush | block rpop then lpush
brpoplpush src dest timeout
> lpush l one 1 > brpoplpush l m 0 "one" > lrange l 0 -1 [] > lrange m 0 -1 ["one"]
Right pop the source list and left push the destination list. If source is empty, block and wait for an element. The timeout is in seconds and when it is zero, the command blocks indefinitely.
A string of the element transferred or null when timeout expires.
lindex | get list elem at index
lindex key idx
> lindex m 0 "one" > lindex m 10 nil
Get list element at index. Index starts at zero and ends at list length - 1.
A string of the element at index or nil when index is out of range.
linsert | insert list elem
linsert key before | after piv val
> linsert m after two three 3 > linsert m after four five -1 > lrange m 0 -1 ["one","two","three"]
Insert into list an value before or after the element named by piv.
The count of elements in the list after inserting the new element, or -1 when the piv is not found.
llen | get list length
llen key
> llen m 3
Get list length.
The count of elements in list, 0 if list doesn’t exist.
lpop | left pop list elem
lpop key
> lpush x one 1 > lpop x "one" > lpop x nil > type x 'none'
Left pop the element from the list. The list key is removed when there are zero elements left.
The string value of the element or nil if list doesn’t exist.
lpush | left push list elem
lpush key val [val ..]
> lpush x one two three 3
Left push elements to the list.
The length of the list after elements are added.
lpushx | left push if exists
lpushx key val [val ..]
> lpushx y one two three 0 > type y 'none' > lpushx x one two three 6
Left push elements to the list only if it exists.
The length of the list after elements are added.
lrange | get range of elems
lrange key start stop
> lrange x 0 -1 ["three","two","one","three","two","one"] > lrange x 6 10 []
Get a range of elements from the list. If list doesn’t exist or range has zero elements, an empty array is returned. A negative index starts from the end of the list: -1 is the last element, -2 is the second last element.
An array of elements between the start and stop indexes, inclusive.
lrem | remove count elems
lrem key count value
> lrange x 0 -1 ["three","two","one","three","two","one"] > lrem x 1 one 1 > lrem x 1 one 1 > lrem x 1 one 0 > lrange x 0 -1 ["three","two","three","two"]
Remove count list elements which match the value.
An integer count of elements removed.
lset | set list elem at index
lset key idx value
> lpush l one two three 3 > lset l 1 TWO 'OK' > lrange l 0 -1 ["three","TWO","one"]
Set the list element at index. Index is zero based.
OK if success, error if out of range or not found.
ltrim | trim list elems
ltrim key start stop
> lpush x one two three one two three 6 > ltrim x 4 10 'OK' > lrange x 0 -1 ["two","one"]
Trim list to range. If start is beyond the end of the list, then all elements are removed.
OK.
rpop | right pop list elem
rpop key
> rpush x two three 2 > rpop x "three" > rpop x "two" > rpop x nil > type x 'none'
Right pop the element from the list. The list key is removed when there are zero elements left.
The string value of the element or nil if list doesn’t exist.
rpoplpush | right pop left push
rpoplpush src dest
> rpush x two three 2 > rpoplpush x y "three" > rpoplpush x y "two" > rpoplpush x y nil
Right pop the source list and left push the destination list. If source is empty, return nil.
A string of the element transferred or nil.
rpush | right push elem
rpush key [val ...]
> rpush x one two three 3
Right push elements to the list.
The length of the list after elements are added.
rpushx | right push if exist
rpushx key [val ...]
> rpushx y one two three 0 > type y 'none' > rpush x one two three 3 > rpushx x one two three 6
Right push elements to the list only if it exists.
The length of the list after elements are added.
Hash
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
-4 |
1 |
1 |
1 |
write |
|
-3 |
1 |
1 |
1 |
write |
|
3 |
1 |
1 |
1 |
read |
|
3 |
1 |
1 |
1 |
read |
|
2 |
1 |
1 |
1 |
read |
|
4 |
1 |
1 |
1 |
write |
|
4 |
1 |
1 |
1 |
write |
|
2 |
1 |
1 |
1 |
read |
|
2 |
1 |
1 |
1 |
read |
|
-3 |
1 |
1 |
1 |
read |
|
-4 |
1 |
1 |
1 |
write |
|
-4 |
1 |
1 |
1 |
write |
|
4 |
1 |
1 |
1 |
write |
|
3 |
1 |
1 |
1 |
read |
|
2 |
1 |
1 |
1 |
read |
|
-3 |
1 |
1 |
1 |
read |
happend | append a value
happend key field val [val ...]
> happend h f v 1 > happend h f w 0 > hgetall h ["f","vw"]
Append a string to a field value.
An integer 1 or 0 indicating whether the field was created.
hdel | delete fields
hdel key field [field ...]
> hmset h f 1 g 2 'OK' > hdel h f g 2
Remove one or more fields from a hash set.
An integer indicating how many fields were removed.
hexists | if field exists
hexists key field
> hmset h f 1 g 2 'OK' > hexists h f 1 > hexists h h 0
Test whether field exists in hash.
An integer 1 indicating the field exists or 0 when it doesn’t.
hget | get a field value
hget key field
> hmset h f 1 g 2 'OK' > hget h f "1" > hget h h nil
Get the value associated with field.
A string value or nil when the field does not exist.
hgetall | get all field values
hgetall key
> hmset h f 1 g 2 'OK' > hgetall h ["f","1","g","2"]
Get all of the fields and values associated with the hash stored at key.
An array of field value pairs. An empty array when key doesn’t exist.
hincrby | incr field
hincrby key field int
> hmset h f 1 g 2 'OK' > hincrby h f 10 11
Add an integer value to field.
The integer value after incrementing the integer or an error if the value stored in field is not an integer.
hincrbyfloat | incr field
hincrbyfloat key field num
> hmset h f 1 g 2 'OK' > hincrbyfloat h f 123456.66 "123457.66"
Add a numeric value to field. This uses 128 bit decimal arithmetic which has a 34 digit range and an exponent from -6143 to +6144. https://en.wikipedia.org/wiki/Decimal128_floating-point_format
A string numeric value after incrementing the number or an error if the value stored in field is not a number.
hkeys | get all field keys
hkeys key
> hmset h f 1 g 2 'OK' > hkeys h ["f","g"]
Get all field keys in the hash.
An array of field names.
hlen | get number of fields
hlen key
> hmset h f 1 g 2 'OK' > hlen h 2
Get the number field value pairs in the hash.
An integer count of the number of fields.
hmget | get multiple field vals
hmget key field [field ...]
> hmset h f 1 g 2 'OK' > hmget h f g h ["1","2",nil]
Get multiple values from a hash. If a field doesn’t exist, a nil is returned.
An array of values or nil.
hmset | set multiple field vals
hmset key field value [field value ...]
> hmset h f 1 g 2 'OK' > hmset h g 3 tree 50 'OK' > hgetall h ["f","1","g","3","tree","50"]
Set multiple field value pairs in the hash.
OK.
hset | set a field value
hset key field value [field value ...]
> hset h f 1 g 2 2 > hset h g 3 tree 50 1 > hgetall h ["f","1","g","3","tree","50"]
Set multiple field value pairs in the hash. Preexisting fields will be overwritten, and new fields will be added to the hash.
An integer indicating number of fields created.
hsetnx | set if not present
hsetnx key field value
> hmset h f 1 g 2 'OK' > hsetnx h tree 50 1 > hsetnx h g 3 0 > hgetall h ["f","1","g","2","tree","50"]
Set a field in a hash only when it does not exist.
An integer 1 or 0 indicating success.
hstrlen | get strlen of field val
hstrlen key field
> hsetnx h tree 50 1 > hstrlen h tree 2
Get the string length of value stored with field, 0 if field does not exist.
An integer string length, which is the count of the 8 bit characters in the value.
hvals | get all values
hvals key
> hmset h f 1 g 2 'OK' > hvals h ["f","1","g","2"]
Get all of the values stored in the hash.
An array of all the values or nil when hash does not exist.
hscan | iterate fields
hscan key cursor [match pattern] [count int]
> hset h abc 1 abb 2 abd 3 xyz 4 zzz 5 5 > hscan h 0 match a* count 1 ["2",["abc","1"]] > hscan h 2 match a* count 1 ["3",["abb","2"]] > hscan h 3 match a* count 1 ["4",["abd","3"]] > hscan h 4 match a* count 1 ["0",[]] > hscan h 0 ["0",["abc","1","abb","2","abd","3","xyz","4","zzz","5"]] > hscan h 5 match a* count 1 ["0",[]]
Get the fields and values which match a pattern. The cursor is the offset into the scan where the results will start. If the cursor is equal to 3, then the match will start at the 3rd field in the hash.
An array within an array. The outer array is the cursor counter, the inner array is the fields and values.
Set
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
-3 |
1 |
1 |
1 |
write |
|
2 |
1 |
1 |
1 |
read |
|
-2 |
1 |
-1 |
1 |
read |
|
-3 |
1 |
-1 |
1 |
write |
|
-2 |
1 |
-1 |
1 |
read |
|
-3 |
1 |
-1 |
1 |
write |
|
3 |
1 |
1 |
1 |
read |
|
2 |
1 |
1 |
1 |
read |
|
4 |
1 |
2 |
1 |
write |
|
-2 |
1 |
1 |
1 |
write |
|
-2 |
1 |
1 |
1 |
read |
|
-3 |
1 |
1 |
1 |
write |
|
-2 |
1 |
-1 |
1 |
read |
|
-3 |
1 |
-1 |
1 |
write |
|
-3 |
1 |
1 |
1 |
read |
sadd | add to set
sadd key mem [mem ...]
> sadd s x y z 3 > sadd s z a b 2
Add one or more members to a set.
An integer count of unique members added.
scard | get member count
scard key
> sadd s x y z 3 > scard s 3
Get the count of set members.
An integer count of members.
sdiff | subtract sets
sdiff key [key ...]
> sadd s x y z 3 > sadd t x Y z 3 > sdiff s t ["y"] > sdiff t s ["Y"]
Subtract sets. Remove members of the first set using the members of the the other sets.
An array of members.
sdiffstore | subtract and store
sdiffstore dest key [key ...]
> sadd s x y z 3 > sadd t x Y z 3 > sdiffstore sd s t 1 > smembers sd ["y"] > sdiffstore td t s 1 > smembers td ["Y"]
Remove members of the first set using the members of the the other sets. Store the result in the dest key.
A count of members stored in the set at the dest key.
sinter | intersect sets
sinter key [key ...]
> sadd s x y z 3 > sadd t x Y z 3 > sinter s t ["x", "z"]
Intersect all the sets, only keep a member if it is in all sets.
An array of members.
sinterstore | intersect and store
sinterstore key [key ...]
> sadd s x y z 3 > sadd t x Y z 3 > sinterstore si s t 2 > smembers si ["x", "z"]
Intersect all the sets and store the result in the dest key.
A count of members stored in the set at the dest key.
sismember | test membership
sismember key mem
> sadd s x y z 3 > sismember s x 1 > sismember s Y 0
Test whether member is present in a set.
A 1 is returned if it is a member, a 0 if not.
smembers | get all members
smembers key
> sadd s x y z 3 > smembers s ["x","y","z"]
Get all the members in a set.
An array of set members, which could be empty if the key doesn’t exist.
smove | move member to set
smove src dest mem
> sadd s x y z 3 > sadd t x Y z 3 > smove s t x 1 > smove s t Y 0 > smove s t a 0 > smove s t y 1 > smembers s ["z"] > smembers t ["x","Y","z","y"]
Move a member to another set, which removes the member from the source and only adds it the destination if it exists in the source.
A 1 is returned if the member exists in the source and is moved and a 0 is returned if the member does not exist in the source.
spop | remove rand members
spop key [count]
> sadd s x y z 3 > sadd t x Y z 3 > spop s ["y"] > spop t 300 ["x","Y","z"] > smembers s ["x","z"] > smembers t [] > spop t []
Remove count random members from the set and return them.
An array of members removed, which may be less than count if there are not enough in the set to fulfill the total.
srandmember | get rand members
srandmember key [count]
> sadd s x y z 3 > sadd t x Y z 3 > srandmember s ["y"] > srandmember t 300 ["x","Y","z"]
Get count random members from the set and return them.
An array of members removed, which may be less than count if there are not enough in the set to fulfill the total.
srem | remove members
srem key mem [mem ...]
> sadd s x y z 3 > srem s y Y z 2
Remove one or more members from the set.
An integer count of members removed.
sunion | union sets
sunion key [key ...]
> sadd s x y z 3 > sadd t x Y z 3 > sunion s t ["x","y","Y","z"]
Union sets and return members.
An array of members.
sunionstore | union and store
sunionstore dest key [key ...]
> sadd s x y z 3 > sadd t x Y z 3 > sunionstore su s t 4 > smembers su ["x","y","Y","z"]
Union all the sets and store the result in the dest key.
A count of members stored in the set at the dest key.
sscan | iterate and match
sscan key curs [match pattern] [count cnt]
> sadd s abc abb abd xyz zzz 5 > sscan s 0 match a* count 1 ["2",["abc"]] > sscan s 2 match a* count 1 ["3",["abb"]] > sscan s 3 match a* count 1 ["4",["abd"]] > sscan s 4 match a* count 1 ["0",[]] > sscan s 0 ["0",["abc","abb","abd","xyz","zzz"]] > sscan s 5 match a* count 1 ["0",[]]
Get the fields and values which match a pattern. The cursor is the offset into the scan where the results will start. If the cursor is equal to 3, then the match will start at the 3rd member of the set.
An array within an array. The outer array is the cursor counter, the inner array are the members matched.
Sorted Set
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
-4 |
1 |
1 |
1 |
write |
|
2 |
1 |
1 |
1 |
read |
|
4 |
1 |
1 |
1 |
read |
|
4 |
1 |
1 |
1 |
write |
|
-4 |
1 |
1 |
1 |
write movable |
|
4 |
1 |
1 |
1 |
read |
|
-4 |
1 |
1 |
1 |
read |
|
-4 |
1 |
1 |
1 |
read |
|
-4 |
1 |
1 |
1 |
read |
|
-4 |
1 |
1 |
1 |
read |
|
3 |
1 |
1 |
1 |
read |
|
-3 |
1 |
1 |
1 |
write |
|
4 |
1 |
1 |
1 |
write |
|
4 |
1 |
1 |
1 |
write |
|
4 |
1 |
1 |
1 |
write |
|
-4 |
1 |
1 |
1 |
read |
|
-4 |
1 |
1 |
1 |
read |
|
3 |
1 |
1 |
1 |
read |
|
3 |
1 |
1 |
1 |
read |
|
-4 |
1 |
1 |
1 |
write movable |
|
-3 |
1 |
1 |
1 |
read |
|
-2 |
1 |
1 |
1 |
write |
|
-2 |
1 |
1 |
1 |
write |
|
-3 |
1 |
-2 |
1 |
write |
|
-3 |
1 |
-2 |
1 |
write |
zadd | add to zset
zadd key [nx | xx] [ch] [incr] score mem [score mem ...]
> zadd z 10 a 20 b 30 c 3 > zrange z 0 -1 withscores ["a","10","b","20","c","30"] > zadd z incr 1.1 a 2.2 b 3.3 c "33.3" > zrange z 0 -1 withscores ["a","11.1","b","22.2","c","33.3"] > zadd z incr 1 a "12.1" > zadd z nx 10 a 40 d 1 > zrange z 0 -1 withscores ["a","12.1","b","22.2","c","33.3","d","40"]
Add members to zset with score, optionally with a no exist (nx) flag or must exist (xx) flag. The ch flag alters the count to the number members changed, otherwise it is the count of the number of members created. The incr flag causes the score to be added to the existing instead of replacing it. The score is stored as 64 bit decimal number, which has a 16 digit precision and -383 to +384 exponent range. https://en.wikipedia.org/wiki/Decimal64_floating-point_format
A count of members created, or changed when the ch flag is set. If incr used, then the result is the new score. A string type is used for scores since it is a decimal real.
zcard | get member count
zcard key
> zadd z 10 a 20 b 30 c 3 > zrange z 0 -1 ["a","b","c"] > zcard z 3
Get a count of the number members.
An integer count, 0 if the key doesn’t exist.
zcount | count within bounds
zcount key min max
> zadd z 10 a 20 b 30 c 3 > zcount z 10 30 3 > zcount z 15 30 2
Get number of members within a bounds.
An integer count, 0 if the key doesn’t exist.
zincrby | incr score
zincrby key incr mem
> zadd z 10 a 20 b 30 c 3 > zincrby z 1.5 a "21.5" > zrange z 0 -1 withscores ["b","20","a","21.5","c","30"] > zincrby z 1.5 A "1.5" > zrange z 0 -1 withscores ["A","1.5","b","20","a","21.5","c","30"]
Add a score to member, if member doesn’t exists, create it.
The score after incrementing it.
zinterstore | intersect and store
zinterstore dest num key [key ...] [weights w [w ...]] [aggregate sum|min|max]
> zadd z1 10 a 20 b 30 c 3 > zadd z2 40 d 30 c 10 b 3 > zinterstore z3 2 z1 z2 2 > zrange z3 0 -1 withscores ["b","30","c","60"]
Intersect zsets and store in destination key. The members which are in both sets are combined into the destination set. The score is a combination of both members, depending on the weight given to each set and how it is aggregated. The default is weight 1 for each set (or no weight), and aggregating by sum.
An integer count of the members in the new set.
zlexcount | count lexical bounds
zlexcount key min max
> zadd z 10 a 10 b 10 c 10 d 4 > zlexcount z a d 4 > zcount z 10 10 4
Count members in a zset within a lexical bounds, when all elements have the same score (and this only works when all members have the same score).
An integer count of the number of members between an inclusive lexical bounds.
zrange | get members with range
zrange key start stop [withscores]
> zadd z 10 a 20 b 30 c 40 d 4 > zrange z 2 3 withscores ["c","30","d","40"] > zrange z 0 -1 ["a","b","c","d"]
Get range of members between ranked indices. The elements are sorted by score, low to high, so the 0th indexed element is the lowest score and ranked lowest. The start and stop can be negative, which would index from the highest score, so the -1 indexed element is the highest score and ranked highest.
An array of members with scores if requested.
zrangebylex | get with lex range
zrangebylex key min max [limit off cnt]
> zadd z 10 a 10 b 10 c 10 d 4 > zrangebylex z [a [b ["a","b"] > zrangebylex z - + ["a","b","c","d"] > zrangebylex z - + limit 0 1 ["a"] > zrangebylex z - + limit 1 1 ["b"]
Get members in a zset within a lexical bounds, when all elements have the same score (and this only works when all members have the same score).
An array of members.
zrevrangebylex | get rev lex range
zrevrangebylex key min max [limit off cnt]
> zadd z 10 a 10 b 10 c 10 d 4 > zrevrangebylex z [c [a ["c","b","a"] > zrevrangebylex z + - ["d","c","b","a"] > zrevrangebylex z + - limit 0 1 ["d"] > zrevrangebylex z + - limit 1 1 ["c"]
Get members in a zset within a lexical bounds high to low, in reverse, when all elements have the same score (and this only works when all members have the same score).
An array of members.
zrangebyscore | get range by score
zrangebyscore key min max [withscores]
> zadd z 10 a 20 b 30 c 40 d 4 > zrangebyscore z 10 30 ["a","b","c"] > zrangebyscore z (1 [2 withscores ["b","20"]
Get range of members between scores. The start is the lowest score and the stop is the highest score. The members are returned from the lowest to the highest, in score order.
An array of members, with scores if requested.
zrank | get rank of member
zrank key mem
> zadd z 10 a 20 b 30 c 40 d 4 > zrank z b 1 > zrank z c 2 > zrank z f nil
Get index of member, it’s rank, where it is ordered by score.
An integer indicating rank of member, nil if member not found.
zrem | remove members
zrem key mem [mem ...]
> zadd z 10 a 20 b 30 c 40 d 4 > zrem z b c f 2 > zrange z 0 -1 withscores ["a","10","d","40"]
Remove members by name.
The integer 1 if removed, 0 if not removed.
zremrangebylex | remove by lex
zremrangebylex key min max
> zadd z 10 a 10 b 10 c 10 d 4 > zremrangebylex z [a [c 3 > zrange z 0 -1 withscores ["d","10"]
Remove members from a zset within a lexical bounds high to low, in reverse, when all elements have the same score (and this only works when all members have the same score).
An integer count of the number of members removed.
zremrangebyrank | remove by rank
zremrangebyrank key start stop
> zadd z 10 a 20 b 30 c 40 d 4 > zremrangebyrank z 1 2 2 > zrange z 0 -1 withscores ["a","10","d","40"]
Remove members from a zset by rank, which is the index of order that they are sorted.
An integer count of the number of members removed.
zremrangebyscore | remove by score
zremrangebyscore key start stop
> zadd z 10 a 20 b 30 c 40 d 4 > zremrangebyscore z 10 20 2 > zrange z 0 -1 withscores ["c","30","d","40"]
Remove members from a zset by score.
An integer count of the number of members removed.
zrevrange | get reverse range
zrevrange key start stop [withscores]
> zadd z 10 a 20 b 30 c 40 d 4 > zrevrange z 2 3 withscores ["b","20","a","10"] > zrevrange z 0 -1 ["d","c","b","a"]
Get range of members between ranks. The start is the lowest index of the reverse ordered zset, the stop is the highest. The members are returned from low to high using a reverse ordered zset.
An array of members with scores if requested.
zrevrangebyscore | get reverse score
zrevrangebyscore key start stop [withscores] [limit off cnt]
> zadd z 10 a 20 b 30 c 40 d 4 > zrevrangebyscore z +inf -inf withscores ["d","40","c","30","b","20","a","10"] > zrevrangebyscore z 20 10 withscores ["b","20","a","10"] > zrevrangebyscore z (20 [10 withscores ["a","10"]
Get reverse range of members between scores. The start is the highest score and the stop is the lowest score. The members are returned from the highest to the lowest, in reverse score order.
An array of members with scores if requested.
zrevrank | get reverse rank
zrevrank key mem
> zadd z 10 a 20 b 30 c 40 d 40 > zrevrank z b 20 > zrevrank z c 10 > zrevrank z f nil
Get inverse rank index of member by name. If the order of the zset is reversed, then this is the index of the member.
An integer indicating rank of member, nil if member is not found.
zscore | get score of member
zscore key mem
> zadd z 10 a 20 b 30 c 40 d 4 > zscore z a "10" > zscore z d "40"
Get score of a member.
A string which contains a decimal value for the score.
zunionstore | store a union
zunionstore dest num key [key ...] [weights w [w ...]] [aggregate sum|min|max]
> zadd z1 10 a 20 b 30 c 3 > zadd z2 40 d 30 c 10 b 3 > zunionstore z3 2 z1 z2 4 > zrange z3 0 -1 withscores ["a","10","b","30","d","40","c","60"]
Union zsets and store in destination key. The members which are in both sets are combined into the destination set. The score is a combination of both members, depending on the weight given to each set and how it is aggregated. The default is weight 1 for each set (or no weight), and aggregating by sum.
An integer count of the members in the new set.
zscan | iterate a zset
zscan key curs [match pattern] [count cnt]
> zadd z 50 abc 40 abb 30 abd 20 xyz 10 zzz 5 > zscan z 0 match a* count 1 ["3",["abd","30"]] > zscan z 3 match a* count 1 ["4",["abb","40"]] > zscan z 4 match a* count 1 ["0",["abc","50"]] > zscan z 5 match a* count 1 ["0",[]] > zscan z 0 ["0",["zzz","10","xyz","20","abd","30","abb","40","abc","50"]] > zscan z 5 match a* count 1 ["0",[]]
Get the fields and values which match a pattern. The cursor is the offset into the scan where the results will start. If the cursor is equal to 3, then the match will start at the 3rd member of the zset.
An array within an array. The outer array is the cursor counter, the inner array are the members matched with their scores.
zpopmin | remove minimum score
zpopmin key [count]
> zadd z 10 a 20 b 30 c 40 d 4 > zpopmin z 2 ["a","10","b","20"] > zpopmin z 20 ["c","30","d","40"] > zpopmin z 20 []
Remove up to count members the lowest scores of the zset. If not enough members are currently in the set, truncate count to the number of members in the set.
An array with the set of members and the scores, in the order they were popped, an empty array is returned when the key doesn’t exist.
zpopmax | remove maximum score
zpopmax key [count]
> zadd z 10 a 20 b 30 c 40 d 4 > zpopmax z 2 ["d","40","c","30"] > zpopmax z 20 ["b","20","a","10"] > zpopmax z 20 []
Remove up to count members the highest scores of the zset. If not enough members are currently in the set, truncate count to the number of members in the set.
An array with the set of members and the scores, in the order they were popped, an empty array is returned when the key doesn’t exist.
bzpopmin | block pop min score
bzpopmin key [key ...] timeout
> bzpopmin z x 2 null > bzpopmin z x 0 ["z","a","10"] > bzpopmin z x 0
Remove lowest score member of the zset. If no members are currently in the zset, block and wait timeout seconds for a publisher to add them. Wait indefinitely when timeout is zero.
An array with the zset name and the member with scores. If timeout occurs, then null is returned.
bzpopmax | block pop max score
bzpopmax key [key ...] timeout
> bzpopmax z x 2 null > bzpopmax z x 0 ["z","d","40"] > bzpopmax z x 0
Remove hightest score member of the zset. If no members are currently in the zset, block and wait timeout seconds for a publisher to add them. Wait indefinitely when timeout is zero.
An array with the zset name and the member with scores. If timeout occurs, then null is returned.
Geo
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
-5 |
1 |
1 |
1 |
write |
|
-2 |
1 |
1 |
1 |
read |
|
-2 |
1 |
1 |
1 |
read |
|
-4 |
1 |
1 |
1 |
read |
|
-6 |
1 |
1 |
1 |
write movable |
|
-5 |
1 |
1 |
1 |
write movable |
geoadd | add a pos to key
geoadd key long lat mem [long lat mem ...]
Add longitude, latitude to key as member by converting the position to a Uber H3 hash and adding it to the set. The members are ordered by hash because hashes closest to eachother are also closest by spatual distance.
An integer is returned indicating how many members were added which did not already exist.
geohash | get hash of members
geohash key mem [mem ...]
Get geo hash string by finding the members and converting the Uber H3 hash to an encoded hash string as described in on the geohash wiki page: https://en.wikipedia.org/wiki/Geohash
An array of geohash strings, which may be nil if member is not found.
geopos | get pos of members
geopos key [mem ...]
Get geo positions of members as longitude, latitude pairs.
An array of positions or null if member is not found.
geodist | get member distance
geodist key mem1 mem2 [unit]
Compute the distance in units between members. Default unit is meters, but km, feet, miles are accepted.
A decimal string representing the distance or nil when member is not found.
georadius | get members in radius
georadius key long lat rad m | k | ft | mi [withcoord] [withdist] [withhash] [count n] [asc | desc] [storedist key]
Get all members within a radius of position. This iterates through the set using the hash of longitude latitude as the starting point. When the endpoints are found, the members are returned or stored. When storedist is used, then the distance and members are stored in a sorted set.
An array of members with optional distance, hash, and/or coordinates. The hash is an integer used by the Uber H3 library.
georadiusbymember | get members
georadiusbymember key member rad m | k | ft | mi [withcoord] [withdist] [withhash] [count n] [asc | desc] [storedist key]
Similar to georadius, get all members within a radius of an existing member. This iterates through the set using the named member as the starting point. When the endpoints are found, the members are returned or stored. When storedist is used, then the distance and members are stored in a sorted set.
An array of members with optional distance, hash, and/or coordinates. The hash is an integer used by the Uber H3 library.
Hyperloglog
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
-2 |
1 |
1 |
1 |
write |
|
-2 |
1 |
-1 |
1 |
read |
|
-2 |
1 |
-1 |
1 |
write |
pfadd | add elems to hlog
pfadd key elem [elem ...]
> pfadd hl 1 2 3 4 5 6 1
Add elems to hyperloglog table.
The integer 1 is returned when new elements are added, 0 is returned when all elements are collisions or duplicates.
pfcount | get hlog cardinality
pfcount key [key ...]
> pfadd hl 1 2 3 4 5 6 1 > pfcount hl 6
Get approximate cardinality of hyperloglog table.
An integer count of the cardinality estimate.
pfmerge | merge multiple hlogs
pfmerge dkey skey [skey ...]
> pfadd hl 1 2 3 4 5 6 10 1 > pfcount hl 7 > pfadd hl2 1 2 3 4 5 6 7 1 > pfcount hl2 7 > pfmerge hl2 hl hl2 'OK' > pfcount hl2 8
Merge multiple hyperloglog tables and write them to the destination. The dest key is not merged, it written to. A dest key can be used as a source key, but the original data in the source will be overwritten with the merged data.
OK.
Pubsub
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
-2 |
0 |
0 |
0 |
||
-2 |
0 |
0 |
0 |
||
3 |
0 |
0 |
0 |
||
-1 |
0 |
0 |
0 |
||
-2 |
0 |
0 |
0 |
||
-1 |
0 |
0 |
0 |
psubscribe | pattern subscribe
psubscribe pat [pat ...]
> psubscribe p* q* executing: ["psubscribe","p*","q*"] ["psubscribe","p*",1] ["psubscribe","q*",2] ["pmessage","p*","publius","friend"] ["pmessage","q*","qQq","OoO"]
Subscribe to patterns. The messages published to channels which match the pattern will be forwarded to the client. A message may be forwarded to the same client more than once if its channel matches multiple patterns. It is also possible to be forwarded the message again if the channel matches a subscription.
An array with the subscription and an integer which is a count of the subscriptions open.
pubsub | query pubsub info
pubsub [channels [pattern] | numsub channel | numpat]
> pubsub channels ["two","five","seven","six","one","three","four"] > pubsub channels t* ["two","three"] > pubsub channels x* []
Get the channels that are in use which match a pattern.
> pubsub numsub one two three ["one",1,"two",1,"three",1]
Get the number of subscription on each channel.
> pubsub numpat 3
Display the number of pattern subscriptions open.
publish | publish msg to channel
publish channel msg
> publish one two 1
Publish msg to channel.
A count of the times the message is forwarded to a client.
punsubscribe | pattern unsubscribe
punsubscribe [pat ...]
> psubscribe x* ["psubscribe","x*",1] > punsubscribe x* ["punsubscribe","x*",0]
Unsubscribe patterns. This cancels interest in the patterns previously subscribed. If no patterns are named, all patterns are unsubscribed.
An array with the punsubscribe and an integer count of the number of subscriptions that the client has open.
subscribe | subscribe channel
subscribe chan [chan ...]
> subscribe x ["subscribe","x",1]
Subscribe to channels. The messages published to the channels that are subscribed will be forwarded to the client.
An array with the subscription and an integer which is a count of the subscriptions open.
unsubscribe | unsubscribe channel
unsubscribe [chan ...]
> subscribe x ["subscribe","x",1] > unsubscribe x ["unsubscribe","x",0]
Unsubscribe channels. This cancels interest in the channels previously subscribed. If no channels are named, all channels are unsubscribed.
An array with the unsubscribe and an integer count of the number of subscriptions that the client has open.
Transaction
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
1 |
0 |
0 |
0 |
||
1 |
0 |
0 |
0 |
||
1 |
0 |
0 |
0 |
||
1 |
0 |
0 |
0 |
||
-2 |
1 |
-1 |
1 |
read |
discard | discard trans
discard
> multi 'OK' > incr x 'QUEUED' > discard 'OK'
Discards watch commands and discards commands queued by multi.
OK or error when no multi is started.
exec | run trans
exec
> multi 'OK' > set x 10 'QUEUED' > exec ['OK']
Execute commands queued by multi as an atomic unit.
An array of results, an element for every command, or null when a watch fails.
multi | start trans
multi
> multi 'OK' > set x 10 'QUEUED' > exec ['OK'] > multi 'OK' > set `ERR arguments format cmd: \'set\'` > set x 10 'QUEUED' > exec `ERR transaction aborted, error cmd: \'exec\'`
Start a transaction, commands issued after multi but before exec are queued execution. The syntax of the command and arguments is checked before being queued, so a command may be QUEUED or have an syntax error result.
OK.
unwatch | stop watching
unwatch
> watch x 'OK' > unwatch 'OK'
Discard watched keys.
OK.
watch | start watching
watch key [key ...]
> watch x 'OK' > multi 'OK' > set x 10 'QUEUED' > exec null
Watch keys before a multi transaction starts. After exec is issued, all watched keys are examined to make sure that none have been modified. If a watched key was modified, then the transaction aborts and null is returned.
OK.
Stream
command | arity | first key | last key | step | flags |
---|---|---|---|---|---|
-2 |
2 |
2 |
1 |
read |
|
-5 |
1 |
1 |
1 |
write |
|
-2 |
1 |
1 |
1 |
write |
|
-2 |
1 |
1 |
1 |
write |
|
-4 |
1 |
1 |
1 |
read |
|
-4 |
1 |
1 |
1 |
read |
|
2 |
1 |
1 |
1 |
read |
|
-3 |
1 |
1 |
1 |
read movable |
|
-2 |
2 |
2 |
1 |
write |
|
-3 |
1 |
1 |
1 |
write movable |
|
-4 |
1 |
1 |
1 |
write |
|
-5 |
1 |
1 |
1 |
write |
|
-3 |
1 |
1 |
1 |
read |
|
4 |
1 |
1 |
1 |
write |
xinfo | get stream info
xinfo [consumers key groupname] [groups key] [stream key]
> xinfo groups S [["name","G","consumers",2,"pending",2,"last-delivered-id", "1580474523226-0"], ["name","H","consumers",0,"pending",0,"last-delivered-id","0"]]
Get group info for a stream, which shows what the next id will be, the number of consumers and the number of pending records.
An array of groups where each group is an array of field values:
-
name — the name of the group.
-
consumers — the count of consumers.
-
pending — the count of records in the pending queue.
-
last-delivered-id — an id pointer, used to incrementally send newer records to clients.
The empty array [] is returned when the stream doesn’t exist or it does not have groups.
> xinfo stream S ["length",3,"groups",2,"last-generated-id","1580474524828-0","first-entry", ["1580474520477-0",["c","1"]],"last-entry",["1580474524828-0",["b","1"]]]
Get the info for the a stream.
An array of field values describing the stream:
-
length — the number of items in the stream
-
groups — the number of groups associated with the stream
-
last-generated-id — the id generated by the stream, it is used to ensure that the next generated id is greater than the last.
-
first-entry — the item which is at the head of the stream.
-
last-entry — the item which is at the tail of the stream.
The empty array [] is returned when the stream doesn’t exist.
> xinfo consumers S G [["name","C","pending",1,"idle",2225891],["name","D","pending",1, "idle",2221204]]
An array of consumers, which is an array of field values:
-
name — the name of the consumer.
-
pending — the count of records in the pending queue for this consumer.
-
idle — the number of milliseconds since the consumer was active
The empty array [] is returned when stream or group or consumers don’t exist.
xadd | add entry to stream
xadd key id field string [field string ...]
> xadd S * cosmic crisp "1580392806377-0" > xadd S * red delicous "1580392886784-0" > xrange S - + [["1580392806377-0",["cosmic","crisp"]], ["1580392886784-0",["red","delicious"]]]
Add field value pairs to stream. If id is the star, then it is generated using the current milliseconds, and an incrementing serial number which is only incremented within the millisecond period. If the id is not generated, it should be one or two 64 bit integers (separated by the dash) increasing in value, since an id must formed to increase over time.
The string id associated with the new entry.
xtrim | trim stream to size
xtrim key maxlen [~] count
> xadd S * cosmic crisp "1580392806377-0" > xadd S * red delicous "1580392886784-0" > xadd S * shiba inu "1580393902456-0" > xadd S * akita inu "1580393946076-0" > xlen S 4 > xtrim S maxlen 2 2 > xrange S - + [["1580393902456-0",["shiba","inu"]], ["1580393946076-0",["akita","inu"]]
Trims the stream to a maxlen items from the tail — these are the oldest entries.
An integer count of items removed from the stream.
xdel | delete from stream
xdel key id [id ...]
> xadd S * hello world "1580394876047-0" > xadd S * hello world "1580394877281-0" > xdel S 1580394876047-0 1580394877281-0 2
Delete entries from the stream which match the id strings.
An integer count of items removed from the stream.
xrange | get range of items
xrange key start end [count cnt]
> xadd S * a 1 "1580458726320-0" > xadd S * b 2 "1580458729687-0" > xadd S * c 3 "1580458733903-0" > xrange S - + [["1580458726320-0",["a","1"]],["1580458729687-0",["b","2"]], ["1580458733903-0",["c","3"]]] > xrange S 1580458729687 1580458733903 [["1580458729687-0",["b","2"]],["1580458733903-0",["c","3"]]] > xrange S 1580458733903-1 + []
Get items between start and end range. The id assigned to each item in the stream is a numerically increasing value. The start is the low id, the end is the high id. All of the items within the range are returned, up to count, if specified.
An array of items. Each item is an id followed by an array of all of the fields defined in the entry. The empty array is the result when no items are found or the key does not exist.
xrevrange | get reverse range
xrevrange key start end [count cnt]
> xadd S * a 1 "1580458726320-0" > xadd S * b 2 "1580458729687-0" > xadd S * c 3 "1580458733903-0" > xrevrange S + - [["1580458733903-0",["c","3"]],["1580458729687-0",["b","2"]], ["1580458726320-0",["a","1"]]] > xrevrange S 1580458733903 1580458729687 [["1580458733903-0",["c","3"]],["1580458729687-0",["b","2"]]] > xrevrange S + 1580458733903-1 []
Get items between start and end range. The id assigned to each item in the stream is a numerically increasing value. The start is the high id, the end is the low id. All of the items within the range are returned, up to count, if specified.
An array of items. Each item is an id followed by an array of all of the fields defined in the entry. The empty array is the result when no items are found or the key does not exist.
xlen | get stream length
xlen key
> xadd S * a 1 "1580458726320-0" > xlen S 1 > xadd S * b 2 "1580458729687-0" > xlen S 2
Get the number of items in a stream.
An integer count of the number of items, or 0 when the stream is empty or the key doesn’t exist.
xread | get next entry
xread [count cnt] [block ms] streams key [key ...] id [id ...]
> xadd S * a 1 "1580466119503-0" > xadd T * x 1 "1580466126059-0" > xread streams S T 0 0 [["S",[["1580466119503-0",["a","1"]]]], ["T",[["1580466126059-0",["x","1"]]]]]
Read new items on one or more streams which occur after the id. If all streams are exhausted of new items, then the command can block, if requested, until items are available on any stream.
An array of streams names that have items, with the array of item identfiers, then the array of field values. The result is structurally similar to the xrange command, where the results are combined over multiple streams. If no items are available, or the block timeout expires, a null is returned.
xgroup | modify group
xgroup [create key grp id [mkstream]] [setid key grp id] [destroy key grp] [delconsumer key grp cname]
> xgroup create S G 0 mkstream 'OK' > xgroup create T G 0 mkstream 'OK' > xadd S * a 1 "1580466848853-0" > xadd T * x 1 "1580466970348-0" > xreadgroup group G C streams S T > > [["S",[["1580466848853-0",["a","1"]]]], ["T",[["1580466970348-0",["x","1"]]]]]
Create a consumer group and initialize the next id that consumers will read. The option mkstream will create an empty stream if it doesn’t exit.
> xgroup setid S G 0 'OK' > xreadgroup group G D streams S T > > [["S",[["1580466848853-0",["a","1"]]]]]
Set the next id that consumers will read. Each group contains a pointer to the next id. The setid argument moves the pointer to a different location.
> xinfo groups T [["name","G","consumers",1,"pending",1, "last-delivered-id","1580466970348-0"]] > xgroup destroy T G 1 > xinfo groups T []
Destroy the group and associated consumers from the stream.
> xinfo consumers S G [["name","C","pending",1,"idle",466329], ["name","D","pending",1,"idle",378057]] > xgroup delconsumer S G D 1 > xinfo consumers S G [["name","C","pending",1,"idle",514499]]
Delete the consumer from the group. The removes any pending items that the consumer has outstanding.
-
xgroup create — OK or error if key not found and mkstream not specified.
-
xgroup setid — OK or error if group or key not found.
-
xgroup destroy — An integer 1 if group destroyed, 0 if not found.
-
xgroup delconsumer — An integer 1 if consumer destroyed, 0 if not found.
xreadgroup | read next group
xreadgroup group grp consumer [count cnt] [block ms] [noack] streams key [key ...] id [id ...]
> xadd S * a 1 "1580466848853-0" > xadd T * x 1 "1580466970348-0" > xreadgroup group G C streams S T > > [["S",[["1580466848853-0",["a","1"]]]], ["T",[["1580466970348-0",["x","1"]]]]] > xpending S G [1,"1580466848853-0","1580466848853-0",[["C","1"]]] > xpending T G [1,"1580466970348-0","1580466970348-0",[["C","1"]]] > xack S G 1580466848853-0 1 > xack T G 1580466970348-0 1 > xpending S G [0,nil,nil,nil] > xpending T G [0,nil,nil,nil]
Read streams through consumer group. This assigns items from the stream to the consumer attached to the group. A record of this read is saved with the stream until it is acked with xack, or reassigned with xclaim, or the group is destroyed with xgroup. If the id used to read the streams is >, then the next id pointer for the group is used to read the next available items. If the id is a number, then the records returned are already assigned to the consumer. This form is used to find the records after they have been delivered. If no records are available and > is used, then null is returned or if block ms is used, the command is blocked until the records become available.
An array of streams names that have items, with the array of item identfiers, then the array of field values. The result is structurally similar to the xrange command, where the results are combined over multiple streams. If no items are available, or the block timeout expires, a null is returned.
xack | consume group entry
xack key grp id [id ...]
> xreadgroup group G C streams S > [["S",[["1580466848853-0",["a","1"]]]]] > xpending S G [1,"1580466848853-0","1580466848853-0",[["C","1"]]] > xack S G 1580466848853-0 1 > xpending S G [0,nil,nil,nil] > xack S G 1580466848853-0 0
Acknowledge consumption of the id strings. The record in the stream associated with the group is removed from the pending list.
An integer count of the number of id strings acked.
xclaim | read old group entries
xclaim key grp consumer min-idle-time id [id ...] [idle ms] [time ms-utc] [retrycount cnt] [force] [justid]
> xreadgroup group G C streams S > [["S",[["1580466848853-0",["a","1"]]]]] > xclaim S G D 1 1580466848853-0 [["1580466848853-0",["a","1"]]] > xpending S G [1,"1580466848853-0","1580466848853-0",[["D","1"]]] > xack S G 1580466848853-0 1 > xpending S G [0,nil,nil,nil] > xgroup setid S G 0 'OK' > xclaim S G D 1 1580466848853-0 [] > xreadgroup group G C streams S > [["S",[["1580466848853-0",["a","1"]]]]] > xclaim S G D 10000 1580466848853-0 [] > xclaim S G D 100 1580466848853-0 [["1580466848853-0",["a","1"]]] > xclaim S G E 0 1580466848853-0 force [["1580466848853-0",["a","1"]]] > xclaim S G X 0 1580466848853-0 force justid ["1580466848853-0"] > xpending S G [1,"1580466848853-0","1580466848853-0",[["X","1"]]]
Recover items from a stream, group and assign them to a consumer. An item must be older than min-idle-time millisecs in order for xclaim to succeed. This is to prevent the race condtion of claiming items that were already claimed. The force argument causes the record to be claimed regardless of the pending state.
The records are returned when xclaim succeeds, unless justid is specified. An empty array is returned when no id succeeds.
xpending | find pending by group
xpending key grp [start end count] [consumer]
> xpending S G [1,"1580466848853-0","1580466848853-0",[["X","1"]]] > xreadgroup group G C count 1 streams S > [["S",[["1580472282479-0",["b","1"]]]]] > xreadgroup group G D count 1 streams S > [["S",[["1580472289614-0",["c","1"]]]]] > xpending S G [3,"1580466848853-0","1580472289614-0", [["X","1"],["C","1"],["D","1"]]] > xpending S G - + 10 C [["1580472282479-0","C",73749,1]] > xpending S G - + 10 D [["1580472289614-0","D",77612,1]] > xadd S * d 1 "1580472723272-0" > xreadgroup group G D count 1 streams S > [["S",[["1580472723272-0",["d","1"]]]]] > xpending S G - + 10 D [["1580472289614-0","D",397783,1],["1580472723272-0","D",4319,1]] > xpending S G [4,"1580466848853-0","1580472723272-0", [["X","1"],["C","1"],["D","2"]]]
Get the pending id records from group. Without a consumer, this requests the number of pending records, pending head and tail for the group, and the consumers pending count pairs. With the consumer, this requests all of the pending records for the consumer, up to the count specified. The id, the consumer, the pending time in milliseconds, and the delivered count are in each of the pending records.
-
xpending key grp — An array of pending count, head pending id, tail pending id, and an array off consumers, each with a count of pending records.
-
xpending key grp start end count consumer — An array of pending records belonging to the consumer requested, each with an id, an idle time, and a delivery count.
xsetid | set last entry of group
xsetid key grp id
> xinfo groups S [["name","G","consumers",0,"pending",0, "last-delivered-id","1580474520477-0"]] > xsetid S G 0 'OK' > xinfo groups S [["name","G","consumers",0,"pending",0,"last-delivered-id","0"]]
Set the next id of a group associated with a stream.
OK if success, error when key or group doesn’t exist.