redis API reference
A Redis client speaking RESP2 (the REdis Serialization Protocol) over the net system library. Commands go out as RESP arrays of bulk strings; replies (+OK, -ERR, :int, $bulk, *array) parse back into a Reply. Typed per-command helpers (get / set / incr / keys / ...) keep the common path fully typed; command is the generic escape hatch for anything else. A -ERR reply throws a catchable Error (kind "redis"). The reply parser frames over bytes and counts bulk-string lengths in bytes, so a value whose byte length differs from its rune length (any non-ASCII UTF-8 text) is read byte-exact. Needs the default jennifer binary (uses net).
Import with import "redis.j" as redis;. See the redis guide for prose and examples.
Functions
redis.command(session as Session, args as list of string)
Send one command (its arguments) and return the reply.
Parameters
session{Session}- the open sessionargs{list of string}- the command name and its arguments
Returns {Reply} - the parsed reply
Throws
{Error}- kind "redis" on a-ERRreply
redis.connect(opts as Options)
Open a session, authenticating and selecting a database when set.
Parameters
opts{Options}- the connection settings
Returns {Session} - the open session
redis.decr(session as Session, key as string)
Atomically decrement key and return the new value.
Parameters
session{Session}- the open sessionkey{string}- the counter key
Returns {int} - the new value
redis.del(session as Session, key as string)
Delete key and return the number of keys removed (0 or 1).
Parameters
session{Session}- the open sessionkey{string}- the key to delete
Returns {int} - the number of keys removed (0 or 1)
redis.discard(session as Session)
Discard the queued transaction (DISCARD).
Parameters
session{Session}- the open session
redis.exec(session as Session)
Execute the queued transaction (EXEC) and return one reply per queued command, in order. An aborted transaction (a nil EXEC reply) yields an empty list.
Parameters
session{Session}- the open session
Returns {list of Reply} - the queued commands' replies
redis.exists(session as Session, key as string)
Report whether key is present.
Parameters
session{Session}- the open sessionkey{string}- the key to test
Returns {bool} - whether the key exists
redis.get(session as Session, key as string)
Return the string value of key, or "" when the key is missing.
Parameters
session{Session}- the open sessionkey{string}- the key to read
Returns {string} - the value, or "" when missing
redis.getBytes(session as Session, key as string)
Return the raw bytes value of key, or empty bytes when the key is missing (use exists to tell an empty value from a missing key). The byte-exact counterpart to get: it never UTF-8-decodes, so a binary value stored with setBytes round-trips exactly.
Parameters
session{Session}- the open sessionkey{string}- the key to read
Returns {bytes} - the value, or empty bytes when missing
Throws
{Error}- kind "redis" on a-ERRreply
redis.hdel(session as Session, key as string, field as string)
Delete field from hash key (HDEL); returns the number removed (0 or 1).
Parameters
session{Session}- the open sessionkey{string}- the hash keyfield{string}- the field to delete
Returns {int} - the number of fields removed
redis.hget(session as Session, key as string, field as string)
Return hash key's field (HGET), or "" when the field or key is missing.
Parameters
session{Session}- the open sessionkey{string}- the hash keyfield{string}- the field name
Returns {string} - the value, or "" when missing
redis.hgetAll(session as Session, key as string)
Return every field and value of hash key (HGETALL) as a map of string to string (empty when the key is missing).
Parameters
session{Session}- the open sessionkey{string}- the hash key
Returns {map of string to string} - the field -> value pairs
redis.hset(session as Session, key as string, field as string, value as string)
Set hash key's field to value (HSET); returns the number of fields newly created (0 when it already existed and was updated).
Parameters
session{Session}- the open sessionkey{string}- the hash keyfield{string}- the field namevalue{string}- the field value
Returns {int} - the number of new fields (0 or 1)
redis.incr(session as Session, key as string)
Atomically increment key and return the new value.
Parameters
session{Session}- the open sessionkey{string}- the counter key
Returns {int} - the new value
redis.keys(session as Session, pattern as string)
Return the keys matching a glob pattern (e.g. "", "user:").
Parameters
session{Session}- the open sessionpattern{string}- the glob pattern
Returns {list of string} - the matching keys
redis.llen(session as Session, key as string)
Return the length of list key (LLEN); 0 when the key is missing.
Parameters
session{Session}- the open sessionkey{string}- the list key
Returns {int} - the list length
redis.lpop(session as Session, key as string)
Remove and return the first element of list key (LPOP), or "" when empty.
Parameters
session{Session}- the open sessionkey{string}- the list key
Returns {string} - the popped element, or "" when the list is empty
redis.lpush(session as Session, key as string, value as string)
Prepend value to list key (LPUSH); returns the list's new length.
Parameters
session{Session}- the open sessionkey{string}- the list keyvalue{string}- the value to prepend
Returns {int} - the new list length
redis.lrange(session as Session, key as string, start as int, stop as int)
Return the elements of list key from start to stop inclusive (LRANGE; negative indices count from the end, so 0, -1 is the whole list).
Parameters
session{Session}- the open sessionkey{string}- the list keystart{int}- the start indexstop{int}- the stop index (inclusive)
Returns {list of string} - the elements in range
redis.multi(session as Session)
Begin a transaction (MULTI). Commands issued after this are queued (each replies "+QUEUED") until exec runs them atomically or discard drops them.
Parameters
session{Session}- the open session
redis.ping(session as Session)
Return the server's PONG (a liveness check).
Parameters
session{Session}- the open session
Returns {string} - the server's reply ("PONG")
redis.pipeline(session as Session, commands as list of list of string)
Send several commands in one write and read exactly one reply per command (a single network round trip). Unlike command, a -ERR reply does not throw - each command's outcome is returned in order, so inspect each Reply.
Parameters
session{Session}- the open sessioncommands{list of list of string}- each command as an argument list
Returns {list of Reply} - one reply per command, in order
redis.psubscribe(session as Session, patterns as list of string)
Subscribe to one or more glob patterns (e.g. "news.*").
Parameters
session{Session}- the open sessionpatterns{list of string}- the patterns to subscribe to
redis.publish(session as Session, channel as string, message as string)
Publish message to channel and return the number of subscribers that received it. Runs on an ordinary (non-subscribed) connection.
Parameters
session{Session}- the open sessionchannel{string}- the channel to publish tomessage{string}- the message body
Returns {int} - the number of subscribers that received the message
redis.punsubscribe(session as Session, patterns as list of string)
Unsubscribe from the given patterns, or from all patterns when the list is empty.
Parameters
session{Session}- the open sessionpatterns{list of string}- the patterns to leave ([] means all)
redis.quit(session as Session)
End the session and close the connection.
Parameters
session{Session}- the open session
redis.receiveMessage(session as Session)
Block until the next message / pmessage push arrives, skipping the (un)subscribe confirmation frames. Wrap the call in a spawn to receive concurrently with the rest of the program; the per-read idle timeout (Session.timeout, milliseconds) bounds the wait and raises a catchable error on a stall.
Parameters
session{Session}- the open, subscribed session
Returns {Message} - the next channel / pattern push
Throws
{Error}- kind "redis" on a server error reply or a closed connection
redis.rpush(session as Session, key as string, value as string)
Append value to list key (RPUSH); returns the list's new length.
Parameters
session{Session}- the open sessionkey{string}- the list keyvalue{string}- the value to append
Returns {int} - the new list length
redis.sadd(session as Session, key as string, member as string)
Add member to set key (SADD); returns the number newly added (0 or 1).
Parameters
session{Session}- the open sessionkey{string}- the set keymember{string}- the member to add
Returns {int} - the number of members added
redis.scan(session as Session, cursor as int, pattern as string, count as int)
Walk the keyspace one page at a time (SCAN), the production-safe iterator: start with cursor 0 and repeat until the returned cursor is 0 again. Pass pattern "" to skip the MATCH glob and count 0 to skip the COUNT hint. Prefer this over keys, which blocks the server on a large keyspace.
Parameters
session{Session}- the open sessioncursor{int}- the cursor (0 to begin)pattern{string}- a glob to filter keys ("" for no filter)count{int}- a per-page size hint (0 for the server default)
Returns {ScanResult} - the next cursor and this page's keys
redis.scard(session as Session, key as string)
Return the number of members in set key (SCARD); 0 when missing.
Parameters
session{Session}- the open sessionkey{string}- the set key
Returns {int} - the member count
redis.set(session as Session, key as string, value as string)
Store value at key.
Parameters
session{Session}- the open sessionkey{string}- the key to writevalue{string}- the value to store
redis.setBytes(session as Session, key as string, value as bytes)
Store a raw bytes value at key, byte-for-byte. Unlike set (whose string value is UTF-8-encoded onto the wire), this stores arbitrary binary - a serialized blob, a compressed payload, an image - which getBytes reads back exactly. Read it with getBytes, not get (the string reader throws on a non-UTF-8 value).
Parameters
session{Session}- the open sessionkey{string}- the key to writevalue{bytes}- the raw value to store
Throws
{Error}- kind "redis" on a-ERRreply
redis.sismember(session as Session, key as string, member as string)
Report whether member is in set key (SISMEMBER).
Parameters
session{Session}- the open sessionkey{string}- the set keymember{string}- the member to test
Returns {bool} - whether the member is present
redis.smembers(session as Session, key as string)
Return every member of set key (SMEMBERS) as a list (empty when missing; order is unspecified).
Parameters
session{Session}- the open sessionkey{string}- the set key
Returns {list of string} - the members
redis.srem(session as Session, key as string, member as string)
Remove member from set key (SREM); returns the number removed (0 or 1).
Parameters
session{Session}- the open sessionkey{string}- the set keymember{string}- the member to remove
Returns {int} - the number of members removed
redis.subscribe(session as Session, channels as list of string)
Subscribe to one or more channels. After subscribing, the connection is in subscribed mode and may only run (P)SUBSCRIBE / (P)UNSUBSCRIBE / PING / QUIT until fully unsubscribed; read pushes with receiveMessage.
Parameters
session{Session}- the open sessionchannels{list of string}- the channels to subscribe to
redis.unsubscribe(session as Session, channels as list of string)
Unsubscribe from the given channels, or from all channels when the list is empty.
Parameters
session{Session}- the open sessionchannels{list of string}- the channels to leave ([] means all)
Structs
redis.Message
A pushed pub/sub message (from receiveMessage).
| Field | Type | Description |
|---|---|---|
kind | string | "message" (a plain channel push) or "pmessage" (a pattern push) |
channel | string | the channel the message was published to |
pattern | string | the subscribed glob pattern ("" for a plain message) |
payload | string | the message body |
redis.Options
Connection settings.
| Field | Type | Description |
|---|---|---|
host | string | the server host |
port | int | the server port |
security | transport.Security | transport.Security.None (plaintext) or .Tls (rediss); .Starttls is rejected (Redis has no in-band upgrade) |
user | string | the AUTH username ("" for password-only or no auth) |
password | string | the AUTH password; "" skips AUTH |
db | int | the database to SELECT (0 is the default) |
redis.Reply
A parsed RESP reply.
| Field | Type | Description |
|---|---|---|
kind | string | "string" (simple or bulk), "error", "int", "nil", or "array" |
str | string | the string / error text |
num | int | the integer value |
items | list of Reply | an array reply's elements |
redis.ScanResult
One step of a scan cursor walk.
| Field | Type | Description |
|---|---|---|
cursor | int | the cursor to pass to the next scan (0 ends the walk) |
keys | list of string | the keys returned by this step |
redis.Session
An open Redis connection.
| Field | Type | Description |
|---|---|---|
conn | net.Conn | the underlying socket |
timeout | int | per-read idle timeout in milliseconds (0 disables it) |