Clients#

Redis#

class Redis(host: str | None = 'localhost', port: int | None = 6379, db: int = 0, *, username: str | None = None, password: str | None = None, stream_timeout: float | None = None, connect_timeout: float | None = None, connection_pool: ConnectionPool | None = None, connection_pool_cls: Type[ConnectionPool] = ConnectionPool, unix_socket_path: str | None = None, encoding: str = 'utf-8', decode_responses: bool = False, ssl: bool = False, ssl_context: SSLContext | None = None, ssl_keyfile: str | None = None, ssl_certfile: str | None = None, ssl_cert_reqs: Literal['optional', 'required', 'none'] | None = None, ssl_check_hostname: bool | None = None, ssl_ca_certs: str | None = None, max_connections: int | None = None, max_idle_time: float = 0, idle_check_interval: float = 1, client_name: str | None = None, protocol_version: Literal[2, 3] = 3, verify_version: bool = True, cache: AbstractCache | None = None, noreply: bool = False, noevict: bool = False, notouch: bool = False, retry_policy: RetryPolicy = ConstantRetryPolicy((ConnectionError, TimeoutError), 2, 0.01), **kwargs: Any)[source]#
Changes
Parameters:
  • host – The hostname of the redis server

  • port – The port at which th redis server is listening on

  • db – database number to switch to upon connection

  • username – Username for authenticating with the redis server

  • password – Password for authenticating with the redis server

  • stream_timeout – Timeout (seconds) when reading responses from the server

  • connect_timeout – Timeout (seconds) for establishing a connection to the server

  • connection_pool – The connection pool instance to use. If not provided a new pool will be assigned to this client.

  • connection_pool_cls – The connection pool class to use when constructing a connection pool for this instance.

  • unix_socket_path – Path to the UDS which the redis server is listening at

  • encoding – The codec to use to encode strings transmitted to redis and decode responses with. (See Encoding/Decoding)

  • decode_responses – If True string responses from the server will be decoded using encoding before being returned. (See Encoding/Decoding)

  • ssl – Whether to use an SSL connection

  • ssl_context – If provided the ssl.SSLContext will be used when establishing the connection. Otherwise either the default context (if no other ssl related parameters are provided) or a custom context based on the other ssl_* parameters will be used.

  • ssl_keyfile – Path of the private key to use

  • ssl_certfile – Path to the certificate corresponding to ssl_keyfile

  • ssl_cert_reqs – Whether to try to verify the server’s certificates and how to behave if verification fails (See ssl.SSLContext.verify_mode).

  • ssl_check_hostname – Whether to enable hostname checking when establishing an ssl connection.

  • ssl_ca_certs – Path to a concatenated certificate authority file or a directory containing several CA certifcates to use for validating the server’s certificates when ssl_cert_reqs is not "none" (See ssl.SSLContext.load_verify_locations()).

  • max_connections – Maximum capacity of the connection pool (Ignored if connection_pool is not None.

  • max_idle_time – Maximum number of a seconds an unused connection is cached before it is disconnected.

  • idle_check_interval – Periodicity of idle checks (seconds) to release idle connections.

  • client_name – The client name to identifiy with the redis server

  • protocol_version – Whether to use the RESP (2) or RESP3 (3) protocol for parsing responses from the server (Default 3). (See Redis Response)

  • verify_version – Validate redis server version against the documented version introduced before executing a command and raises a CommandNotSupportedError error if the required version is higher than the reported server version

  • cache – If provided the cache will be used to avoid requests for read only commands if the client has already requested the data and it hasn’t been invalidated. The cache is responsible for any mutations to the keys that happen outside of this client

  • noreply – If True the client will not request a response for any commands sent to the server.

  • noevict – Ensures that connections from the client will be excluded from the client eviction process even if we’re above the configured client eviction threshold.

  • notouch – Ensures that commands sent by the client will not alter the LRU/LFU of the keys they access.

  • retry_policy – The retry policy to use when interacting with the redis server

classmethod from_url(url: str, db: int | None = None, *, decode_responses: ~typing.Literal[False] = False, protocol_version: ~typing.Literal[2, 3] = 3, verify_version: bool = True, noreply: bool = False, noevict: bool = False, notouch: bool = False, retry_policy: ~coredis.retry.RetryPolicy = ConstantRetryPolicy<retries=2, retryable_exceptions=ConnectionError, TimeoutError>, **kwargs: ~typing.Any) RedisBytesT[source]#
classmethod from_url(url: str, db: int | None = None, *, decode_responses: ~typing.Literal[True], protocol_version: ~typing.Literal[2, 3] = 3, verify_version: bool = True, noreply: bool = False, noevict: bool = False, notouch: bool = False, retry_policy: ~coredis.retry.RetryPolicy = ConstantRetryPolicy<retries=2, retryable_exceptions=ConnectionError,TimeoutError>, **kwargs: ~typing.Any) RedisStringT

Return a Redis client object configured from the given URL, which must use either the redis:// scheme for RESP connections or the unix:// scheme for Unix domain sockets.

For example:

  • redis://[:password]@localhost:6379/0

  • rediss://[:password]@localhost:6379/0

  • unix://[:password]@/path/to/socket.sock?db=0

url and kwargs are passed as is to the coredis.ConnectionPool.from_url().

bitfield(key: KeyT) BitFieldOperation#
Returns:

a BitFieldOperation instance to conveniently construct one or more bitfield operations on key.

bitfield_ro(key: KeyT) BitFieldOperation#
Returns:

a BitFieldOperation instance to conveniently construct bitfield operations on a read only replica against key.

Raises ReadOnlyError if a write operation is attempted

decoding(mode: Literal[False], encoding: str | None = None) ContextManager[Redis[bytes]][source]#
decoding(mode: Literal[True], encoding: str | None = None) ContextManager[Redis[str]]

Context manager to temporarily change the decoding behavior of the client

Parameters:
  • mode – Whether to decode or not

  • encoding – Optional encoding to use if decoding. If not provided the encoding parameter provided to the client will be used.

Example:

client = coredis.Redis(decode_responses=True)
await client.set("fubar", "baz")
assert await client.get("fubar") == "baz"
with client.decoding(False):
    assert await client.get("fubar") == b"baz"
    with client.decoding(True):
        assert await client.get("fubar") == "baz"

New in version 4.8.0.

ensure_persistence(local: Literal[0, 1] = 0, replicas: int = 0, timeout_ms: int = 100) Iterator[ClientT]#

Context manager to ensure that commands executed within the context are synced to the AOF of a local host and/or replicas within timeout_ms milliseconds.

Internally this uses WAITAOF after each command executed within the context

Raises:

coredis.exceptions.PersistenceError

Example for standalone client:

client = coredis.Redis()
with client.ensure_persistence(1, 0, 20):
    await client.set("fubar", 1)

Example for cluster:

client = coredis.RedisCluster("localhost", 7000)
with client.ensure_persistence(1, 1, 20):
    await client.set("fubar", 1)

New in version 4.12.0.

ensure_replication(replicas: int = 1, timeout_ms: int = 100) Iterator[ClientT]#

Context manager to ensure that commands executed within the context are replicated to atleast replicas within timeout_ms milliseconds.

Internally this uses WAIT after each command executed within the context

Raises:

coredis.exceptions.ReplicationError

Example:

client = coredis.RedisCluster("localhost", 7000)
with client.ensure_replication(1, 20):
    await client.set("fubar", 1)
async execute_command(command: bytes, *args: ValueT, callback: Callable[[...], R] = NoopCallback(), **options: ValueT | None) R[source]#

Executes a command with configured retries and returns the parsed response

async get_library(name: StringT) Library#

Fetch a pre registered library

Parameters:

name – name of the library

New in version 3.1.0.

async hscan_iter(key: KeyT, match: StringT | None = None, count: int | None = None) AsyncGenerator[tuple[AnyStr, AnyStr], None]#

Make an iterator using the HSCAN command so that the client doesn’t need to remember the cursor position.

ignore_replies() Iterator[ClientT]#

Context manager to run commands without waiting for a reply.

Example:

client = coredis.Redis()
with client.ignore_replies():
    assert None == await client.set("fubar", 1), "noreply"
assert True == await client.set("fubar", 1), "reply"
monitor() Monitor[source]#

Return an instance of a Monitor

The monitor can be used as an async iterator or individual commands can be fetched via get_command().

async pipeline(transaction: bool | None = True, watches: Parameters[KeyT] | None = None, timeout: float | None = None) coredis.pipeline.Pipeline[AnyStr][source]#

Returns a new pipeline object that can queue multiple commands for batch execution.

Parameters:
  • transaction – indicates whether all commands should be executed atomically.

  • watches – If transaction is True these keys are watched for external changes during the transaction.

  • timeout – If specified this value will take precedence over Redis.stream_timeout

pubsub(ignore_subscribe_messages: bool = False, retry_policy: RetryPolicy | None = None, **kwargs: Any) PubSub[source]#

Return a Pub/Sub instance that can be used to subscribe to channels and patterns and receive messages that get published to them.

Parameters:
  • ignore_subscribe_messages – Whether to skip subscription acknowledgement messages

  • retry_policy – An explicit retry policy to use in the subscriber.

async register_library(name: StringT, code: StringT, replace: bool = False) Library#

Register a new library

Parameters:
  • name – name of the library

  • code – raw code for the library

  • replace – Whether to replace the library when intializing. If False an exception will be raised if the library was already loaded in the target redis instance.

New in version 3.1.0.

register_script(script: ValueT) Script#

Registers a Lua script

Returns:

A coredis.commands.script.Script instance that is callable and hides the complexity of dealing with scripts, keys, and shas.

async scan_iter(match: StringT | None = None, count: int | None = None, type_: StringT | None = None) AsyncIterator#

Make an iterator using the SCAN command so that the client doesn’t need to remember the cursor position.

async sscan_iter(key: KeyT, match: StringT | None = None, count: int | None = None) AsyncIterator#

Make an iterator using the SSCAN command so that the client doesn’t need to remember the cursor position.

async transaction(func: Callable[['coredis.pipeline.Pipeline[AnyStr]'], Coroutine[Any, Any, Any]], *watches: KeyT, value_from_callable: bool = False, watch_delay: float | None = None, **kwargs: Any) Any | None[source]#

Convenience method for executing the callable func as a transaction while watching all keys specified in watches.

Parameters:
  • func – callable should expect a single argument which is a coredis.pipeline.Pipeline object retrieved by calling pipeline().

  • watches – The keys to watch during the transaction

  • value_from_callable – Whether to return the result of transaction or the value returned from func

async zscan_iter(key: KeyT, match: StringT | None = None, count: int | None = None) AsyncIterator[ScoredMember]#

Make an iterator using the ZSCAN command so that the client doesn’t need to remember the cursor position.

async append(key: KeyT, value: ValueT) int#

Append a value to a key

Returns:

the length of the string after the append operation.

Redis command documentation: APPEND

async decr(key: KeyT) int#

Decrement the integer value of a key by one

Returns:

the value of key after the decrement

Redis command documentation: DECR

async decrby(key: KeyT, decrement: int) int#

Decrement the integer value of a key by the given number

Returns:

the value of key after the decrement

Redis command documentation: DECRBY

async get(key: KeyT) AnyStr | None#

Get the value of a key

Returns:

the value of key, or None when key does not exist.

Redis command documentation: GET

Hint

Supports client side caching

async getdel(key: KeyT) AnyStr | None#

Get the value of a key and delete the key

Returns:

the value of key, None when key does not exist, or an error if the key’s value type isn’t a string.

Redis command documentation: GETDEL

Compatibility:

async getex(key: KeyT, ex: int | timedelta | None = None, px: int | timedelta | None = None, exat: int | datetime | None = None, pxat: int | datetime | None = None, persist: bool | None = None) AnyStr | None#

Get the value of a key and optionally set its expiration

GETEX is similar to GET, but is a write command with additional options. All time parameters can be given as datetime.timedelta or integers.

Parameters:
  • key – name of the key

  • ex – sets an expire flag on key key for ex seconds.

  • px – sets an expire flag on key key for px milliseconds.

  • exat – sets an expire flag on key key for ex seconds, specified in unix time.

  • pxat – sets an expire flag on key key for ex milliseconds, specified in unix time.

  • persist – remove the time to live associated with key.

Returns:

the value of key, or None when key does not exist.

Redis command documentation: GETEX

Compatibility:

async getrange(key: KeyT, start: int, end: int) AnyStr#

Get a substring of the string stored at a key

Returns:

The substring of the string value stored at key, determined by the offsets start and end (both are inclusive)

Redis command documentation: GETRANGE

Hint

Supports client side caching

async getset(key: KeyT, value: ValueT) AnyStr | None#

Set the string value of a key and return its old value

Returns:

the old value stored at key, or None when key did not exist.

Redis command documentation: GETSET

async incr(key: KeyT) int#

Increment the integer value of a key by one

Returns:

the value of key after the increment. If no key exists, the value will be initialized as 1.

Redis command documentation: INCR

async incrby(key: KeyT, increment: int) int#

Increment the integer value of a key by the given amount

Returns:

the value of key after the increment If no key exists, the value will be initialized as increment

Redis command documentation: INCRBY

async incrbyfloat(key: KeyT, increment: int | float) float#

Increment the float value of a key by the given amount

Returns:

the value of key after the increment. If no key exists, the value will be initialized as increment

Redis command documentation: INCRBYFLOAT

async lcs(key1: KeyT, key2: KeyT, *, len_: bool | None = None, idx: bool | None = None, minmatchlen: int | None = None, withmatchlen: bool | None = None) AnyStr | int | LCSResult#

Find the longest common substring

Returns:

The matched string if no other arguments are given. The returned values vary depending on different arguments.

  • If len_ is provided the length of the longest match

  • If idx is True all the matches with the start/end positions of both keys. Optionally, if withmatchlen is True each match will contain the length of the match.

Redis command documentation: LCS

Compatibility:

New in version 3.0.0.

async mget(keys: Parameters[KeyT]) Tuple[AnyStr | None, ...]#

Returns values ordered identically to keys

Redis command documentation: MGET

async mset(key_values: Mapping[KeyT, ValueT]) bool#

Sets multiple keys to multiple values

Redis command documentation: MSET

async msetnx(key_values: Mapping[KeyT, ValueT]) bool#

Set multiple keys to multiple values, only if none of the keys exist

Returns:

Whether all the keys were set

Redis command documentation: MSETNX

async psetex(key: KeyT, milliseconds: int | timedelta, value: ValueT) bool#

Set the value and expiration in milliseconds of a key

Redis command documentation: PSETEX

async set(key: KeyT, value: ValueT, *, condition: Literal[PureToken.NX, PureToken.XX] | None = None, get: bool | None = None, ex: int | timedelta | None = None, px: int | timedelta | None = None, exat: int | datetime | None = None, pxat: int | datetime | None = None, keepttl: bool | None = None) AnyStr | bool | None#

Set the string value of a key

Parameters:
  • condition – Condition to use when setting the key

  • get – Return the old string stored at key, or nil if key did not exist. An error is returned and the command is aborted if the value stored at key is not a string.

  • ex – Number of seconds to expire in

  • px – Number of milliseconds to expire in

  • exat – Expiry time with seconds granularity

  • pxat – Expiry time with milliseconds granularity

  • keepttl – Retain the time to live associated with the key

Returns:

Whether the operation was performed successfully.

Warning

If the command is issued with the get argument, the old string value stored at key is return regardless of success or failure - except if the key was not found.

Redis command documentation: SET

Compatibility:

async setex(key: KeyT, value: ValueT, seconds: int | timedelta) bool#

Set the value of key key to value that expires in seconds

Redis command documentation: SETEX

async setnx(key: KeyT, value: ValueT) bool#

Sets the value of key key to value if key doesn’t exist

Redis command documentation: SETNX

async setrange(key: KeyT, offset: int, value: ValueT) int#

Overwrite bytes in the value of key starting at offset with value. If offset plus the length of value exceeds the length of the original value, the new value will be larger than before.

If offset exceeds the length of the original value, null bytes will be used to pad between the end of the previous value and the start of what’s being injected.

Returns:

the length of the string after it was modified by the command.

Redis command documentation: SETRANGE

async strlen(key: KeyT) int#

Get the length of the value stored in a key

Returns:

the length of the string at key, or 0 when key does not

Redis command documentation: STRLEN

Hint

Supports client side caching

async substr(key: KeyT, start: int, end: int) AnyStr#

Get a substring of the string stored at a key

Returns:

the substring of the string value stored at key, determined by the offsets start and end (both are inclusive). Negative offsets can be used in order to provide an offset starting from the end of the string.

Redis command documentation: SUBSTR

Hint

Supports client side caching

async bitcount(key: KeyT, start: int | None = None, end: int | None = None, index_unit: Literal[PureToken.BIT, PureToken.BYTE] | None = None) int#

Returns the count of set bits in the value of key. Optional start and end parameters indicate which bytes to consider

Redis command documentation: BITCOUNT

Compatibility:

async bitop(keys: Parameters[KeyT], operation: StringT, destkey: KeyT) int#

Perform a bitwise operation using operation between keys and store the result in destkey.

Redis command documentation: BITOP

async bitpos(key: KeyT, bit: int, start: int | None = None, end: int | None = None, index_unit: Literal[PureToken.BIT, PureToken.BYTE] | None = None) int#

Return the position of the first bit set to 1 or 0 in a string. start and end defines the search range. The range is interpreted as a range of bytes and not a range of bits, so start=0 and end=2 means to look at the first three bytes.

Returns:

The position of the first bit set to 1 or 0 according to the request. If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned.

If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right.

So if the string is three bytes set to the value 0xff the command BITPOS key 0 will return 24, since up to bit 23 all the bits are 1.

Basically, the function considers the right of the string as padded with zeros if you look for clear bits and specify no range or the start argument only.

However, this behavior changes if you are looking for clear bits and specify a range with both start and end.

If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

Redis command documentation: BITPOS

Compatibility:

async getbit(key: KeyT, offset: int) int#

Returns the bit value at offset in the string value stored at key

Returns:

the bit value stored at offset.

Redis command documentation: GETBIT

async setbit(key: KeyT, offset: int, value: int) int#

Flag the offset in key as value.

Redis command documentation: SETBIT

async copy(source: KeyT, destination: KeyT, db: int | None = None, replace: bool | None = None) bool#

Copy a key

Redis command documentation: COPY

Compatibility:

New in version 3.0.0.

async delete(keys: Parameters[KeyT]) int#

Delete one or more keys specified by keys

Returns:

The number of keys that were removed.

Redis command documentation: DEL

async dump(key: KeyT) bytes#

Return a serialized version of the value stored at the specified key.

Returns:

the serialized value

Redis command documentation: DUMP

async exists(keys: Parameters[KeyT]) int#

Determine if a key exists

Returns:

the number of keys that exist from those specified as arguments.

Redis command documentation: EXISTS

async expire(key: KeyT, seconds: int | timedelta, condition: Literal[PureToken.NX, PureToken.XX, PureToken.GT, PureToken.LT] | None = None) bool#

Set a key’s time to live in seconds

Returns:

if the timeout was set or not set. e.g. key doesn’t exist, or operation skipped due to the provided arguments.

Redis command documentation: EXPIRE

Compatibility:

async expireat(key: KeyT, unix_time_seconds: int | datetime, condition: Literal[PureToken.NX, PureToken.XX, PureToken.GT, PureToken.LT] | None = None) bool#

Set the expiration for a key to a specific time

Returns:

if the timeout was set or no. e.g. key doesn’t exist, or operation skipped due to the provided arguments.

Redis command documentation: EXPIREAT

Compatibility:

async expiretime(key: KeyT) datetime#

Get the expiration Unix timestamp for a key

Returns:

Expiration Unix timestamp in seconds, or a negative value in order to signal an error.

  • The command returns -1 if the key exists but has no associated expiration time.

  • The command returns -2 if the key does not exist.

Redis command documentation: EXPIRETIME

Compatibility:

New in version 3.0.0.

async keys(pattern: StringT = '*') set[AnyStr]#

Find all keys matching the given pattern

Returns:

keys matching pattern.

Redis command documentation: KEYS

async migrate(host: StringT, port: int, destination_db: int, timeout: int, *keys: KeyT, copy: bool | None = None, replace: bool | None = None, auth: StringT | None = None, username: StringT | None = None, password: StringT | None = None) bool#

Atomically transfer key(s) from a Redis instance to another one.

Returns:

If all keys were found in the source instance.

Redis command documentation: MIGRATE

New in version 3.0.0.

async move(key: KeyT, db: int) bool#

Move a key to another database

Redis command documentation: MOVE

async object_encoding(key: KeyT) AnyStr | None#

Return the internal encoding for the object stored at key

Returns:

the encoding of the object, or None if the key doesn’t exist

Redis command documentation: OBJECT ENCODING

async object_freq(key: KeyT) int#

Return the logarithmic access frequency counter for the object stored at key

Returns:

The counter’s value.

Redis command documentation: OBJECT FREQ

async object_idletime(key: KeyT) int#

Return the time in seconds since the last access to the object stored at key

Returns:

The idle time in seconds.

Redis command documentation: OBJECT IDLETIME

async object_refcount(key: KeyT) int#

Return the reference count of the object stored at key

Returns:

The number of references.

Redis command documentation: OBJECT REFCOUNT

async persist(key: KeyT) bool#

Removes an expiration on key

Redis command documentation: PERSIST

async pexpire(key: KeyT, milliseconds: int | timedelta, condition: Literal[PureToken.NX, PureToken.XX, PureToken.GT, PureToken.LT] | None = None) bool#

Set a key’s time to live in milliseconds

Returns:

if the timeout was set or not. e.g. key doesn’t exist, or operation skipped due to the provided arguments.

Redis command documentation: PEXPIRE

Compatibility:

async pexpireat(key: KeyT, unix_time_milliseconds: int | datetime, condition: Literal[PureToken.NX, PureToken.XX, PureToken.GT, PureToken.LT] | None = None) bool#

Set the expiration for a key as a UNIX timestamp specified in milliseconds

Returns:

if the timeout was set or not. e.g. key doesn’t exist, or operation skipped due to the provided arguments.

Redis command documentation: PEXPIREAT

Compatibility:

async pexpiretime(key: KeyT) datetime#

Get the expiration Unix timestamp for a key in milliseconds

Returns:

Expiration Unix timestamp in milliseconds, or a negative value in order to signal an error

  • The command returns -1 if the key exists but has no associated expiration time.

  • The command returns -2 if the key does not exist.

Redis command documentation: PEXPIRETIME

Compatibility:

New in version 3.0.0.

async pttl(key: KeyT) int#

Returns the number of milliseconds until the key key will expire

Returns:

TTL in milliseconds, or a negative value in order to signal an error

Redis command documentation: PTTL

async randomkey() AnyStr | None#

Returns the name of a random key

Returns:

the random key, or None when the database is empty.

Redis command documentation: RANDOMKEY

async rename(key: KeyT, newkey: KeyT) bool#

Rekeys key key to newkey

Redis command documentation: RENAME

async renamenx(key: KeyT, newkey: KeyT) bool#

Rekeys key key to newkey if newkey doesn’t already exist

Returns:

False when newkey already exists.

Redis command documentation: RENAMENX

async restore(key: KeyT, ttl: int | timedelta | datetime, serialized_value: bytes, replace: bool | None = None, absttl: bool | None = None, idletime: int | timedelta | None = None, freq: int | None = None) bool#

Create a key using the provided serialized value, previously obtained using DUMP.

Redis command documentation: RESTORE

async scan(cursor: int | None = 0, match: StringT | None = None, count: int | None = None, type_: StringT | None = None) tuple[int, tuple[AnyStr, ...]]#

Incrementally iterate the keys space

Redis command documentation: SCAN

async sort(key: KeyT, gets: Parameters[KeyT] | None = None, by: StringT | None = None, offset: int | None = None, count: int | None = None, order: Literal[PureToken.ASC, PureToken.DESC] | None = None, alpha: bool | None = None, store: KeyT | None = None) Tuple[AnyStr, ...] | int#

Sort the elements in a list, set or sorted set

Returns:

sorted elements.

When the store option is specified the command returns the number of sorted elements in the destination list.

Redis command documentation: SORT

async sort_ro(key: KeyT, gets: Parameters[KeyT] | None = None, by: StringT | None = None, offset: int | None = None, count: int | None = None, order: Literal[PureToken.ASC, PureToken.DESC] | None = None, alpha: bool | None = None) Tuple[AnyStr, ...]#

Sort the elements in a list, set or sorted set. Read-only variant of SORT.

Returns:

sorted elements.

Redis command documentation: SORT_RO

Compatibility:

New in version 3.0.0.

async touch(keys: Parameters[KeyT]) int#

Alters the last access time of a key(s). Returns the number of existing keys specified.

Returns:

The number of keys that were touched.

Redis command documentation: TOUCH

async ttl(key: KeyT) int#

Get the time to live for a key in seconds

Returns:

TTL in seconds, or a negative value in order to signal an error

Redis command documentation: TTL

async type(key: KeyT) AnyStr | None#

Determine the type stored at key

Returns:

type of key, or None when key does not exist.

Redis command documentation: TYPE

Hint

Supports client side caching

Delete a key asynchronously in another thread. Otherwise it is just as delete(), but non blocking.

Returns:

The number of keys that were unlinked.

Redis command documentation: UNLINK

async wait(numreplicas: int, timeout: int) int#

Wait for the synchronous replication of all the write commands sent in the context of the current connection

Returns:

the number of replicas the write was replicated to

Redis command documentation: WAIT

Warning

Using wait directly is not recommended. Use the Redis.ensure_replication() or RedisCluster.ensure_replication() context managers to ensure a command is replicated to the number of replicas

async waitaof(numlocal: int, numreplicas: int, timeout: int) tuple[int, ...]#

Wait for all write commands sent in the context of the current connection to be synced to AOF of local host and/or replicas

Returns:

a tuple of (numlocal, numreplicas) that the write commands were synced to

Redis command documentation: WAITAOF

Compatibility:

Warning

Using waitaof directly is not recommended. Use the Redis.ensure_persistence() or RedisCluster.ensure_persistence() context managers to ensure a command is synced to the AOF of the number of local hosts or replicas

New in version 4.12.0.

async hdel(key: KeyT, fields: Parameters[StringT]) int#

Deletes fields from hash key

Redis command documentation: HDEL

async hexists(key: KeyT, field: StringT) bool#

Returns a boolean indicating if field exists within hash key

Redis command documentation: HEXISTS

Hint

Supports client side caching

async hget(key: KeyT, field: StringT) AnyStr | None#

Returns the value of field within the hash key

Redis command documentation: HGET

Hint

Supports client side caching

async hgetall(key: KeyT) dict[AnyStr, AnyStr]#

Returns a Python dict of the hash’s name/value pairs

Redis command documentation: HGETALL

Hint

Supports client side caching

async hincrby(key: KeyT, field: StringT, increment: int) int#

Increments the value of field in hash key by increment

Redis command documentation: HINCRBY

async hincrbyfloat(key: KeyT, field: StringT, increment: int | float) float#

Increments the value of field in hash key by floating increment

Redis command documentation: HINCRBYFLOAT

async hkeys(key: KeyT) tuple[AnyStr, ...]#

Returns the list of keys within hash key

Redis command documentation: HKEYS

Hint

Supports client side caching

async hlen(key: KeyT) int#

Returns the number of elements in hash key

Redis command documentation: HLEN

Hint

Supports client side caching

async hmget(key: KeyT, fields: Parameters[StringT]) Tuple[AnyStr | None, ...]#

Returns values ordered identically to fields

Redis command documentation: HMGET

Hint

Supports client side caching

async hmset(key: KeyT, field_values: Mapping[StringT, ValueT]) bool#

Sets key to value within hash key for each corresponding key and value from the field_items dict.

Redis command documentation: HMSET

async hrandfield(key: KeyT, *, count: int | None = None, withvalues: bool | None = None) AnyStr | tuple[AnyStr, ...] | dict[AnyStr, AnyStr] | None#

Return a random field from the hash value stored at key.

Returns:

Without the additional count argument, the command returns a randomly selected field, or None when key does not exist. When the additional count argument is passed, the command returns fields, or an empty tuple when key does not exist.

If withvalues is True, the reply is a mapping of fields and their values from the hash.

Redis command documentation: HRANDFIELD

Compatibility:

async hscan(key: KeyT, cursor: int | None = 0, match: StringT | None = None, count: int | None = None) tuple[int, dict[AnyStr, AnyStr]]#

Incrementallys return key/value slices in a hash. Also returns a cursor pointing to the scan position.

Parameters:
  • match – allows for filtering the keys by pattern

  • count – allows for hint the minimum number of returns

Redis command documentation: HSCAN

async hset(key: KeyT, field_values: Mapping[StringT, ValueT]) int#

Sets field to value within hash key

Returns:

number of fields that were added

Redis command documentation: HSET

async hsetnx(key: KeyT, field: StringT, value: ValueT) bool#

Sets field to value within hash key if field does not exist.

Returns:

whether the field was created

Redis command documentation: HSETNX

async hstrlen(key: KeyT, field: StringT) int#

Get the length of the value of a hash field

Returns:

the string length of the value associated with field, or zero when field is not present in the hash or key does not exist at all.

Redis command documentation: HSTRLEN

Hint

Supports client side caching

async hvals(key: KeyT) tuple[AnyStr, ...]#

Get all the values in a hash

Returns:

list of values in the hash, or an empty list when key does not exist.

Redis command documentation: HVALS

Hint

Supports client side caching

async pfadd(key: KeyT, *elements: ValueT) bool#

Adds the specified elements to the specified HyperLogLog.

Returns:

Whether atleast 1 HyperLogLog internal register was altered

Redis command documentation: PFADD

async pfcount(keys: Parameters[KeyT]) int#

Return the approximated cardinality of the set(s) observed by the HyperLogLog at key(s).

Returns:

The approximated number of unique elements observed via pfadd().

Redis command documentation: PFCOUNT

async pfmerge(destkey: KeyT, sourcekeys: Parameters[KeyT]) bool#

Merge N different HyperLogLogs into a single one

Redis command documentation: PFMERGE

async blmove(source: KeyT, destination: KeyT, wherefrom: Literal[PureToken.LEFT, PureToken.RIGHT], whereto: Literal[PureToken.LEFT, PureToken.RIGHT], timeout: int | float) AnyStr | None#

Pop an element from a list, push it to another list and return it; or block until one is available

Returns:

the element being popped from source and pushed to destination

Redis command documentation: BLMOVE

Compatibility:

async blmpop(keys: Parameters[KeyT], timeout: int | float, where: Literal[PureToken.LEFT, PureToken.RIGHT], count: int | None = None) List[AnyStr] | None#

Pop elements from the first non empty list, or block until one is available

Returns:

  • A None when no element could be popped, and timeout is reached.

  • A two-element array with the first element being the name of the key from which elements were popped, and the second element is an array of elements.

Redis command documentation: BLMPOP

Compatibility:

New in version 3.0.0.

async blpop(keys: Parameters[KeyT], timeout: int | float) List[AnyStr] | None#

Remove and get the first element in a list, or block until one is available

Returns:

  • None when no element could be popped and the timeout expired.

  • A list with the first element being the name of the key where an element was popped and the second element being the value of the popped element.

Redis command documentation: BLPOP

async brpop(keys: Parameters[KeyT], timeout: int | float) List[AnyStr] | None#

Remove and get the last element in a list, or block until one is available

Returns:

  • None when no element could be popped and the timeout expired.

  • A list with the first element being the name of the key where an element was popped and the second element being the value of the popped element.

Redis command documentation: BRPOP

async brpoplpush(source: KeyT, destination: KeyT, timeout: int | float) AnyStr | None#

Pop an element from a list, push it to another list and return it; or block until one is available

Returns:

the element being popped from source and pushed to destination.

Redis command documentation: BRPOPLPUSH

async lindex(key: KeyT, index: int) AnyStr | None#

Get an element from a list by its index

Returns:

the requested element, or None when index is out of range.

Redis command documentation: LINDEX

Hint

Supports client side caching

async linsert(key: KeyT, where: Literal[PureToken.AFTER, PureToken.BEFORE], pivot: ValueT, element: ValueT) int#

Inserts element in the list stored at key either before or after the reference value pivot.

Returns:

the length of the list after the insert operation, or -1 when the value pivot was not found.

Redis command documentation: LINSERT

async llen(key: KeyT) int#
Returns:

the length of the list at key.

Redis command documentation: LLEN

Hint

Supports client side caching

async lmove(source: KeyT, destination: KeyT, wherefrom: Literal[PureToken.LEFT, PureToken.RIGHT], whereto: Literal[PureToken.LEFT, PureToken.RIGHT]) AnyStr#

Pop an element from a list, push it to another list and return it

Returns:

the element being popped and pushed.

Redis command documentation: LMOVE

Compatibility:

async lmpop(keys: Parameters[KeyT], where: Literal[PureToken.LEFT, PureToken.RIGHT], count: int | None = None) List[AnyStr] | None#

Pop elements from the first non empty list

Returns:

  • A `None` when no element could be popped.

  • A two-element array with the first element being the name of the key from which elements were popped, and the second element is an array of elements.

Redis command documentation: LMPOP

Compatibility:

New in version 3.0.0.

async lpop(key: KeyT, count: int | None = None) AnyStr | list[AnyStr] | None#

Remove and get the first count elements in a list

Returns:

the value of the first element, or None when key does not exist. If count is provided the return is a list of popped elements, or None when key does not exist.

Redis command documentation: LPOP

Compatibility:

async lpos(key: KeyT, element: ValueT, rank: int | None = None, count: int | None = None, maxlen: int | None = None) int | list[int] | None#

Return the index of matching elements on a list

Returns:

The command returns the integer representing the matching element, or None if there is no match.

If the count argument is given a list of integers representing the matching elements.

Redis command documentation: LPOS

Compatibility:

Hint

Supports client side caching

async lpush(key: KeyT, elements: Parameters[ValueT]) int#

Prepend one or multiple elements to a list

Returns:

the length of the list after the push operations.

Redis command documentation: LPUSH

async lpushx(key: KeyT, elements: Parameters[ValueT]) int#

Prepend an element to a list, only if the list exists

Returns:

the length of the list after the push operation.

Redis command documentation: LPUSHX

async lrange(key: KeyT, start: int, stop: int) list[AnyStr]#

Get a range of elements from a list

Returns:

list of elements in the specified range.

Redis command documentation: LRANGE

Hint

Supports client side caching

async lrem(key: KeyT, count: int, element: ValueT) int#

Removes the first count occurrences of elements equal to element from the list stored at key.

The count argument influences the operation in the following ways:

count > 0: Remove elements equal to value moving from head to tail. count < 0: Remove elements equal to value moving from tail to head. count = 0: Remove all elements equal to value.

Returns:

the number of removed elements.

Redis command documentation: LREM

async lset(key: KeyT, index: int, element: ValueT) bool#

Sets index of list key to element

Redis command documentation: LSET

async ltrim(key: KeyT, start: int, stop: int) bool#

Trims the list key, removing all values not within the slice between start and stop

start and stop can be negative numbers just like Python slicing notation

Redis command documentation: LTRIM

async rpop(key: KeyT, count: int | None = None) AnyStr | list[AnyStr] | None#

Remove and get the last elements in a list

Returns:

When called without the count argument the value of the last element, or None when key does not exist.

When called with the count argument list of popped elements, or None when key does not exist.

Redis command documentation: RPOP

Compatibility:

async rpoplpush(source: KeyT, destination: KeyT) AnyStr | None#

Remove the last element in a list, prepend it to another list and return it

Returns:

the element being popped and pushed.

Redis command documentation: RPOPLPUSH

async rpush(key: KeyT, elements: Parameters[ValueT]) int#

Append an element(s) to a list

Returns:

the length of the list after the push operation.

Redis command documentation: RPUSH

async rpushx(key: KeyT, elements: Parameters[ValueT]) int#

Append a element(s) to a list, only if the list exists

Returns:

the length of the list after the push operation.

Redis command documentation: RPUSHX

async sadd(key: KeyT, members: Parameters[ValueT]) int#

Add one or more members to a set

Returns:

the number of elements that were added to the set, not including all the elements already present in the set.

Redis command documentation: SADD

async scard(key: KeyT) int#

Returns the number of members in the set

:return the cardinality (number of elements) of the set, or 0 if key

does not exist.

Redis command documentation: SCARD

Hint

Supports client side caching

async sdiff(keys: Parameters[KeyT]) Set[AnyStr]#

Subtract multiple sets

Returns:

members of the resulting set.

Redis command documentation: SDIFF

async sdiffstore(keys: Parameters[KeyT], destination: KeyT) int#

Subtract multiple sets and store the resulting set in a key

Redis command documentation: SDIFFSTORE

async sinter(keys: Parameters[KeyT]) Set[AnyStr]#

Intersect multiple sets

Returns:

members of the resulting set

Redis command documentation: SINTER

async sintercard(keys: Parameters[KeyT], limit: int | None = None) int#

Intersect multiple sets and return the cardinality of the result

Returns:

The number of elements in the resulting intersection.

Redis command documentation: SINTERCARD

Compatibility:

New in version 3.0.0.

async sinterstore(keys: Parameters[KeyT], destination: KeyT) int#

Intersect multiple sets and store the resulting set in a key

Returns:

the number of elements in the resulting set.

Redis command documentation: SINTERSTORE

async sismember(key: KeyT, member: ValueT) bool#

Determine if a given value is a member of a set

Returns:

If the element is a member of the set. False if key does not exist.

Redis command documentation: SISMEMBER

Hint

Supports client side caching

async smembers(key: KeyT) set[AnyStr]#

Returns all members of the set

Redis command documentation: SMEMBERS

Hint

Supports client side caching

async smismember(key: KeyT, members: Parameters[ValueT]) Tuple[bool, ...]#

Returns the membership associated with the given elements for a set

Returns:

tuple representing the membership of the given elements, in the same order as they are requested.

Redis command documentation: SMISMEMBER

Compatibility:

Hint

Supports client side caching

async smove(source: KeyT, destination: KeyT, member: ValueT) bool#

Move a member from one set to another

Redis command documentation: SMOVE

async spop(key: KeyT, count: int | None = None) AnyStr | set[AnyStr] | None#

Remove and return one or multiple random members from a set

Returns:

When called without the count argument the removed member, or None when key does not exist.

When called with the count argument the removed members, or an empty array when key does not exist.

Redis command documentation: SPOP

async srandmember(key: KeyT, count: int | None = None) AnyStr | set[AnyStr] | None#

Get one or multiple random members from a set

Returns:

without the additional count argument, the command returns a randomly selected element, or None when key does not exist.

When the additional count argument is passed, the command returns elements, or an empty set when key does not exist.

Redis command documentation: SRANDMEMBER

async srem(key: KeyT, members: Parameters[ValueT]) int#

Remove one or more members from a set

Returns:

the number of members that were removed from the set, not including non existing members.

Redis command documentation: SREM

async sscan(key: KeyT, cursor: int | None = 0, match: StringT | None = None, count: int | None = None) tuple[int, set[AnyStr]]#

Incrementally returns subsets of elements in a set. Also returns a cursor pointing to the scan position.

Parameters:
  • match – is for filtering the keys by pattern

  • count – is for hint the minimum number of returns

Redis command documentation: SSCAN

async sunion(keys: Parameters[KeyT]) Set[AnyStr]#

Add multiple sets

Returns:

members of the resulting set.

Redis command documentation: SUNION

async sunionstore(keys: Parameters[KeyT], destination: KeyT) int#

Add multiple sets and store the resulting set in a key

Returns:

the number of elements in the resulting set.

Redis command documentation: SUNIONSTORE

async bzmpop(keys: Parameters[KeyT], timeout: int | float, where: Literal[PureToken.MAX, PureToken.MIN], count: int | None = None) Tuple[AnyStr, Tuple[ScoredMember, ...]] | None#

Remove and return members with scores in a sorted set or block until one is available

Returns:

  • A `None` when no element could be popped.

  • A tuple of (name of key, popped (member, score) pairs)

Redis command documentation: BZMPOP

Compatibility:

New in version 3.0.0.

async bzpopmax(keys: Parameters[KeyT], timeout: int | float) Tuple[AnyStr, AnyStr, float] | None#

Remove and return the member with the highest score from one or more sorted sets, or block until one is available.

Returns:

A triplet with the first element being the name of the key where a member was popped, the second element is the popped member itself, and the third element is the score of the popped element.

Redis command documentation: BZPOPMAX

async bzpopmin(keys: Parameters[KeyT], timeout: int | float) Tuple[AnyStr, AnyStr, float] | None#

Remove and return the member with the lowest score from one or more sorted sets, or block until one is available

Returns:

A triplet with the first element being the name of the key where a member was popped, the second element is the popped member itself, and the third element is the score of the popped element.

Redis command documentation: BZPOPMIN

async zadd(key: KeyT, member_scores: Mapping[StringT, int | float], condition: Literal[PureToken.NX, PureToken.XX] | None = None, comparison: Literal[PureToken.GT, PureToken.LT] | None = None, change: bool | None = None, increment: bool | None = None) int | float | None#

Add one or more members to a sorted set, or update its score if it already exists

Returns:

  • When used without optional arguments, the number of elements added to the sorted set (excluding score updates).

  • If the change option is specified, the number of elements that were changed (added or updated).

  • If condition is specified, the new score of member (a double precision floating point number) represented as string

  • None if the operation is aborted

Redis command documentation: ZADD

Compatibility:

async zcard(key: KeyT) int#

Get the number of members in a sorted set

Returns:

the cardinality (number of elements) of the sorted set, or 0 if the key does not exist

Redis command documentation: ZCARD

async zcount(key: KeyT, min_: ValueT, max_: ValueT) int#

Count the members in a sorted set with scores within the given values

Returns:

the number of elements in the specified score range.

Redis command documentation: ZCOUNT

async zdiff(keys: Parameters[KeyT], withscores: bool | None = None) Tuple[AnyStr | ScoredMember, ...]#

Subtract multiple sorted sets

Returns:

the result of the difference (optionally with their scores, in case the withscores option is given).

Redis command documentation: ZDIFF

Compatibility:

async zdiffstore(keys: Parameters[KeyT], destination: KeyT) int#

Subtract multiple sorted sets and store the resulting sorted set in a new key

Returns:

the number of elements in the resulting sorted set at destination.

Redis command documentation: ZDIFFSTORE

Compatibility:

async zincrby(key: KeyT, member: ValueT, increment: int) float#

Increment the score of a member in a sorted set

Returns:

the new score of member

Redis command documentation: ZINCRBY

async zinter(keys: Parameters[KeyT], weights: Parameters[int] | None = None, aggregate: Literal[PureToken.MAX, PureToken.MIN, PureToken.SUM] | None = None, withscores: bool | None = None) Tuple[AnyStr | ScoredMember, ...]#

Intersect multiple sorted sets

Returns:

the result of intersection (optionally with their scores, in case the withscores option is given).

Redis command documentation: ZINTER

Compatibility:

async zintercard(keys: Parameters[KeyT], limit: int | None = None) int#

Intersect multiple sorted sets and return the cardinality of the result

Returns:

The number of elements in the resulting intersection.

Redis command documentation: ZINTERCARD

Compatibility:

New in version 3.0.0.

async zinterstore(keys: Parameters[KeyT], destination: KeyT, weights: Parameters[int] | None = None, aggregate: Literal[PureToken.MAX, PureToken.MIN, PureToken.SUM] | None = None) int#

Intersect multiple sorted sets and store the resulting sorted set in a new key

Returns:

the number of elements in the resulting sorted set at destination.

Redis command documentation: ZINTERSTORE

async zlexcount(key: KeyT, min_: ValueT, max_: ValueT) int#

Count the number of members in a sorted set between a given lexicographical range

Returns:

the number of elements in the specified score range.

Redis command documentation: ZLEXCOUNT

Hint

Supports client side caching

async zmpop(keys: Parameters[KeyT], where: Literal[PureToken.MAX, PureToken.MIN], count: int | None = None) Tuple[AnyStr, Tuple[ScoredMember, ...]] | None#

Remove and return members with scores in a sorted set

Returns:

A tuple of (name of key, popped (member, score) pairs)

Redis command documentation: ZMPOP

Compatibility:

New in version 3.0.0.

async zmscore(key: KeyT, members: Parameters[ValueT]) Tuple[float | None, ...]#

Get the score associated with the given members in a sorted set

Returns:

scores or None associated with the specified members values (a double precision floating point number), represented as strings

Redis command documentation: ZMSCORE

Compatibility:

Hint

Supports client side caching

async zpopmax(key: KeyT, count: int | None = None) ScoredMember | tuple[ScoredMember, ...] | None#

Remove and return members with the highest scores in a sorted set

Returns:

popped elements and scores.

Redis command documentation: ZPOPMAX

async zpopmin(key: KeyT, count: int | None = None) ScoredMember | tuple[ScoredMember, ...] | None#

Remove and return members with the lowest scores in a sorted set

Returns:

popped elements and scores.

Redis command documentation: ZPOPMIN

async zrandmember(key: KeyT, count: int | None = None, withscores: bool | None = None) AnyStr | list[AnyStr] | tuple[ScoredMember, ...] | None#

Get one or multiple random elements from a sorted set

Returns:

without count, the command returns a randomly selected element, or None when key does not exist.

If count is passed the command returns the elements, or an empty tuple when key does not exist.

If withscores argument is used, the return is a list elements and their scores from the sorted set.

Redis command documentation: ZRANDMEMBER

Compatibility:

async zrange(key: KeyT, min_: int | ValueT, max_: int | ValueT, sortby: Literal[PureToken.BYSCORE, PureToken.BYLEX] | None = None, rev: bool | None = None, offset: int | None = None, count: int | None = None, withscores: bool | None = None) tuple[AnyStr | ScoredMember, ...]#

Return a range of members in a sorted set

Returns:

elements in the specified range (optionally with their scores, in case withscores is given).

Redis command documentation: ZRANGE

Compatibility:

Hint

Supports client side caching

async zrangebylex(key: KeyT, min_: ValueT, max_: ValueT, offset: int | None = None, count: int | None = None) tuple[AnyStr, ...]#

Return a range of members in a sorted set, by lexicographical range

Returns:

elements in the specified score range.

Redis command documentation: ZRANGEBYLEX

Hint

Supports client side caching

async zrangebyscore(key: KeyT, min_: int | float, max_: int | float, withscores: bool | None = None, offset: int | None = None, count: int | None = None) tuple[AnyStr | ScoredMember, ...]#

Return a range of members in a sorted set, by score

Returns:

elements in the specified score range (optionally with their scores).

Redis command documentation: ZRANGEBYSCORE

Hint

Supports client side caching

async zrangestore(dst: KeyT, src: KeyT, min_: int | ValueT, max_: int | ValueT, sortby: Literal[PureToken.BYSCORE, PureToken.BYLEX] | None = None, rev: bool | None = None, offset: int | None = None, count: int | None = None) int#

Store a range of members from sorted set into another key

Returns:

the number of elements in the resulting sorted set

Redis command documentation: ZRANGESTORE

Compatibility:

async zrank(key: KeyT, member: ValueT, withscore: bool | None = None) int | tuple[int, float] | None#

Determine the index of a member in a sorted set

Returns:

the rank of member. If withscore is True the return is a tuple of (rank, score).

Redis command documentation: ZRANK

Compatibility:

Hint

Supports client side caching

async zrem(key: KeyT, members: Parameters[ValueT]) int#

Remove one or more members from a sorted set

Returns:

The number of members removed from the sorted set, not including non existing members.

Redis command documentation: ZREM

async zremrangebylex(key: KeyT, min_: ValueT, max_: ValueT) int#

Remove all members in a sorted set between the given lexicographical range

Returns:

the number of elements removed.

Redis command documentation: ZREMRANGEBYLEX

async zremrangebyrank(key: KeyT, start: int, stop: int) int#

Remove all members in a sorted set within the given indexes

Returns:

the number of elements removed.

Redis command documentation: ZREMRANGEBYRANK

async zremrangebyscore(key: KeyT, min_: int | float, max_: int | float) int#

Remove all members in a sorted set within the given scores

Returns:

the number of elements removed.

Redis command documentation: ZREMRANGEBYSCORE

async zrevrange(key: KeyT, start: int, stop: int, withscores: bool | None = None) tuple[AnyStr | ScoredMember, ...]#

Return a range of members in a sorted set, by index, with scores ordered from high to low

Returns:

elements in the specified range (optionally with their scores).

Redis command documentation: ZREVRANGE

Hint

Supports client side caching

async zrevrangebylex(key: KeyT, max_: ValueT, min_: ValueT, offset: int | None = None, count: int | None = None) tuple[AnyStr, ...]#

Return a range of members in a sorted set, by lexicographical range, ordered from higher to lower strings.

Returns:

elements in the specified score range

Redis command documentation: ZREVRANGEBYLEX

Hint

Supports client side caching

async zrevrangebyscore(key: KeyT, max_: int | float, min_: int | float, withscores: bool | None = None, offset: int | None = None, count: int | None = None) tuple[AnyStr | ScoredMember, ...]#

Return a range of members in a sorted set, by score, with scores ordered from high to low

Returns:

elements in the specified score range (optionally with their scores)

Redis command documentation: ZREVRANGEBYSCORE

Hint

Supports client side caching

async zrevrank(key: KeyT, member: ValueT, withscore: bool | None = None) int | tuple[int, float] | None#

Determine the index of a member in a sorted set, with scores ordered from high to low

Returns:

the rank of member. If withscore is True the return is a tuple of (rank, score).

Redis command documentation: ZREVRANK

Compatibility:

Hint

Supports client side caching

async zscan(key: KeyT, cursor: int | None = 0, match: StringT | None = None, count: int | None = None) tuple[int, tuple[ScoredMember, ...]]#

Incrementally iterate sorted sets elements and associated scores

Redis command documentation: ZSCAN

async zscore(key: KeyT, member: ValueT) float | None#

Get the score associated with the given member in a sorted set

Returns:

the score of member (a double precision floating point number), represented as string or None if the member doesn’t exist.

Redis command documentation: ZSCORE

Hint

Supports client side caching

async zunion(keys: Parameters[KeyT], weights: Parameters[int] | None = None, aggregate: Literal[PureToken.SUM, PureToken.MIN, PureToken.MAX] | None = None, withscores: bool | None = None) Tuple[AnyStr | ScoredMember, ...]#

Add multiple sorted sets

Returns:

the result of union (optionally with their scores, in case withscores is given).

Redis command documentation: ZUNION

Compatibility:

async zunionstore(keys: Parameters[KeyT], destination: KeyT, weights: Parameters[int] | None = None, aggregate: Literal[PureToken.SUM, PureToken.MIN, PureToken.MAX] | None = None) int#

Add multiple sorted sets and store the resulting sorted set in a new key

Returns:

the number of elements in the resulting sorted set at destination.

Redis command documentation: ZUNIONSTORE

async geoadd(key: KeyT, longitude_latitude_members: Parameters[Tuple[int | float, int | float, ValueT]], condition: Literal[PureToken.NX, PureToken.XX] | None = None, change: bool | None = None) int#

Add one or more geospatial items in the geospatial index represented using a sorted set

Returns:

Number of elements added. If change is True the return is the number of elements that were changed.

Redis command documentation: GEOADD

Compatibility:

async geodist(key: KeyT, member1: StringT, member2: StringT, unit: Literal[PureToken.M, PureToken.KM, PureToken.FT, PureToken.MI] | None = None) float | None#

Returns the distance between two members of a geospatial index

Returns:

Distance in the unit specified by unit

Redis command documentation: GEODIST

async geohash(key: KeyT, members: Parameters[ValueT]) Tuple[AnyStr, ...]#

Returns members of a geospatial index as standard geohash strings

Redis command documentation: GEOHASH

async geopos(key: KeyT, members: Parameters[ValueT]) Tuple[GeoCoordinates | None, ...]#

Returns longitude and latitude of members of a geospatial index

Returns:

pairs of longitude/latitudes. Missing members are represented by None entries.

Redis command documentation: GEOPOS

async georadius(key: KeyT, longitude: int | float, latitude: int | float, radius: int | float, unit: Literal[PureToken.FT, PureToken.KM, PureToken.M, PureToken.MI], *, withcoord: bool | None = None, withdist: bool | None = None, withhash: bool | None = None, count: int | None = None, any_: bool | None = None, order: Literal[PureToken.ASC, PureToken.DESC] | None = None, store: KeyT | None = None, storedist: KeyT | None = None) int | tuple[AnyStr | GeoSearchResult, ...]#

Query a geospatial index to fetch members within the borders of the area specified with center location at longitude and latitude and the maximum distance from the center (radius).

Returns:

  • If no with{coord,dist,hash} options are provided the return is simply the names of places matched (optionally ordered if order is provided).

  • If any of the with{coord,dist,hash} options are set each result entry contains (name, distance, geohash, coordinate pair)`

  • If a key for store or storedist is provided, the return is the count of places stored.

Redis command documentation: GEORADIUS

Compatibility:

async georadiusbymember(key: KeyT, member: ValueT, radius: int | float, unit: Literal[PureToken.FT, PureToken.KM, PureToken.M, PureToken.MI], withcoord: bool | None = None, withdist: bool | None = None, withhash: bool | None = None, count: int | None = None, any_: bool | None = None, order: Literal[PureToken.ASC, PureToken.DESC] | None = None, store: KeyT | None = None, storedist: KeyT | None = None) int | tuple[AnyStr | GeoSearchResult, ...]#

This command is exactly like georadius() with the sole difference that instead of searching from a coordinate, it searches from a member already existing in the index.

Returns:

  • If no with{coord,dist,hash} options are provided the return is simply the names of places matched (optionally ordered if order is provided).

  • If any of the with{coord,dist,hash} options are set each result entry contains (name, distance, geohash, coordinate pair)`

  • If a key for store or storedist is provided, the return is the count of places stored.

Redis command documentation: GEORADIUSBYMEMBER

async geosearch(key: KeyT, member: ValueT | None = None, longitude: int | float | None = None, latitude: int | float | None = None, radius: int | float | None = None, circle_unit: Literal[PureToken.M, PureToken.KM, PureToken.FT, PureToken.MI] | None = None, width: int | float | None = None, height: int | float | None = None, box_unit: Literal[PureToken.M, PureToken.KM, PureToken.FT, PureToken.MI] | None = None, order: Literal[PureToken.ASC, PureToken.DESC] | None = None, count: int | None = None, any_: bool | None = None, withcoord: bool | None = None, withdist: bool | None = None, withhash: bool | None = None) int | tuple[AnyStr | GeoSearchResult, ...]#
Returns:

  • If no with{coord,dist,hash} options are provided the return is simply the names of places matched (optionally ordered if order is provided).

  • If any of the with{coord,dist,hash} options are set each result entry contains (name, distance, geohash, coordinate pair)`

Redis command documentation: GEOSEARCH

Compatibility:

async geosearchstore(destination: KeyT, source: KeyT, member: ValueT | None = None, longitude: int | float | None = None, latitude: int | float | None = None, radius: int | float | None = None, circle_unit: Literal[PureToken.M, PureToken.KM, PureToken.FT, PureToken.MI] | None = None, width: int | float | None = None, height: int | float | None = None, box_unit: Literal[PureToken.M, PureToken.KM, PureToken.FT, PureToken.MI] | None = None, order: Literal[PureToken.ASC, PureToken.DESC] | None = None, count: int | None = None, any_: bool | None = None, storedist: bool | None = None) int#
Returns:

The number of elements stored in the resulting set

Redis command documentation: GEOSEARCHSTORE

Compatibility:

async eval(script: StringT, keys: Parameters[KeyT] | None = None, args: Parameters[ValueT] | None = None) ResponseType#

Execute the Lua script with the key names and argument values in keys and args.

Returns:

The result of the script as redis returns it

Redis command documentation: EVAL

async eval_ro(script: StringT, keys: Parameters[KeyT] | None = None, args: Parameters[ValueT] | None = None) ResponseType#

Read-only variant of eval() that cannot execute commands that modify data.

Returns:

The result of the script as redis returns it

Redis command documentation: EVAL_RO

Compatibility:

New in version 3.0.0.

async evalsha(sha1: StringT, keys: Parameters[KeyT] | None = None, args: Parameters[ValueT] | None = None) ResponseType#

Execute the Lua script cached by it’s sha ref with the key names and argument values in keys and args. Evaluate a script from the server’s cache by its sha1 digest.

Returns:

The result of the script as redis returns it

Redis command documentation: EVALSHA

async evalsha_ro(sha1: StringT, keys: Parameters[KeyT] | None = None, args: Parameters[ValueT] | None = None) ResponseType#

Read-only variant of evalsha() that cannot execute commands that modify data.

Returns:

The result of the script as redis returns it

Redis command documentation: EVALSHA_RO

Compatibility:

New in version 3.0.0.

async fcall(function: StringT, keys: Parameters[KeyT] | None = None, args: Parameters[ValueT] | None = None) ResponseType#

Invoke a function

Redis command documentation: FCALL

Compatibility:

New in version 3.1.0.

async fcall_ro(function: StringT, keys: Parameters[KeyT] | None = None, args: Parameters[ValueT] | None = None) ResponseType#

Read-only variant of fcall()

Redis command documentation: FCALL_RO

Compatibility:

New in version 3.1.0.

async function_delete(library_name: StringT) bool#

Delete a library and all its functions.

Redis command documentation: FUNCTION DELETE

Compatibility:

New in version 3.1.0.

async function_dump() bytes#

Dump all functions into a serialized binary payload

Redis command documentation: FUNCTION DUMP

Compatibility:

New in version 3.1.0.

async function_flush(async_: Literal[PureToken.ASYNC, PureToken.SYNC] | None = None) bool#

Delete all functions

Redis command documentation: FUNCTION FLUSH

Compatibility:

New in version 3.1.0.

async function_kill() bool#

Kill the function currently in execution.

Redis command documentation: FUNCTION KILL

Compatibility:

New in version 3.1.0.

async function_list(libraryname: StringT | None = None, withcode: bool | None = None) Mapping[str, LibraryDefinition]#

List information about the functions registered under libraryname

Redis command documentation: FUNCTION LIST

Compatibility:

New in version 3.1.0.

async function_load(function_code: StringT, replace: bool | None = None) AnyStr#

Load a library of functions.

Redis command documentation: FUNCTION LOAD

Compatibility:

New in version 3.1.0.

async function_restore(serialized_value: bytes, policy: Literal[PureToken.FLUSH, PureToken.APPEND, PureToken.REPLACE] | None = None) bool#

Restore all the functions on the given payload

Redis command documentation: FUNCTION RESTORE

Compatibility:

New in version 3.1.0.

async function_stats() dict[AnyStr, AnyStr | dict[AnyStr, dict[AnyStr, ResponsePrimitive]]]#

Return information about the function currently running

Redis command documentation: FUNCTION STATS

Compatibility:

New in version 3.1.0.

async script_debug(mode: Literal[PureToken.NO, PureToken.SYNC, PureToken.YES]) bool#

Set the debug mode for executed scripts

Raises:

NotImplementedError

Redis command documentation: SCRIPT DEBUG

New in version 3.0.0.

async script_exists(sha1s: Parameters[StringT]) Tuple[bool, ...]#

Check if a script exists in the script cache by specifying the SHAs of each script as sha1s.

Returns:

tuple of boolean values indicating if each script exists in the cache.

Redis command documentation: SCRIPT EXISTS

async script_flush(sync_type: Literal[PureToken.ASYNC, PureToken.SYNC] | None = None) bool#

Flushes all scripts from the script cache

Redis command documentation: SCRIPT FLUSH

Compatibility:

async script_kill() bool#

Kills the currently executing Lua script

Redis command documentation: SCRIPT KILL

async script_load(script: StringT) AnyStr#

Loads a Lua script into the script cache.

Returns:

The SHA1 digest of the script added into the script cache

Redis command documentation: SCRIPT LOAD

async publish(channel: StringT, message: ValueT) int#

Publish message on channel.

Returns:

the number of subscribers the message was delivered to.

Redis command documentation: PUBLISH

async pubsub_channels(pattern: StringT | None = None) set[AnyStr]#

Return channels that have at least one subscriber

Redis command documentation: PUBSUB CHANNELS

async pubsub_numpat() int#

Get the count of unique patterns pattern subscriptions

Returns:

the number of patterns all the clients are subscribed to.

Redis command documentation: PUBSUB NUMPAT

async pubsub_numsub(*channels: StringT) dict[AnyStr, int]#

Get the count of subscribers for channels

Returns:

Mapping of channels to number of subscribers per channel

Redis command documentation: PUBSUB NUMSUB

async pubsub_shardchannels(pattern: StringT | None = None) set[AnyStr]#

Return shard channels that have at least one subscriber

Redis command documentation: PUBSUB SHARDCHANNELS

Compatibility:

New in version 3.6.0.

async pubsub_shardnumsub(*channels: StringT) dict[AnyStr, int]#

Get the count of subscribers for shard channels

Returns:

Ordered mapping of shard channels to number of subscribers per channel

Redis command documentation: PUBSUB SHARDNUMSUB

async spublish(channel: StringT, message: ValueT) int#

Publish message on shard channel.

Returns:

the number of shard subscribers the message was delivered to.

Note

The number only represents subscribers listening to the exact node the message was published to, which means that if a subscriber is listening on a replica node, it will not be included in the count.

Redis command documentation: SPUBLISH

Compatibility:

New in version 3.6.0.

async xack(key: KeyT, group: StringT, identifiers: Parameters[ValueT]) int#

Marks a pending message as correctly processed, effectively removing it from the pending entries list of the consumer group.

Returns:

number of messages successfully acknowledged, that is, the IDs we were actually able to resolve in the PEL.

Redis command documentation: XACK

async xadd(key: KeyT, field_values: Mapping[StringT, ValueT], identifier: ValueT | None = None, nomkstream: bool | None = None, trim_strategy: Literal[PureToken.MAXLEN, PureToken.MINID] | None = None, threshold: int | None = None, trim_operator: Literal[PureToken.EQUAL, PureToken.APPROXIMATELY] | None = None, limit: int | None = None) AnyStr | None#

Appends a new entry to a stream

Returns:

The identifier of the added entry. The identifier is the one auto-generated if * is passed as identifier, otherwise the it justs returns the same identifier specified

Returns None when used with nomkstream and the key doesn’t exist.

Redis command documentation: XADD

Compatibility:

async xautoclaim(key: KeyT, group: StringT, consumer: StringT, min_idle_time: int | timedelta, start: ValueT, count: int | None = None, justid: bool | None = None) tuple[AnyStr, tuple[AnyStr, ...]] | tuple[AnyStr, tuple[StreamEntry, ...], tuple[AnyStr, ...]]#

Changes (or acquires) ownership of messages in a consumer group, as if the messages were delivered to the specified consumer.

Returns:

A dictionary with keys as stream identifiers and values containing all the successfully claimed messages in the same format as xrange()

Redis command documentation: XAUTOCLAIM

Compatibility:

New in version 3.0.0.

async xclaim(key: KeyT, group: StringT, consumer: StringT, min_idle_time: int | datetime.timedelta, identifiers: Parameters[ValueT], idle: int | datetime.timedelta | None = None, time: int | datetime.datetime | None = None, retrycount: int | None = None, force: bool | None = None, justid: bool | None = None, lastid: ValueT | None = None) Tuple[AnyStr, ...] | Tuple[StreamEntry, ...]#

Changes (or acquires) ownership of a message in a consumer group, as if the message was delivered to the specified consumer.

Redis command documentation: XCLAIM

async xdel(key: KeyT, identifiers: Parameters[ValueT]) int#

Redis command documentation: XDEL

async xgroup_create(key: KeyT, groupname: StringT, identifier: ValueT | None = None, mkstream: bool | None = None, entriesread: int | None = None) bool#

Create a consumer group.

Redis command documentation: XGROUP CREATE

Compatibility:

async xgroup_createconsumer(key: KeyT, groupname: StringT, consumername: StringT) bool#

Create a consumer in a consumer group.

Returns:

whether the consumer was created

Redis command documentation: XGROUP CREATECONSUMER

Compatibility:

New in version 3.0.0.

async xgroup_delconsumer(key: KeyT, groupname: StringT, consumername: StringT) int#

Delete a consumer from a consumer group.

Returns:

The number of pending messages that the consumer had before it was deleted

Redis command documentation: XGROUP DELCONSUMER

New in version 3.0.0.

async xgroup_destroy(key: KeyT, groupname: StringT) int#

Destroy a consumer group.

Returns:

The number of destroyed consumer groups

Redis command documentation: XGROUP DESTROY

async xgroup_setid(key: KeyT, groupname: StringT, identifier: ValueT | None = None, entriesread: int | None = None) bool#

Set a consumer group to an arbitrary last delivered ID value.

Redis command documentation: XGROUP SETID

Compatibility:

New in version 3.0.0.

async xinfo_consumers(key: KeyT, groupname: StringT) tuple[dict[AnyStr, AnyStr], ...]#

Get list of all consumers that belong to groupname of the stream stored at key

Redis command documentation: XINFO CONSUMERS

async xinfo_groups(key: KeyT) tuple[dict[AnyStr, AnyStr], ...]#

Get list of all consumers groups of the stream stored at key

Redis command documentation: XINFO GROUPS

async xinfo_stream(key: KeyT, full: bool | None = None, count: int | None = None) StreamInfo#

Get information about the stream stored at key

Parameters:

Redis command documentation: XINFO STREAM

async xlen(key: KeyT) int#

Redis command documentation: XLEN

async xpending(key: KeyT, group: StringT, start: ValueT | None = None, end: ValueT | None = None, count: int | None = None, idle: int | None = None, consumer: StringT | None = None) tuple[StreamPendingExt, ...] | StreamPending#

Return information and entries from a stream consumer group pending entries list, that are messages fetched but never acknowledged.

Redis command documentation: XPENDING

Compatibility:

async xrange(key: KeyT, start: ValueT | None = None, end: ValueT | None = None, count: int | None = None) tuple[StreamEntry, ...]#

Return a range of elements in a stream, with IDs matching the specified IDs interval

Redis command documentation: XRANGE

async xread(streams: Mapping[ValueT, ValueT], count: int | None = None, block: int | timedelta | None = None) dict[AnyStr, tuple[StreamEntry, ...]] | None#

Return never seen elements in multiple streams, with IDs greater than the ones reported by the caller for each stream. Can block.

Returns:

Mapping of streams to stream entries. Field and values are guaranteed to be reported in the same order they were added by xadd().

When block is used, on timeout None is returned.

Redis command documentation: XREAD

async xreadgroup(group: StringT, consumer: StringT, streams: Mapping[ValueT, ValueT], count: int | None = None, block: int | timedelta | None = None, noack: bool | None = None) dict[AnyStr, tuple[StreamEntry, ...]] | None#

Redis command documentation: XREADGROUP

async xrevrange(key: KeyT, end: ValueT | None = None, start: ValueT | None = None, count: int | None = None) tuple[StreamEntry, ...]#

Return a range of elements in a stream, with IDs matching the specified IDs interval, in reverse order (from greater to smaller IDs) compared to XRANGE

Redis command documentation: XREVRANGE

async xtrim(key: KeyT, trim_strategy: Literal[PureToken.MAXLEN, PureToken.MINID], threshold: int, trim_operator: Literal[PureToken.EQUAL, PureToken.APPROXIMATELY] | None = None, limit: int | None = None) int#

Redis command documentation: XTRIM

Compatibility:

async acl_cat(categoryname: StringT | None = None) tuple[AnyStr, ...]#

List the ACL categories or the commands inside a category

Returns:

a list of ACL categories or a list of commands inside a given category. The command may return an error if an invalid category name is given as argument.

Redis command documentation: ACL CAT

Compatibility:

New in version 3.0.0.

async acl_deluser(usernames: Parameters[StringT]) int#

Remove the specified ACL users and the associated rules

Returns:

The number of users that were deleted. This number will not always match the number of arguments since certain users may not exist.

Redis command documentation: ACL DELUSER

Compatibility:

New in version 3.0.0.

async acl_dryrun(username: StringT, command: StringT, *args: ValueT) bool#

Returns whether the user can execute the given command without executing the command.

Redis command documentation: ACL DRYRUN

Compatibility:

New in version 3.0.0.

async acl_genpass(bits: int | None = None) AnyStr#

Generate a pseudorandom secure password to use for ACL users

Returns:

by default 64 bytes string representing 256 bits of pseudorandom data. Otherwise if an argument if needed, the output string length is the number of specified bits (rounded to the next multiple of 4) divided by 4.

Redis command documentation: ACL GENPASS

Compatibility:

New in version 3.0.0.

async acl_getuser(username: StringT) dict[AnyStr, list[AnyStr] | set[AnyStr]]#

Get the rules for a specific ACL user

Redis command documentation: ACL GETUSER

Compatibility:

New in version 3.0.0.

async acl_list() tuple[AnyStr, ...]#

List the current ACL rules in ACL config file format

Redis command documentation: ACL LIST

Compatibility:

New in version 3.0.0.

async acl_load() bool#

Reload the ACLs from the configured ACL file

Returns:

True if successful. The command may fail with an error for several reasons:

  • if the file is not readable

  • if there is an error inside the file, and in such case the error will be reported to the user in the error.

  • Finally the command will fail if the server is not configured to use an external ACL file.

Redis command documentation: ACL LOAD

Compatibility:

New in version 3.0.0.

async acl_log(count: int | None = None, reset: bool | None = None) bool | tuple[dict[AnyStr, ResponsePrimitive] | None, ...]#

List latest events denied because of ACLs in place

Returns:

When called to show security events a list of ACL security events. When called with RESET True if the security log was cleared.

Redis command documentation: ACL LOG

Compatibility:

New in version 3.0.0.

async acl_save() bool#

Save the current ACL rules in the configured ACL file

Returns:

True if successful. The command may fail with an error for several reasons: - if the file cannot be written, or - if the server is not configured to use an external ACL file.

Redis command documentation: ACL SAVE

Compatibility:

New in version 3.0.0.

async acl_setuser(username: StringT, *rules: StringT) bool#

Modify or create the rules for a specific ACL user

Returns:

True if successful. If the rules contain errors, the error is returned.

Redis command documentation: ACL SETUSER

Compatibility:

New in version 3.0.0.

async acl_users() tuple[AnyStr, ...]#

List the username of all the configured ACL rules

Redis command documentation: ACL USERS

Compatibility:

New in version 3.0.0.

async acl_whoami() AnyStr#

Return the name of the user associated to the current connection

Returns:

the username of the current connection.

Redis command documentation: ACL WHOAMI

Compatibility:

New in version 3.0.0.

async command() dict[str, Command]#

Get Redis command details

Returns:

Mapping of command details. Commands are returned in random order.

Redis command documentation: COMMAND

New in version 3.0.0.

async command_count() int#

Get total number of Redis commands

Returns:

number of commands returned by COMMAND

Redis command documentation: COMMAND COUNT

New in version 3.0.0.

async command_docs(*command_names: StringT) dict[AnyStr, dict[AnyStr, ResponseType]]#

Mapping of commands to a dictionary containing it’s documentation

Redis command documentation: COMMAND DOCS

Compatibility:

New in version 3.1.0.

async command_getkeys(command: StringT, arguments: Parameters[ValueT]) Tuple[AnyStr, ...]#

Extract keys given a full Redis command

Returns:

Keys from your command.

Redis command documentation: COMMAND GETKEYS

New in version 3.0.0.

async command_getkeysandflags(command: StringT, arguments: Parameters[ValueT]) Dict[AnyStr, Set[AnyStr]]#

Extract keys from a full Redis command and their usage flags.

Returns:

Mapping of keys from your command to flags

Redis command documentation: COMMAND GETKEYSANDFLAGS

Compatibility:

New in version 3.1.0.

async command_info(*command_names: StringT) dict[str, Command]#

Get specific Redis command details, or all when no argument is given.

Returns:

mapping of command details.

Redis command documentation: COMMAND INFO

New in version 3.0.0.

async command_list(module: StringT | None = None, aclcat: StringT | None = None, pattern: StringT | None = None) set[AnyStr]#

Get an array of Redis command names

Redis command documentation: COMMAND LIST

Compatibility:

New in version 3.1.0.

async config_get(parameters: Parameters[StringT]) Dict[AnyStr, AnyStr]#

Get the values of configuration parameters

Redis command documentation: CONFIG GET

async config_resetstat() bool#

Resets runtime statistics

Redis command documentation: CONFIG RESETSTAT

async config_rewrite() bool#

Rewrites config file with the minimal change to reflect running config

Redis command documentation: CONFIG REWRITE

async config_set(parameter_values: Mapping[StringT, ValueT]) bool#

Sets configuration parameters to the given values

Redis command documentation: CONFIG SET

async dbsize() int#

Returns the number of keys in the current database

Redis command documentation: DBSIZE

async debug_object(key: KeyT) dict[str, str | int]#

Returns version specific meta information about a given key

Redis command documentation: DEBUG OBJECT

async failover(host: StringT | None = None, port: int | None = None, force: bool | None = None, abort: bool | None = None, timeout: int | timedelta | None = None) bool#

Start a coordinated failover between this server and one of its replicas.

Returns:

True if the command was accepted and a coordinated failover is in progress.

Redis command documentation: FAILOVER

Compatibility:

New in version 3.0.0.

async flushall(async_: Literal[PureToken.ASYNC, PureToken.SYNC] | None = None) bool#

Deletes all keys in all databases on the current host

Redis command documentation: FLUSHALL

async flushdb(async_: Literal[PureToken.ASYNC, PureToken.SYNC] | None = None) bool#

Deletes all keys in the current database

Redis command documentation: FLUSHDB

async info(*sections: StringT) dict[str, ResponseType]#

Get information and statistics about the server

The sections option can be used to select a specific section(s) of information.

Redis command documentation: INFO

async lastsave() datetime#

Get the time of the last successful save to disk

Redis command documentation: LASTSAVE

async latency_doctor() AnyStr#

Return a human readable latency analysis report.

Redis command documentation: LATENCY DOCTOR

New in version 3.0.0.

async latency_graph(event: StringT) AnyStr#

Return a latency graph for the event.

Redis command documentation: LATENCY GRAPH

New in version 3.0.0.

async latency_histogram(*commands: StringT) dict[AnyStr, dict[AnyStr, ValueT]]#

Return the cumulative distribution of latencies of a subset of commands or all.

Redis command documentation: LATENCY HISTOGRAM

Compatibility:

New in version 3.2.0.

async latency_history(event: StringT) tuple[AnyStr, ...]#

Return timestamp-latency samples for the event.

Returns:

The command returns a tuple where each element is a tuple representing the timestamp and the latency of the event.

Redis command documentation: LATENCY HISTORY

New in version 3.0.0.

async latency_latest() dict[AnyStr, tuple[int, int, int]]#

Return the latest latency samples for all events.

Returns:

Mapping of event name to (timestamp, latest, all-time) triplet

Redis command documentation: LATENCY LATEST

New in version 3.0.0.

async latency_reset(*events: StringT) int#

Reset latency data for one or more events.

Returns:

the number of event time series that were reset.

Redis command documentation: LATENCY RESET

New in version 3.0.0.

async lolwut(version: int | None = None) AnyStr#

Get the Redis version and a piece of generative computer art

Redis command documentation: LOLWUT

async memory_doctor() AnyStr#

Outputs memory problems report

Redis command documentation: MEMORY DOCTOR

New in version 3.0.0.

async memory_malloc_stats() AnyStr#

Show allocator internal stats :return: the memory allocator’s internal statistics report

Redis command documentation: MEMORY MALLOC-STATS

New in version 3.0.0.

async memory_purge() bool#

Ask the allocator to release memory

Redis command documentation: MEMORY PURGE

New in version 3.0.0.

async memory_stats() dict[AnyStr, ValueT]#

Show memory usage details :return: mapping of memory usage metrics and their values

Redis command documentation: MEMORY STATS

New in version 3.0.0.

async memory_usage(key: KeyT, *, samples: int | None = None) int | None#

Estimate the memory usage of a key

Returns:

the memory usage in bytes, or None when the key does not exist.

Redis command documentation: MEMORY USAGE

New in version 3.0.0.

async module_list() tuple[dict[AnyStr, ResponsePrimitive], ...]#

List all modules loaded by the server

Returns:

The loaded modules with each element represents a module containing a mapping with name and ver

Redis command documentation: MODULE LIST

New in version 3.2.0.

async module_load(path: StringT, *args: str | bytes | int | float) bool#

Load a module

Redis command documentation: MODULE LOAD

New in version 3.2.0.

async module_loadex(path: StringT, configs: Dict[StringT, ValueT] | None = None, args: Parameters[ValueT] | None = None) bool#

Loads a module from a dynamic library at runtime with configuration directives.

Redis command documentation: MODULE LOADEX

Compatibility:

New in version 3.4.0.

async module_unload(name: StringT) bool#

Unload a module

Redis command documentation: MODULE UNLOAD

New in version 3.2.0.

async replicaof(host: StringT | None = None, port: int | None = None) bool#

Make the server a replica of another instance, or promote it as master.

Redis command documentation: REPLICAOF

New in version 3.0.0.

async role() RoleInfo#

Provides information on the role of a Redis instance in the context of replication, by returning if the instance is currently a master, slave, or sentinel. The command also returns additional information about the state of the replication (if the role is master or slave) or the list of monitored master names (if the role is sentinel).

Redis command documentation: ROLE

async save() bool#

Tells the Redis server to save its data to disk, blocking until the save is complete

Redis command documentation: SAVE

async shutdown(nosave_save: Literal[PureToken.NOSAVE, PureToken.SAVE] | None = None, *, now: bool | None = None, force: bool | None = None, abort: bool | None = None) bool#

Stops Redis server

Redis command documentation: SHUTDOWN

Compatibility:

async slaveof(host: StringT | None = None, port: int | None = None) bool#

Sets the server to be a replicated slave of the instance identified by the host and port. If called without arguments, the instance is promoted to a master instead.

Redis command documentation: SLAVEOF

async slowlog_get(count: int | None = None) tuple[SlowLogInfo, ...]#

Gets the entries from the slowlog. If count is specified, get the most recent count items.

Redis command documentation: SLOWLOG GET

async slowlog_len() int#

Gets the number of items in the slowlog

Redis command documentation: SLOWLOG LEN

async slowlog_reset() bool#

Removes all items in the slowlog

Redis command documentation: SLOWLOG RESET

async swapdb(index1: int, index2: int) bool#

Swaps two Redis databases

Redis command documentation: SWAPDB

New in version 3.0.0.

async time() datetime#

Returns the server time as a 2-item tuple of ints: (seconds since epoch, microseconds into this second).

Redis command documentation: TIME

async asking() bool#

Sent by cluster clients after an -ASK redirect

Redis command documentation: ASKING

New in version 3.0.0.

async cluster_addslots(slots: Parameters[int]) bool#

Assign new hash slots to receiving node

Redis command documentation: CLUSTER ADDSLOTS

async cluster_addslotsrange(slots: Parameters[Tuple[int, int]]) bool#

Assign new hash slots to receiving node

Redis command documentation: CLUSTER ADDSLOTSRANGE

Compatibility:

New in version 3.1.1.

async cluster_bumpepoch() AnyStr#

Advance the cluster config epoch

Returns:

BUMPED if the epoch was incremented, or STILL if the node already has the greatest config epoch in the cluster.

Redis command documentation: CLUSTER BUMPEPOCH

New in version 3.0.0.

async cluster_count_failure_reports(node_id: StringT) int#

Return the number of failure reports active for a given node

Redis command documentation: CLUSTER COUNT-FAILURE-REPORTS

async cluster_countkeysinslot(slot: int) int#

Return the number of local keys in the specified hash slot

Redis command documentation: CLUSTER COUNTKEYSINSLOT

async cluster_delslots(slots: Parameters[int]) bool#

Set hash slots as unbound in the cluster. It determines by it self what node the slot is in and sends it there

Redis command documentation: CLUSTER DELSLOTS

async cluster_delslotsrange(slots: Parameters[Tuple[int, int]]) bool#

Set hash slots as unbound in receiving node

Redis command documentation: CLUSTER DELSLOTSRANGE

Compatibility:

New in version 3.1.1.

async cluster_failover(options: Literal[PureToken.FORCE, PureToken.TAKEOVER] | None = None) bool#

Forces a replica to perform a manual failover of its master.

Redis command documentation: CLUSTER FAILOVER

async cluster_flushslots() bool#

Delete a node’s own slots information

Redis command documentation: CLUSTER FLUSHSLOTS

New in version 3.0.0.

async cluster_forget(node_id: StringT) bool#

remove a node via its node ID from the set of known nodes of the Redis Cluster node receiving the command

Redis command documentation: CLUSTER FORGET

async cluster_getkeysinslot(slot: int, count: int) tuple[AnyStr, ...]#

Return local key names in the specified hash slot

Returns:

count key names

Redis command documentation: CLUSTER GETKEYSINSLOT

New in version 3.0.0.

async cluster_info() dict[str, str]#

Provides info about Redis Cluster node state

Redis command documentation: CLUSTER INFO

async cluster_keyslot(key: KeyT) int#

Returns the hash slot of the specified key

Redis command documentation: CLUSTER KEYSLOT

Returns a list of all TCP links to and from peer nodes in cluster

Returns:

A map of maps where each map contains various attributes and their values of a cluster link.

Redis command documentation: CLUSTER LINKS

Compatibility:

New in version 3.1.1.

async cluster_meet(ip: StringT, port: int, cluster_bus_port: int | None = None) bool#

Force a node cluster to handshake with another node.

Redis command documentation: CLUSTER MEET

async cluster_myid() AnyStr#

Return the node id

Redis command documentation: CLUSTER MYID

New in version 3.1.1.

async cluster_nodes() list[ClusterNodeDetail]#

Get Cluster config for the node

Redis command documentation: CLUSTER NODES

async cluster_replicas(node_id: StringT) list[ClusterNodeDetail]#

List replica nodes of the specified master node

Redis command documentation: CLUSTER REPLICAS

async cluster_replicate(node_id: StringT) bool#

Reconfigure a node as a replica of the specified master node

Redis command documentation: CLUSTER REPLICATE

async cluster_reset(hard_soft: Literal[PureToken.HARD, PureToken.SOFT] | None = None) bool#

Reset a Redis Cluster node

Redis command documentation: CLUSTER RESET

async cluster_saveconfig() bool#

Forces the node to save cluster state on disk

Redis command documentation: CLUSTER SAVECONFIG

async cluster_set_config_epoch(config_epoch: int) bool#

Set the configuration epoch in a new node

Redis command documentation: CLUSTER SET-CONFIG-EPOCH

async cluster_setslot(slot: int, *, importing: StringT | None = None, migrating: StringT | None = None, node: StringT | None = None, stable: bool | None = None) bool#

Bind a hash slot to a specific node

Redis command documentation: CLUSTER SETSLOT

async cluster_shards() list[dict[AnyStr, list[ValueT] | Mapping[AnyStr, ValueT]]]#

Get mapping of cluster slots to nodes

Redis command documentation: CLUSTER SHARDS

Compatibility:

New in version 3.2.0.

async cluster_slaves(node_id: StringT) list[ClusterNodeDetail]#

List replica nodes of the specified master node

Redis command documentation: CLUSTER SLAVES

async cluster_slots() dict[tuple[int, int], tuple[ClusterNode, ...]]#

Get mapping of Cluster slot to nodes

Redis command documentation: CLUSTER SLOTS

async readonly() bool#

Enables read queries for a connection to a cluster replica node

Redis command documentation: READONLY

New in version 3.2.0.

async readwrite() bool#

Disables read queries for a connection to a cluster replica node

Redis command documentation: READWRITE

New in version 3.2.0.

async auth(password: StringT, username: StringT | None = None) bool#

Authenticate to the server

Redis command documentation: AUTH

Compatibility:

Warning

Using auth directly is not recommended. Use the Redis.username and Redis.password arguments when initializing the client to ensure that all connections originating from this client are authenticated before being made available.

New in version 3.0.0.

async bgrewriteaof() bool#

Tell the Redis server to rewrite the AOF file from data in memory

Redis command documentation: BGREWRITEAOF

async bgsave(schedule: bool | None = None) bool#

Tells the Redis server to save its data to disk. Unlike save(), this method is asynchronous and returns immediately.

Redis command documentation: BGSAVE

async client_caching(mode: Literal[PureToken.NO, PureToken.YES]) bool#

Instruct the server about tracking or not keys in the next request

Redis command documentation: CLIENT CACHING

Compatibility:

New in version 3.0.0.

async client_getname() AnyStr | None#

Returns the current connection name

Returns:

The connection name, or None if no name is set.

Redis command documentation: CLIENT GETNAME

async client_getredir() int#

Get tracking notifications redirection client ID if any

Returns:

the ID of the client we are redirecting the notifications to. The command returns -1 if client tracking is not enabled, or 0 if client tracking is enabled but we are not redirecting the notifications to any client.

Redis command documentation: CLIENT GETREDIR

Compatibility:

New in version 3.0.0.

async client_id() int#

Returns the client ID for the current connection

Returns:

The id of the client.

Redis command documentation: CLIENT ID

New in version 3.0.0.

async client_info() ClientInfo#

Returns information about the current client connection.

Redis command documentation: CLIENT INFO

Compatibility:

New in version 3.0.0.

async client_kill(ip_port: StringT | None = None, identifier: int | None = None, type_: Literal[PureToken.NORMAL, PureToken.MASTER, PureToken.SLAVE, PureToken.REPLICA, PureToken.PUBSUB] | None = None, user: StringT | None = None, addr: StringT | None = None, laddr: StringT | None = None, skipme: bool | None = None) int | bool#

Disconnects the client at ip_port

Returns:

True if the connection exists and has been closed or the number of clients killed.

Redis command documentation: CLIENT KILL

Compatibility:

async client_list(type_: Literal[PureToken.MASTER, PureToken.NORMAL, PureToken.PUBSUB, PureToken.REPLICA] | None = None, identifiers: Parameters[int] | None = None) Tuple[ClientInfo, ...]#

Get client connections

Returns:

a tuple of dictionaries containing client fields

Redis command documentation: CLIENT LIST

Compatibility:

async client_no_evict(enabled: Literal[PureToken.ON, PureToken.OFF]) bool#

Set client eviction mode for the current connection

Redis command documentation: CLIENT NO-EVICT

Compatibility:

Warning

Using client_no_evict directly is not recommended. Use Redis.noevict argument when initializing the client to ensure that all connections originating from this client use the desired mode

New in version 3.2.0.

async client_no_touch(enabled: Literal[PureToken.OFF, PureToken.ON]) bool#

Controls whether commands sent by the client will alter the LRU/LFU of the keys they access.

Redis command documentation: CLIENT NO-TOUCH

Compatibility:

Warning

Using client_no_touch directly is not recommended. Use Redis.notouch argument when initializing the client to ensure that all connections originating from this client use the desired mode

New in version 4.12.0.

async client_pause(timeout: int, mode: Literal[PureToken.WRITE, PureToken.ALL] | None = None) bool#

Stop processing commands from clients for some time

Returns:

The command returns True or raises an error if the timeout is invalid.

Redis command documentation: CLIENT PAUSE

Compatibility:

async client_reply(mode: Literal[PureToken.OFF, PureToken.ON, PureToken.SKIP]) bool#

Instruct the server whether to reply to commands

Redis command documentation: CLIENT REPLY

Danger

Using client_reply directly is not supported. Use the Redis.noreply argument when initializing the client to ensure that all connections originating from this client disable or enable replies. You can also use the Redis.ignore_replies() context manager to selectively execute certain commands without waiting for a reply

New in version 3.0.0.

async client_setinfo(lib_name: StringT | None = None, lib_ver: StringT | None = None) bool#

Set client or connection specific info

Parameters:
  • lib_name – name of the library

  • lib_ver – version of the library

Redis command documentation: CLIENT SETINFO

Compatibility:

Warning

Using client_setinfo directly is not recommended. Coredis sets the library name and version by default during the handshake phase.Explicitly calling this command will only apply to the connection from the pool that was used to send it and not for subsequent commands

New in version 4.12.0.

async client_setname(connection_name: StringT) bool#

Set the current connection name :return: If the connection name was successfully set.

Redis command documentation: CLIENT SETNAME

Warning

Using client_setname directly is not recommended. Use the Redis.client_name argument when initializing the client to ensure the client name is consistent across all connections originating from the client

async client_tracking(status: Literal[PureToken.OFF, PureToken.ON], *prefixes: StringT, redirect: int | None = None, bcast: bool | None = None, optin: bool | None = None, optout: bool | None = None, noloop: bool | None = None) bool#

Enable or disable server assisted client side caching support

Returns:

If the connection was successfully put in tracking mode or if the tracking mode was successfully disabled.

Redis command documentation: CLIENT TRACKING

Compatibility:

New in version 3.0.0.

async client_trackinginfo() dict[AnyStr, AnyStr | set[AnyStr] | list[AnyStr]]#

Return information about server assisted client side caching for the current connection

Returns:

a mapping of tracking information sections and their respective values

Redis command documentation: CLIENT TRACKINGINFO

Compatibility:

New in version 3.0.0.

async client_unblock(client_id: int, timeout_error: Literal[PureToken.TIMEOUT, PureToken.ERROR] | None = None) bool#

Unblock a client blocked in a blocking command from a different connection

Returns:

Whether the client was unblocked

Redis command documentation: CLIENT UNBLOCK

New in version 3.0.0.

async client_unpause() bool#

Resume processing of clients that were paused

Returns:

The command returns `True`

Redis command documentation: CLIENT UNPAUSE

Compatibility:

New in version 3.0.0.

async echo(message: StringT) AnyStr#

Echo the string back from the server

Redis command documentation: ECHO

async hello(protover: int | None = None, username: StringT | None = None, password: StringT | None = None, setname: StringT | None = None) dict[AnyStr, AnyStr]#

Handshake with Redis

Returns:

a mapping of server properties.

Redis command documentation: HELLO

Compatibility:

New in version 3.0.0.

async ping(message: StringT | None = None) AnyStr#

Ping the server

Returns:

PONG, when no argument is provided else the message provided

Redis command documentation: PING

async quit() bool#

Close the connection

Redis command documentation: QUIT

async reset() None#

Reset the connection

Redis command documentation: RESET

Compatibility:

New in version 3.0.0.

async select(index: int) bool#

Change the selected database for the current connection

Redis command documentation: SELECT

Warning

Using select directly is not recommended. Use the db argument when initializing the client to ensure that all connections originating from this client use the desired database number

New in version 3.0.0.

async sentinel_config_get(name: ValueT) dict[AnyStr, AnyStr]#

Get the current value of a global Sentinel configuration parameter. The specified name may be a wildcard, similar to config_get()

Compatibility:

async sentinel_config_set(name: ValueT, value: ValueT) bool#

Set the value of a global Sentinel configuration parameter

Compatibility:

async sentinel_failover(service_name: StringT) bool#

Force a failover as if the master was not reachable, and without asking for agreement to other Sentinels

async sentinel_flushconfig() bool#

Force Sentinel to rewrite its configuration on disk, including the current Sentinel state.

async sentinel_get_master_addr_by_name(service_name: StringT) tuple[str, int] | None#

Returns a (host, port) pair for the given service_name

async sentinel_infocache(*nodenames: StringT) dict[AnyStr, dict[int, dict[str, ResponseType]]]#

Return cached INFO output from masters and replicas.

async sentinel_master(service_name: StringT) dict[str, int | bool | str]#

Returns a dictionary containing the specified masters state.

async sentinel_masters() dict[str, dict[str, int | bool | str]]#

Returns a list of dictionaries containing each master’s state.

async sentinel_monitor(name: ValueT, ip: ValueT, port: int, quorum: int) bool#

Adds a new master to Sentinel to be monitored

async sentinel_myid() AnyStr#

Return the ID of the Sentinel instance Compatibility:

async sentinel_remove(name: ValueT) bool#

Removes a master from Sentinel’s monitoring

async sentinel_replicas(service_name: StringT) tuple[dict[str, int | bool | str], ...]#

Returns a list of replicas for service_name

async sentinel_reset(pattern: StringT) int#

Reset all the masters with matching name. The pattern argument is a glob-style pattern. The reset process clears any previous state in a master (including a failover in progress), and removes every replica and sentinel already discovered and associated with the master.

async sentinel_sentinels(service_name: StringT) tuple[dict[str, int | bool | str], ...]#

Returns a list of sentinels for service_name

async sentinel_set(name: ValueT, option: ValueT, value: ValueT) bool#

Sets Sentinel monitoring parameters for a given master

async sentinel_slaves(service_name: StringT) tuple[dict[str, int | bool | str], ...]#

Returns a list of slaves for paramref:service_name

property autocomplete: Autocomplete#

Property to access Autocomplete commands.

New in version 4.12.0.

property bf: BloomFilter#

Property to access BloomFilter commands.

New in version 4.12.0.

property cf: CuckooFilter#

Property to access CuckooFilter commands.

New in version 4.12.0.

property cms: CountMinSketch#

Property to access CountMinSketch commands.

New in version 4.12.0.

property graph: Graph#

Property to access Graph commands.

New in version 4.12.0.

property json: Json#

Property to access Json commands.

New in version 4.12.0.

property search: Search#

Property to access Search commands.

New in version 4.12.0.

property tdigest: TDigest#

Property to access TDigest commands.

New in version 4.12.0.

property timeseries: TimeSeries#

Property to access TimeSeries commands.

New in version 4.12.0.

property topk: TopK#

Property to access TopK commands.

New in version 4.12.0.

Cluster#

class RedisCluster(host: str | None = None, port: int | None = None, *, startup_nodes: Iterable[Node] | None = None, stream_timeout: float | None = None, connect_timeout: float | None = None, ssl: bool = False, ssl_context: SSLContext | None = None, ssl_keyfile: str | None = None, ssl_certfile: str | None = None, ssl_cert_reqs: