Redis Modules¶

coredis.modules

Redis module commands in coredis are exposed under properties of the Redis or RedisCluster clients such as json, bf. These properties in turn return instances of the module command group containers which are bound to the client.

The module commands can also be accessed by instantiating the module command group classes (listed in the sections below) directly.

To access the Json command group from the coredis.modules.RedisJSON module for example:

import coredis

client = coredis.Redis()

# through the client
await client.json.get("key", "$")
# or directly
json = coredis.modules.Json(client)
await json.get("key", "$")

RedisJSON¶

class Json(client: AbstractExecutor)[source]¶

Container for the commands in the json command group of the RedisJSON module.

Added in version 4.12.

async delete(key: KeyT, path: StringT | None = None) → int[source]¶

Delete a value from a JSON document.

Parameters:

key¶ – The key of the JSON document.
path¶ – The JSONPath to specify.

Returns:

The number of paths deleted

RedisJSON command documentation: JSON.DEL

Gets the value at one or more paths

Parameters:

key¶ – The key of the JSON document.
paths¶ – JSONPath(s) to get values from.

Returns:

The value at path

RedisJSON command documentation: JSON.GET

Hint

Supports client side caching

async forget(key: KeyT, path: ValueT | None = None) → int[source]¶

Deletes an element from a path from a json object

Parameters:

key¶ – The key of the JSON document.
path¶ – The path(s) to delete from the JSON object.

Returns:

The number of deleted elements.

RedisJSON command documentation: JSON.FORGET

Toggles a boolean value

Parameters:

key¶ – Redis key to modify.
path¶ – JSONPath to specify.

Returns:

A list of integer replies for each path, the new value (0 if false or 1 if true), or None for JSON values matching the path that are not Boolean.

RedisJSON command documentation: JSON.TOGGLE

Compatibility:

New in RedisJSON version: 2.0.0

async clear(key: KeyT, path: ValueT | None = None) → int[source]¶

Clears all values from an array or an object and sets numeric values to 0

Parameters:

key¶ – The key to parse.
path¶ – The JSONPath to specify.

Returns:

The number of values cleared.

RedisJSON command documentation: JSON.CLEAR

Compatibility:

New in RedisJSON version: 2.0.0

Sets or updates the JSON value at a path

Parameters:

key¶ – The key to parse.
path¶ – JSONPath to specify. For new Redis keys the path must be the root. For existing keys, when the entire path exists, the value that it contains is replaced with value. For existing keys, when the path exists, except for the last element, a new child is added with value. Adds a key (with its respective value) to a JSON Object (in a json data type key) only if it is the last child in the path, or it is the parent of a new child being added in the path. Optional argument condition modifies this behavior for both new json data type keys as well as the JSON Object keys in them.
value¶ – Value to set at the specified path.
condition¶ – Optional argument to modify the behavior of adding a key to a JSON Object. If NX, the key is set only if it does not already exist. If XX, the key is set only if it already exists.

Returns:

True if the value was set successfully, False otherwise.

RedisJSON command documentation: JSON.SET

async mget(keys: Parameters[KeyT], path: StringT) → JsonType[source]¶

Returns the values at a path from one or more keys

Parameters:

keys¶ – one or more keys to retrieve values from.
path¶ – JSONPath to specify.

Returns:

The values at path for each of the keys in keys.

RedisJSON command documentation: JSON.MGET

async mset(triplets: Parameters[Tuple[KeyT, StringT, JsonType]]) → bool[source]¶

Sets or updates the JSON value of one or more keys

Parameters:: triplets¶ – Collection of triplets containing (key, path, value) to set.
Returns:: True if all the values were set successfully

RedisJSON command documentation: JSON.MSET

Compatibility:

New in RedisJSON version: 2.6.0

Merge a JSON object into an existing Redis key at a specified path.

Parameters:

key¶ – The Redis key to merge the JSON object into.
path¶ – The JSONPath within the Redis key to merge the JSON object into.
value¶ – The JSON object to merge into the Redis key.

Returns:

True if the merge was successful, False otherwise.

RedisJSON command documentation: JSON.MERGE

Compatibility:

New in RedisJSON version: 2.6.0

Increments the numeric value at path by a value

Parameters:

key¶ – The key to modify.
path¶ – The JSONPath to specify.
value¶ – The number value to increment.

RedisJSON command documentation: JSON.NUMINCRBY

Multiplies the numeric value at path by a value

Parameters:

key¶ – Key to modify.
path¶ – JSONPath to specify.
value¶ – Number value to multiply.

RedisJSON command documentation: JSON.NUMMULTBY

Appends a string to a JSON string value at path

Parameters:

key¶ – The key to modify
value¶ – The value to append to the string(s) at the specified path.
path¶ – The JSONPath to specify the location of the string(s) to modify.

Returns:

A list of integer replies for each path, the string’s new length, or None if the matching JSON value is not a string.

RedisJSON command documentation: JSON.STRAPPEND

async strlen(key: KeyT, path: KeyT | None = None) → int | list[int | None] | None[source]¶

Returns the length of the JSON String at path in key

Parameters:

key¶ – The key of the JSON document.
path¶ – JSONPath to specify.

Returns:

An array of integer replies for each path, the array’s length, or None, if the matching JSON value is not a string.

RedisJSON command documentation: JSON.STRLEN

Hint

Supports client side caching

async arrappend(key: KeyT, values: Parameters[JsonType], path: KeyT | None = None) → int | List[int | None] | None[source]¶

Append one or more json values into the array at path after the last element in it.

Parameters:

key¶ – The key to modify.
values¶ – One or more values to append to one or more arrays.
path¶ – JSONPath to specify.

Returns:

An array of integer replies for each path, the array’s new size, or None if the matching JSON value is not an array.

RedisJSON command documentation: JSON.ARRAPPEND

Returns the index of the first occurrence of a JSON scalar value in the array at path

Parameters:

key¶ – The key to parse.
path¶ – The JSONPath to specify.
value¶ – The value to find its index in one or more arrays.
start¶ – Inclusive start value to specify in a slice of the array to search.
stop¶ – Exclusive stop value to specify in a slice of the array to search, including the last element. Negative values are interpreted as starting from the end.

Returns:

The index of the first occurrence of the value in the array, or a list of indices if the value is found in multiple arrays.

RedisJSON command documentation: JSON.ARRINDEX

Hint

Supports client side caching

async arrinsert(key: KeyT, path: ValueT, index: int, values: Parameters[JsonType]) → int | List[int | None] | None[source]¶

Inserts the JSON scalar(s) value at the specified index in the array at path

Parameters:

key¶ – Key to modify.
path¶ – JSONPath to specify.
index¶ – Position in the array where you want to insert a value. The index must be in the array’s range. Inserting at index 0 prepends to the array. Negative index values start from the end of the array.
values¶ – One or more values to insert in one or more arrays.

Returns:

The length of the array after the insert operation or a list of lengths of the arrays after the insert operation if the path matches multiple arrays

RedisJSON command documentation: JSON.ARRINSERT

async arrlen(key: KeyT, path: KeyT | None = None) → int | list[int | None] | None[source]¶

Returns the length of the array at path

Parameters:

key¶ – The key to parse.
path¶ – The JSONPath to specify.

Returns:

An integer if the matching value is an array, or a list of integers if multiple matching values are arrays. Returns None if the key or path do not exist.

RedisJSON command documentation: JSON.ARRLEN

Hint

Supports client side caching

Removes and returns the element at the specified index in the array at path

Parameters:

key¶ – Key to modify.
path¶ – JSONPath to specify.
index¶ – Position in the array to start popping from. Out-of-range indexes round to their respective array ends.

Returns:

The popped value, or None if the matching JSON value is not an array.

RedisJSON command documentation: JSON.ARRPOP

async arrtrim(key: KeyT, path: ValueT, start: int, stop: int) → int | list[int | None] | None[source]¶

Trims the array at path to contain only the specified inclusive range of indices from start to stop

Parameters:

key¶ – Key to modify.
path¶ – The JSONPath to specify.
start¶ – The index of the first element to keep (previous elements are trimmed).
stop¶ – The index of the last element to keep (following elements are trimmed), including the last element. Negative values are interpreted as starting from the end.

Returns:

The number of elements removed or a list if multiple matching values are arrays.

RedisJSON command documentation: JSON.ARRTRIM

async objkeys(key: KeyT, path: StringT | None = None) → ResponseType[source]¶

Returns the JSON keys of the object at path

Parameters:

key¶ – The key of the JSON document.
path¶ – JSONPath to specify.

Returns:

A list of the key names in the object or a list of lists if multiple objects match the path, or None if the matching value is not an object.

RedisJSON command documentation: JSON.OBJKEYS

async objlen(key: KeyT, path: KeyT | None = None) → int | list[int | None] | None[source]¶

Returns the number of keys of the object at path

Parameters:

key¶ – The key of the JSON document.
path¶ – JSONPath to specify.

Returns:

An integer if the path matches exactly one object or a list of integer replies for each path specified as the number of keys in the object or None, if the matching JSON value is not an object.

RedisJSON command documentation: JSON.OBJLEN

async type(key: KeyT, path: KeyT | None = None) → AnyStr | list[AnyStr | None] | None[source]¶

Returns the type of the JSON value at path

Parameters:

key¶ – The key to parse.
path¶ – The JSONPath to specify.

RedisJSON command documentation: JSON.TYPE

Hint

Supports client side caching

async resp(key: KeyT, path: KeyT | None = None) → ResponseType[source]¶

Returns the JSON value at path in Redis Serialization Protocol (RESP)

Parameters:

key¶ – The key to parse.
path¶ – The JSONPath to specify.

RedisJSON command documentation: JSON.RESP

Compatibility:

Deprecated in RedisJSON version: 2.6.0

async debug_memory(key: KeyT, path: KeyT | None = None) → int | list[int | None] | None[source]¶

Reports the size in bytes of a key

RedisJSON command documentation: JSON.DEBUG MEMORY

RedisBloom¶

BloomFilter¶

class BloomFilter(client: AbstractExecutor)[source]¶

Container for the commands in the bf command group of the RedisBloom module.

Added in version 4.12.

async reserve(key: KeyT, error_rate: int | float, capacity: int, expansion: int | None = None, nonscaling: bool | None = None) → bool[source]¶

Creates a new Bloom Filter

Parameters:

key¶ – The key under which the filter is found.
error_rate¶ – The desired probability for false positives.
capacity¶ – The number of entries intended to be added to the filter.
expansion¶ – The size of the new sub-filter when capacity is reached.
nonscaling¶ – Prevents the filter from creating additional sub-filters.

RedisBloom command documentation: BF.RESERVE

async add(key: KeyT, item: ValueT) → bool[source]¶

Adds an item to a Bloom Filter

Parameters:

key¶ – The key under which the filter is found.
item¶ – The item to add to the filter.

RedisBloom command documentation: BF.ADD

async madd(key: KeyT, items: Parameters[ValueT]) → Tuple[bool, ...][source]¶

Adds one or more items to a Bloom Filter. A filter will be created if it does not exist

Parameters:

key¶ – The key under which the filter is found.
items¶ – One or more items to add.

RedisBloom command documentation: BF.MADD

Adds one or more items to a Bloom Filter. A filter will be created if it does not exist

Parameters:

key¶ – The key under which the filter is found.
items¶ – One or more items to add.
capacity¶ – The desired capacity for the filter to be created.
error¶ – The error ratio of the newly created filter if it does not yet exist.
expansion¶ – The expansion factor for the filter when capacity is reached.
nocreate¶ – Indicates that the filter should not be created if it does not already exist.
nonscaling¶ – Prevents the filter from creating additional sub-filters if initial capacity is reached.

RedisBloom command documentation: BF.INSERT

async exists(key: KeyT, item: ValueT) → bool[source]¶

Checks whether an item exists in a Bloom Filter

Parameters:

key¶ – The key under which the filter is found.
item¶ – The item to check for existence.

RedisBloom command documentation: BF.EXISTS

Hint

Supports client side caching

async mexists(key: KeyT, items: Parameters[ValueT]) → Tuple[bool, ...][source]¶

Checks whether one or more items exist in a Bloom Filter

Parameters:

key¶ – The key under which the filter is found.
items¶ – One or more items to check.

RedisBloom command documentation: BF.MEXISTS

Hint

Supports client side caching

async scandump(key: KeyT, iterator: int) → tuple[int, bytes | None][source]¶

Begins an incremental save of the bloom filter

Parameters:

key¶ – The key under which the filter is found.
iterator¶ – Iterator value; either 0 to start a dump or the iterator from a previous invocation of this command.

Returns:

A tuple of iterator value and data. If iterator is 0, iteration has completed. The iterator-data pair should be passed to loadchunk() when restoring the filter.

RedisBloom command documentation: BF.SCANDUMP

async loadchunk(key: KeyT, iterator: int, data: bytes) → bool[source]¶

Restores a filter previously saved using scandump()

Parameters:

key¶ – Name of the key to restore.
iterator¶ – Iterator value associated with the data chunk.
data¶ – Current data chunk.

RedisBloom command documentation: BF.LOADCHUNK

async info(key: KeyT, single_value: Literal[PureToken.CAPACITY, PureToken.EXPANSION, PureToken.FILTERS, PureToken.ITEMS, PureToken.SIZE] | None = None) → dict[AnyStr, int] | int[source]¶

Returns information about a Bloom Filter

Parameters:

key¶ – The key name for an existing Bloom filter.
single_value¶ – Optional parameter to get a specific information field.

Returns:

A dictionary with all information fields if single_value is not specified, or an integer representing the value of the specified field.

RedisBloom command documentation: BF.INFO

Hint

Supports client side caching

async card(key: KeyT) → int[source]¶

Returns the cardinality of a Bloom filter

Parameters:: key¶ – The key name for an existing Bloom filter.

RedisBloom command documentation: BF.CARD

Compatibility:

New in RedisBloom version: 2.4.4

Hint

Supports client side caching

CuckooFilter¶

class CuckooFilter(client: AbstractExecutor)[source]¶

Container for the commands in the cf command group of the RedisBloom module.

Added in version 4.12.

async reserve(key: KeyT, capacity: int, bucketsize: int | None = None, maxiterations: int | None = None, expansion: int | None = None) → bool[source]¶

Creates a new Cuckoo Filter

Parameters:

key¶ – The name of the filter.
capacity¶ – Estimated capacity for the filter.
bucketsize¶ – Number of items in each bucket.
maxiterations¶ – Number of attempts to swap items between buckets before declaring filter as full and creating an additional filter.
expansion¶ – When a new filter is created, its size is the size of the current filter multiplied by expansion.

RedisBloom command documentation: CF.RESERVE

async add(key: KeyT, item: ValueT) → bool[source]¶

Adds an item to a Cuckoo Filter

Parameters:

key¶ – The name of the filter.
item¶ – The item to add.

RedisBloom command documentation: CF.ADD

async addnx(key: KeyT, item: ValueT) → bool[source]¶

Adds an item to a Cuckoo Filter if the item did not exist previously.

Parameters:

key¶ – The name of the filter.
item¶ – The item to add.

RedisBloom command documentation: CF.ADDNX

async insert(key: KeyT, items: Parameters[ValueT], capacity: int | None = None, nocreate: bool | None = None) → Tuple[bool, ...][source]¶

Adds one or more items to a Cuckoo Filter. A filter will be created if it does not exist

Parameters:

key¶ – The name of the filter.
items¶ – One or more items to add.
capacity¶ – Specifies the desired capacity of the new filter, if this filter does not exist yet.
nocreate¶ – If specified, prevents automatic filter creation if the filter does not exist.

Returns:

A tuple of boolean values indicating if the command was executed correctly.

RedisBloom command documentation: CF.INSERT

async insertnx(key: KeyT, items: Parameters[ValueT], capacity: int | None = None, nocreate: bool | None = None) → Tuple[bool, ...][source]¶

Adds one or more items to a Cuckoo Filter if the items did not exist previously. A filter will be created if it does not exist

Parameters:

key¶ – The name of the filter.
items¶ – One or more items to add.
capacity¶ – Specifies the desired capacity of the new filter, if this filter does not exist yet.
nocreate¶ – If specified, prevents automatic filter creation if the filter does not exist.

RedisBloom command documentation: CF.INSERTNX

async exists(key: KeyT, item: ValueT) → bool[source]¶

Checks whether an item exist in a Cuckoo Filter

Parameters:

key¶ – The name of the filter.
item¶ – The item to check for.

RedisBloom command documentation: CF.EXISTS

Hint

Supports client side caching

async mexists(key: KeyT, items: Parameters[ValueT]) → Tuple[bool, ...][source]¶

Checks whether one or more items exist in a Cuckoo Filter

Parameters:

key¶ – The name of the filter.
items¶ – The item(s) to check for.

RedisBloom command documentation: CF.MEXISTS

Hint

Supports client side caching

async delete(key: KeyT, item: ValueT) → bool[source]¶

Deletes an item from a Cuckoo Filter

Parameters:

key¶ – The name of the filter.
item¶ – The item to delete from the filter.

RedisBloom command documentation: CF.DEL

async count(key: KeyT, item: ValueT) → int[source]¶

Return the number of times an item might be in a Cuckoo Filter

Parameters:

key¶ – The name of the filter.
item¶ – The item to count.

RedisBloom command documentation: CF.COUNT

Hint

Supports client side caching

async scandump(key: KeyT, iterator: int) → tuple[int, bytes | None][source]¶

Begins an incremental save of the bloom filter

Parameters:

key¶ – Name of the filter.
iterator¶ – Iterator value. This is either 0, or the iterator from a previous invocation of this command.

RedisBloom command documentation: CF.SCANDUMP

async loadchunk(key: KeyT, iterator: int, data: StringT) → bool[source]¶

Restores a filter previously saved using SCANDUMP

Parameters:

key¶ – Name of the key to restore.
iter¶ – Iterator value associated with data (returned by scandump()).
data¶ – Current data chunk (returned by scandump()).

RedisBloom command documentation: CF.LOADCHUNK

async info(key: KeyT) → dict[AnyStr, ResponsePrimitive][source]¶

Returns information about a Cuckoo Filter

Parameters:: key¶ – The name of the filter.

RedisBloom command documentation: CF.INFO

Count Min Sketch¶

class CountMinSketch(client: AbstractExecutor)[source]¶

Container for the commands in the cms command group of the RedisBloom module.

Added in version 4.12.

async initbydim(key: KeyT, width: int, depth: int) → bool[source]¶

Initializes a Count-Min Sketch to dimensions specified by user

Parameters:

key¶ – Name of the sketch.
width¶ – Number of counters in each array. Reduces error size.
depth¶ – Number of counter-arrays. Reduces error probability.

RedisBloom command documentation: CMS.INITBYDIM

Compatibility:

New in RedisBloom version: 2.0.0

async initbyprob(key: KeyT, error: int | float, probability: int | float) → bool[source]¶

Initializes a Count-Min Sketch to accommodate requested tolerances.

Parameters:

key¶ – Name of the sketch.
error¶ – Estimate size of error as a percent of total counted items.
probability¶ – Desired probability for inflated count as a decimal value between 0 and 1.

RedisBloom command documentation: CMS.INITBYPROB

Compatibility:

New in RedisBloom version: 2.0.0

async incrby(key: KeyT, items: Mapping[AnyStr, int]) → tuple[int, ...][source]¶

Increases the count of one or more items by increment

Parameters:

key¶ – The name of the HyperLogLog sketch.
items¶ – A dictionary containing the items to increment and their respective increments.

RedisBloom command documentation: CMS.INCRBY

Compatibility:

New in RedisBloom version: 2.0.0

async query(key: KeyT, items: Parameters[StringT]) → Tuple[int, ...][source]¶

Returns the count for one or more items in a sketch

Parameters:

key¶ – The name of the Count-Min Sketch.
items¶ – One or more items for which to return the count.

RedisBloom command documentation: CMS.QUERY

Compatibility:

New in RedisBloom version: 2.0.0

Hint

Supports client side caching

async merge(destination: KeyT, sources: Parameters[KeyT], weights: Parameters[int | float] | None = None) → bool[source]¶

Merges several sketches into one sketch

Parameters:

destination¶ – The name of the destination sketch. Must be initialized.
sources¶ – Names of the source sketches to be merged.
weights¶ – Multiples of each sketch. Default is 1.

RedisBloom command documentation: CMS.MERGE

Compatibility:

New in RedisBloom version: 2.0.0

async info(key: KeyT) → dict[AnyStr, int][source]¶

Returns information about a sketch

Parameters:: key¶ – The name of the sketch.
Returns:: A dictionary containing the width, depth, and total count of the sketch.

RedisBloom command documentation: CMS.INFO

Compatibility:

New in RedisBloom version: 2.0.0

Hint

Supports client side caching

TDigest¶

class TDigest(client: AbstractExecutor)[source]¶

Container for the commands in the tdigest command group of the RedisBloom module.

Added in version 4.12.

async create(key: KeyT, compression: int | None = None) → bool[source]¶

Allocates memory and initializes a new t-digest sketch

Parameters:

key¶ – The key name for the new t-digest sketch.
compression¶ – A controllable tradeoff between accuracy and memory consumption.

RedisBloom command documentation: TDIGEST.CREATE

Compatibility:

New in RedisBloom version: 2.4.0

async reset(key: KeyT) → bool[source]¶

Resets a t-digest sketch: empty the sketch and re-initializes it.

Parameters:: key¶ – The key name for an existing t-digest sketch.

RedisBloom command documentation: TDIGEST.RESET

Compatibility:

New in RedisBloom version: 2.4.0

async add(key: KeyT, values: Parameters[int | float]) → bool[source]¶

Adds one or more observations to a t-digest sketch

Parameters:

key¶ – Key name for an existing t-digest sketch.
values¶ – value(s) of observation(s)

RedisBloom command documentation: TDIGEST.ADD

Compatibility:

New in RedisBloom version: 2.4.0

async merge(destination_key: KeyT, source_keys: Parameters[KeyT], compression: int | None = None, override: bool | None = None) → bool[source]¶

Merges multiple t-digest sketches into a single sketch

Parameters:

destination_key¶ – Key name for a t-digest sketch to merge observation values to. If it does not exist, a new sketch is created. If it is an existing sketch, its values are merged with the values of the source keys. To override the destination key contents use override.
source_keys¶ – Key names for t-digest sketches to merge observation values from.
compression¶ – Controllable tradeoff between accuracy and memory consumption.
override¶ – When specified, if destination_key already exists, it is overwritten.

RedisBloom command documentation: TDIGEST.MERGE

Compatibility:

New in RedisBloom version: 2.4.0

async min(key: KeyT) → float[source]¶

Returns the minimum observation value from a t-digest sketch

Parameters:: key¶ – The key name for an existing t-digest sketch.

RedisBloom command documentation: TDIGEST.MIN

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

async max(key: KeyT) → float[source]¶

Returns the maximum observation value from a t-digest sketch

Parameters:: key¶ – The key name for an existing t-digest sketch.

RedisBloom command documentation: TDIGEST.MAX

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

async quantile(key: KeyT, quantiles: Parameters[int | float]) → Tuple[float, ...][source]¶

Returns, for each input fraction, an estimation of the value (floating point) that is smaller than the given fraction of observations

Parameters:

key¶ – Key name for an existing t-digest sketch.
quantiles¶ – Input fractions (between 0 and 1 inclusively).

RedisBloom command documentation: TDIGEST.QUANTILE

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

async cdf(key: KeyT, values: Parameters[int | float]) → Tuple[float, ...][source]¶

Returns, for each input value, an estimation of the fraction (floating-point) of (observations smaller than the given value + half the observations equal to the given value)

Parameters:

key¶ – The key name for an existing t-digest sketch.
values¶ – The values for which the CDF should be retrieved.

RedisBloom command documentation: TDIGEST.CDF

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

async trimmed_mean(key: KeyT, low_cut_quantile: int | float, high_cut_quantile: int | float) → float[source]¶

Returns an estimation of the mean value from the sketch, excluding observation values outside the low and high cutoff quantiles

Parameters:

key¶ – The key name for an existing t-digest sketch.
low_cut_quantile¶ – A floating-point value in the range [0..1], should be lower than high_cut_quantile.
high_cut_quantile¶ – A floating-point value in the range [0..1], should be higher than low_cut_quantile.

RedisBloom command documentation: TDIGEST.TRIMMED_MEAN

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

async rank(key: KeyT, values: Parameters[int | float]) → Tuple[int, ...][source]¶

Returns, for each input value (floating-point), the estimated rank of the value (the number of observations in the sketch that are smaller than the value + half the number of observations that are equal to the value)

Parameters:

key¶ – The key name for an existing t-digest sketch.
values¶ – Input values for which the rank should be estimated.

RedisBloom command documentation: TDIGEST.RANK

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

async revrank(key: KeyT, values: Parameters[int | float]) → Tuple[int, ...][source]¶

Returns, for each input value (floating-point), the estimated reverse rank of the value (the number of observations in the sketch that are larger than the value + half the number of observations that are equal to the value)

Parameters:

key¶ – The name of an existing t-digest sketch.
values¶ – The input values for which the reverse rank should be estimated.

RedisBloom command documentation: TDIGEST.REVRANK

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

async byrank(key: KeyT, ranks: Parameters[int | float]) → Tuple[float, ...][source]¶

Returns, for each input rank, an estimation of the value (floating-point) with that rank

Parameters:

key¶ – The key name for an existing t-digest sketch.
ranks¶ – The ranks for which the estimated values should be retrieved.

RedisBloom command documentation: TDIGEST.BYRANK

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

async byrevrank(key: KeyT, reverse_ranks: Parameters[int | float]) → Tuple[float, ...][source]¶

Returns, for each input reverse rank, an estimation of the value (floating-point) with that reverse rank

Parameters:

key¶ – The key name for an existing t-digest sketch.
reverse_ranks¶ – The reverse ranks for which the values should be retrieved.

RedisBloom command documentation: TDIGEST.BYREVRANK

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

async info(key: KeyT) → dict[AnyStr, ResponsePrimitive][source]¶

Returns information and statistics about a t-digest sketch

Parameters:: key¶ – The key name for an existing t-digest sketch.
Returns:: Dictionary with information about the sketch, including compression, capacity, number of merged and unmerged nodes, weight of merged and unmerged nodes, number of observations, total compressions, and memory usage.

RedisBloom command documentation: TDIGEST.INFO

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

TopK¶

class TopK(client: AbstractExecutor)[source]¶

Container for the commands in the topk command group of the RedisBloom module.

Added in version 4.12.

async reserve(key: KeyT, topk: int, width: int | None = None, depth: int | None = None, decay: int | float | None = None) → bool[source]¶

Reserve a TopK sketch with specified parameters.

Parameters:

key¶ – Name of the TOP-K sketch.
topk¶ – Number of top occurring items to keep.
width¶ – Number of counters kept in each array.
depth¶ – Number of arrays.
decay¶ – The probability of reducing a counter in an occupied bucket. It is raised to power of it’s counter (decay ^ bucket[i].counter). Therefore, as the counter gets higher, the chance of a reduction is being reduced.

RedisBloom command documentation: TOPK.RESERVE

Compatibility:

New in RedisBloom version: 2.0.0

async add(key: KeyT, items: Parameters[AnyStr]) → Tuple[AnyStr | None, ...][source]¶

Increases the count of one or more items by increment

Parameters:

key¶ – Name of the TOP-K sketch.
items¶ – Item(s) to be added.

RedisBloom command documentation: TOPK.ADD

Compatibility:

New in RedisBloom version: 2.0.0

async incrby(key: KeyT, items: Mapping[AnyStr, int]) → tuple[AnyStr | None, ...][source]¶

Increases the count of one or more items by increment

Parameters:

key¶ – Name of the TOP-K sketch.
items¶ – Dictionary of items and their corresponding increment values.

RedisBloom command documentation: TOPK.INCRBY

Compatibility:

New in RedisBloom version: 2.0.0

async query(key: KeyT, items: Parameters[StringT]) → Tuple[bool, ...][source]¶

Checks whether an item is one of Top-K items. Multiple items can be checked at once.

Parameters:

key¶ – Name of the TOP-K sketch.
items¶ – Item(s) to be queried.

RedisBloom command documentation: TOPK.QUERY

Compatibility:

New in RedisBloom version: 2.0.0

Hint

Supports client side caching

async count(key: KeyT, items: Parameters[StringT]) → Tuple[int, ...][source]¶

Return the count for one or more items are in a sketch

Parameters:

key¶ – The name of the TOP-K sketch.
items¶ – One or more items to count.

RedisBloom command documentation: TOPK.COUNT

Compatibility:

New in RedisBloom version: 2.0.0

async list(key: KeyT, withcount: bool | None = None) → dict[AnyStr, int] | tuple[AnyStr, ...][source]¶

Return full list of items in Top K list

Parameters:

key¶ – Name of the TOP-K sketch.
withcount¶ – Whether to include counts of each element.

RedisBloom command documentation: TOPK.LIST

Compatibility:

New in RedisBloom version: 2.0.0

Hint

Supports client side caching

async info(key: KeyT) → dict[AnyStr, int][source]¶

Returns information about a sketch

Parameters:: key¶ – Name of the TOP-K sketch.
Returns:: A dictionary containing the following information: - k: The number of items tracked by the sketch. - width: The width of the sketch. - depth: The depth of the sketch. - decay: The decay factor used by the sketch.

RedisBloom command documentation: TOPK.INFO

Compatibility:

New in RedisBloom version: 2.0.0

Hint

Supports client side caching

RedisSearch¶

Search & Aggregation¶

class Search(client: AbstractExecutor)[source]¶

Container for the commands in the search command group of the RediSearch module.

Added in version 4.12.

Creates an index with the given spec

Parameters:

index¶ – The name of the index to create.
schema¶ – A list of schema fields
on¶ – The type of Redis key to index.
prefixes¶ – A list of key prefixes to index.
filter_expression¶ – A filter expression to apply to the index.
language¶ – The default language to use for text fields.
language_field¶ – The name of the field to use for language detection.
score¶ – The default score to use for documents.
score_field¶ – The name of the field to use for document scoring.
payload_field¶ – The name of the field to use for document payloads.
maxtextfields¶ – If True, the maximum number of text fields will be used.
temporary¶ – If specified, the index will be temporary and will expire after the given number of seconds.
nooffsets¶ – If True, term offsets will not be stored.
nohl¶ – If True, search results will not include highlighted snippets.
nofields¶ – If True, search results will not include field values.
nofreqs¶ – If True, term frequencies will not be stored.
stopwords¶ – A list of stopwords to ignore.
skipinitialscan¶ – If True, the initial scan of the index will be skipped.

RediSearch command documentation: FT.CREATE

async info(index: KeyT) → dict[AnyStr, ResponseType][source]¶

Returns information and statistics on the index

Parameters:: index¶ – The name of the index.

RediSearch command documentation: FT.INFO

async explain(index: KeyT, query: StringT, dialect: int | None = None) → AnyStr[source]¶

Returns the execution plan for a complex query

Parameters:

index¶ – The name of the index to query.
query¶ – The query to explain.
dialect¶ – Query dialect to use.

RediSearch command documentation: FT.EXPLAIN

Compatibility:

dialect: New in RediSearch version 2.4.3

async alter(index: KeyT, field: Field, skipinitialscan: bool | None = None) → bool[source]¶

Adds a new field to the index

Parameters:

index¶ – The name of the index to alter.
field¶ – The new field to add
skipinitialscan¶ – If True, skip the initial scan and indexing.

RediSearch command documentation: FT.ALTER

async dropindex(index: KeyT, delete_docs: bool | None = None) → bool[source]¶

Deletes the index

Parameters:

index¶ – The name of the index to delete.
delete_docs¶ – If True, delete the documents associated with the index.

RediSearch command documentation: FT.DROPINDEX

Compatibility:

New in RediSearch version: 2.0.0

async aliasadd(alias: StringT, index: KeyT) → bool[source]¶

Adds an alias to the index

Parameters:

alias¶ – The alias to be added to the index.
index¶ – The index to which the alias will be added.

RediSearch command documentation: FT.ALIASADD

async aliasupdate(alias: StringT, index: KeyT) → bool[source]¶

Adds or updates an alias to the index

Parameters:

alias¶ – The alias to be added to an index.
index¶ – The index to which the alias will be added.

RediSearch command documentation: FT.ALIASUPDATE

async aliasdel(alias: StringT) → bool[source]¶

Deletes an alias from the index

Parameters:: alias¶ – The index alias to be removed.

RediSearch command documentation: FT.ALIASDEL

async tagvals(index: KeyT, field_name: StringT) → set[AnyStr][source]¶

Returns the distinct tags indexed in a Tag field

Parameters:

index¶ – The name of the index.
field_name¶ – Name of a Tag field defined in the schema.

RediSearch command documentation: FT.TAGVALS

async synupdate(index: KeyT, synonym_group: StringT, terms: Parameters[StringT], skipinitialscan: bool | None = None) → bool[source]¶

Creates or updates a synonym group with additional terms

Parameters:

index¶ – The name of the index.
synonym_group¶ – The ID of the synonym group to update.
terms¶ – A list of terms to add to the synonym group.
skipinitialscan¶ – If True, only documents indexed after the update will be affected.

RediSearch command documentation: FT.SYNUPDATE

Compatibility:

New in RediSearch version: 1.2.0

async syndump(index: KeyT) → dict[AnyStr, list[AnyStr]][source]¶

Dumps the contents of a synonym group

Parameters:: index¶ – The name of the index.

RediSearch command documentation: FT.SYNDUMP

Compatibility:

New in RediSearch version: 1.2.0

async spellcheck(index: KeyT, query: StringT, distance: int | None = None, include: StringT | None = None, exclude: StringT | None = None, dialect: int | None = None) → SpellCheckResult[source]¶

Performs spelling correction on a query, returning suggestions for misspelled terms

Parameters:

index¶ – The name of the index with the indexed terms.
query¶ – The search query.
distance¶ – Maximum Levenshtein distance for spelling suggestions
include¶ – Specifies an inclusion of a custom dictionary
exclude¶ – Specifies an exclusion of a custom dictionary
dialect¶ – The query dialect to use.

RediSearch command documentation: FT.SPELLCHECK

Compatibility:

New in RediSearch version: 1.4.0
dialect: New in RediSearch version 2.4.3

async dictadd(name: StringT, terms: Parameters[StringT]) → int[source]¶

Adds terms to a dictionary

Parameters:

name¶ – The name of the dictionary.
terms¶ – The terms to add to the dictionary.

RediSearch command documentation: FT.DICTADD

Compatibility:

New in RediSearch version: 1.4.0

async dictdel(name: StringT, terms: Parameters[StringT]) → int[source]¶

Deletes terms from a dictionary

Parameters:

name¶ – The name of the dictionary.
terms¶ – The terms to delete from the dictionary.

RediSearch command documentation: FT.DICTDEL

Compatibility:

New in RediSearch version: 1.4.0

async dictdump(name: StringT) → set[AnyStr][source]¶

Dumps all terms in the given dictionary

Parameters:: name¶ – The name of the dictionary to dump.

RediSearch command documentation: FT.DICTDUMP

Compatibility:

New in RediSearch version: 1.4.0

async list() → set[AnyStr][source]¶

Returns a list of all existing indexes

RediSearch command documentation: FT._LIST

Compatibility:

New in RediSearch version: 2.0.0

Cluster note

The command will be run on all primaries and return the union of the results

async config_set(option: StringT, value: ValueT) → bool[source]¶

Sets runtime configuration options

RediSearch command documentation: FT.CONFIG SET

Cluster note

The command will be run on all primaries and return the response from any shard if all responses are consistent

async config_get(option: StringT) → dict[AnyStr, ResponsePrimitive][source]¶

Retrieves runtime configuration options

RediSearch command documentation: FT.CONFIG GET

Cluster note

The command will be run on a random node

Searches the index with a textual query, returning either documents or just ids

Parameters:

index¶ – The name of the index to search.
query¶ – The text query to search.
nocontent¶ – If True, returns the document ids and not the content.
verbatim¶ – If True, does not try to use stemming for query expansion but searches the query terms verbatim.
nostopwords¶ – If True, disables stopword filtering.
withscores¶ – If True, also returns the relative internal score of each document.
withpayloads¶ – If True, retrieves optional document payloads.
withsortkeys¶ – If True, returns the value of the sorting key
numeric_filters¶ – A dictionary of numeric filters. Limits results to those having numeric values ranging between min and max,
geo_filters¶ – A dictionary of geo filters. Filters the results to a given radius from lon and lat. Radius is given as a number and units.
in_keys¶ – A list of keys to limit the result to. Non-existent keys are ignored, unless all the keys are non-existent.
in_fields¶ – Filters the results to those appearing only in specific attributes of the document, like title or URL.
returns¶ – A dictionary of attributes to return from the document. The values in the dictionary are used as an alias for the attribute name and if None, the attribute will be returned as is.
summarize_fields¶ – A list of fields to summarize. If not None, returns a summary of the fields.
summarize_frags¶ – The number of fragments to return in the summary.
summarize_length¶ – The length of each fragment in the summary.
summarize_separator¶ – The separator to use between fragments in the summary.
highlight_fields¶ – A list of fields to highlight.
highlight_tags¶ – A tuple of opening and closing tags to use for highlighting.
slop¶ – The number of words allowed between query terms.
timeout¶ – The timeout for the search query.
inorder¶ – If True, requires that the query terms appear in the same order as in the query.
language¶ – The language to use for stemming.
expander¶ – The query expander to use.
scorer¶ – The scorer to use.
explainscore¶ – If True, returns an explanation of the score.
payload¶ – The payload to return.
sortby¶ – The field to sort by.
sort_order¶ – The order to sort by.
offset¶ – The offset to start returning results from.
limit¶ – The maximum number of results to return.
parameters¶ – A dictionary of parameters to pass to the query.
dialect¶ – The query dialect to use.

RediSearch command documentation: FT.SEARCH

Compatibility:

dialect: New in RediSearch version 2.4.3

Perform aggregate transformations on search results from a Redis index.

Parameters:

index¶ – Name of the Redis index to search.
query¶ – Base filtering query to retrieve documents.
verbatim¶ – If True, search query terms verbatim.
load¶ – Load document attributes from the source document.
timeout¶ – Maximum time to wait for the query to complete.
transforms¶ – List of transformations to apply to the results.
sortby¶ – Sort the pipeline up to the point of SORTBY.
sortby_max¶ – Optimize sorting by sorting only for the n-largest elements.
offset¶ – Number of results to skip.
limit¶ – Maximum number of results to return.
with_cursor¶ – If True, return a cursor for large result sets.
cursor_read_size¶ – Number of results to read from the cursor at a time.
cursor_maxidle¶ – Maximum idle time for the cursor.
parameters¶ – Additional parameters to pass to the query.
dialect¶ – Query dialect to use.

Returns:

Aggregated search results from the Redis index.

RediSearch command documentation: FT.AGGREGATE

Compatibility:

New in RediSearch version: 1.1.0
dialect: New in RediSearch version 2.4.3

async cursor_read(index: KeyT, cursor_id: int, count: int | None = None) → SearchAggregationResult[source]¶

Reads from a cursor

RediSearch command documentation: FT.CURSOR READ

Compatibility:

New in RediSearch version: 1.1.0

async cursor_del(index: KeyT, cursor_id: int) → bool[source]¶

Deletes a cursor

RediSearch command documentation: FT.CURSOR DEL

Compatibility:

New in RediSearch version: 1.1.0

Field definition to be used in create() & alter()

For more details refer to the documentation for FT.CREATE

name: StringT¶: Name of the field. For hashes, this is a field name within the hash. For JSON, this is a JSON Path expression.

type: Literal[PureToken.TEXT, PureToken.TAG, PureToken.NUMERIC, PureToken.GEO, PureToken.VECTOR]¶: Type of field

alias: StringT | None = None¶: Defines the alias associated to name. For example, you can use this feature to alias a complex JSONPath expression with more memorable (and easier to type) name.

sortable: bool | None = None¶: Whether to optimize for sorting.

unf: bool | None = None¶: Whether to use the unnormalized form of the field for sorting.

nostem: bool | None = None¶: Whether to disable stemming for this field.

noindex: bool | None = None¶: Skip indexing this field

phonetic: StringT | None = None¶: Phonetic algorithm to use for this field.

weight: int | float | None = None¶: Weight of this field in the document’s ranking. The default is 1.0.

separator: StringT | None = None¶: Separator to use for splitting tags if the field is of type TAG.

casesensitive: bool | None = None¶: For fields of type TAG, keeps the original letter cases of the tags. If not specified, the characters are converted to lowercase.

withsuffixtrie: bool | None = None¶: For fields of type TAG & TEXT, keeps a suffix trie with all terms which match the suffix. It is used to optimize contains (foo) and suffix (*foo) queries. Otherwise, a brute-force search on the trie is performed. If suffix trie exists for some fields, these queries will be disabled for other fields

algorithm: Literal['FLAT', 'HSNW'] | None = None¶: The algorithm to use for indexing if the field is of type VECTOR. For more details refer to the Vector similarity section of the RediSearch documentation.

attributes: Dict[StringT, ValueT] | None = None¶: A dictionary of attributes to be used with the algorithm specified. For more details refer to the Creation attributes per algorithm section of the RediSearch documentation.

class Filter(expression: StringT)[source]¶

Filter definition to be used with transformations to specify FILTER steps in aggregate()

For more details refer to FILTER expressions in the RediSearch documentation.

expression: StringT¶: The filter expression

class Group(by: StringT | Parameters[StringT], reducers: Parameters[Reduce] | None = None)[source]¶

Group definition to be used with transformations to specify GROUPBY steps in aggregate()

For more details refer to Aggregations in the RediSearch documentation.

by: StringT | Parameters[StringT]¶: The field to group by

reducers: Parameters[Reduce] | None = None¶: The reducers to apply to each group

class Reduce(function: StringT, parameters: Parameters[ValueT] | None = None, alias: StringT | None = None)[source]¶

Reduce definition to be used with transformations to define REDUCE steps in aggregate()

For more details refer to GroupBy Reducers in the RediSearch documentation.

function: StringT¶: The name of the reducer function

parameters: Parameters[ValueT] | None = None¶: The arguments to the reducer function

alias: StringT | None = None¶: The alias to assign to the result of the reducer function

class Apply(function: StringT, alias: StringT)[source]¶

Apply definition to be used with transformations to specify APPLY steps in aggregate()

For more details refer to APPLY expressions in the RediSearch documentation.

function: StringT¶: The expression to apply

alias: StringT¶: The alias to assign to the result of the expression

Autocomplete¶

class Autocomplete(client: AbstractExecutor)[source]¶

Container for the commands in the suggestion command group of the RediSearch module.

Added in version 4.12.

async sugadd(key: KeyT, string: StringT, score: int | float, increment_score: bool | None = None, payload: StringT | None = None) → int[source]¶

Adds a suggestion string to an auto-complete suggestion dictionary

Parameters:

key¶ – The suggestion dictionary key.
string¶ – The suggestion string to index.
score¶ – The floating point number of the suggestion string’s weight.
increment_score¶ – Increments the existing entry of the suggestion by the given score, instead of replacing the score.
payload¶ – Saves an extra payload with the suggestion, that can be fetched when calling sugget() by using sugget.withpayloads

RediSearch command documentation: FT.SUGADD

Gets completion suggestions for a prefix

Parameters:

key¶ – The suggestion dictionary key.
prefix¶ – The prefix to complete on.
fuzzy¶ – If True, performs a fuzzy prefix search, including prefixes at Levenshtein distance of 1 from the prefix sent.
withscores¶ – If True, also returns the score of each suggestion.
withpayloads¶ – If True, returns optional payloads saved along with the suggestions.
max_suggestions¶ – Limits the results to a maximum of max_suggestions

RediSearch command documentation: FT.SUGGET

Hint

Supports client side caching

async sugdel(key: KeyT, string: StringT) → bool[source]¶

Deletes a string from a suggestion index

Parameters:

key¶ – The suggestion dictionary key.
string¶ – The suggestion string to index.

RediSearch command documentation: FT.SUGDEL

async suglen(key: KeyT) → int[source]¶

Gets the size of an auto-complete suggestion dictionary

Parameters:: key¶ – The key of the suggestion dictionary.

RediSearch command documentation: FT.SUGLEN

RedisGraph¶

class Graph(client: AbstractExecutor)[source]¶

Container for the commands in the graph command group of the RedisGraph module.

async query(graph: KeyT, query: StringT, timeout: int | timedelta | None = None) → GraphQueryResult[source]¶

Executes the given query against a specified graph

Parameters:

graph¶ – The name of the graph to query.
query¶ – The query to execute.
timeout¶ – The maximum amount of time (milliseconds) to wait for the query to complete

Returns:

The result set of the executed query.

RedisGraph command documentation: GRAPH.QUERY

async ro_query(graph: KeyT, query: StringT, timeout: int | timedelta | None = None) → GraphQueryResult[source]¶

Executes a given read only query against a specified graph

Parameters:

graph¶ – The name of the graph to query.
query¶ – The query to execute.
timeout¶ – The maximum amount of time (milliseconds) to wait for the query to complete.

Returns:

The result set for the read-only query or an error if a write query was given.

RedisGraph command documentation: GRAPH.RO_QUERY

Compatibility:

New in RedisGraph version: 2.2.8

async delete(graph: KeyT) → bool[source]¶

Completely removes the graph and all of its entities

Deletes the entire graph and all of its entities.

Parameters:: graph¶ – The name of the graph to be deleted.

RedisGraph command documentation: GRAPH.DELETE

async explain(graph: KeyT, query: StringT) → list[AnyStr][source]¶

Constructs a query execution plan for the given graph and query, but does not execute it.

Parameters:

graph¶ – The name of the graph to execute the query on.
query¶ – The query to construct the execution plan for.

Returns:

A list of strings representing the query execution plan.

RedisGraph command documentation: GRAPH.EXPLAIN

Compatibility:

New in RedisGraph version: 2.0.0

async profile(graph: KeyT, query: StringT, timeout: int | timedelta | None = None) → list[AnyStr][source]¶

Executes a query and returns an execution plan augmented with metrics for each operation’s execution

Parameters:

graph¶ – The name of the graph to execute the query on.
query¶ – The query to execute and return a profile for.
timeout¶ – Optional timeout for the query execution in milliseconds.

Returns:

A string representation of a query execution plan, with details on results produced by and time spent in each operation.

RedisGraph command documentation: GRAPH.PROFILE

Compatibility:

New in RedisGraph version: 2.0.0

async slowlog(graph: KeyT, reset: bool = False) → tuple[GraphSlowLogInfo, ...] | bool[source]¶

Returns a list containing up to 10 of the slowest queries issued against the given graph

Parameters:

graph¶ – The name of the graph
reset¶ – If True, the slowlog will be reset

Returns:

The slowlog for the given graph or True if the slowlog was reset

RedisGraph command documentation: GRAPH.SLOWLOG

Compatibility:

New in RedisGraph version: 2.0.12
reset: New in RedisGraph version 2.12.0

async config_get(name: StringT) → dict[AnyStr, ResponsePrimitive] | ResponsePrimitive[source]¶

Retrieves a RedisGraph configuration

Parameters:: name¶ – The name of the configuration parameter to retrieve.
Returns:: The value of the configuration parameter. If name is *, a mapping of all configuration parameters to their values

RedisGraph command documentation: GRAPH.CONFIG GET

Compatibility:

New in RedisGraph version: 2.2.11

Cluster note

The command will be run on a random node

async config_set(name: StringT, value: ValueT) → bool[source]¶

Updates a RedisGraph configuration

Parameters:

name¶ – The name of the configuration parameter to set.
value¶ – The value to set the configuration parameter to.

Returns:

True if the configuration parameter was set successfully, False otherwise.

RedisGraph command documentation: GRAPH.CONFIG SET

Compatibility:

New in RedisGraph version: 2.2.11

Cluster note

The command will be run on all primaries and return the response from any shard if all responses are consistent

async list() → set[AnyStr][source]¶

Lists all graph keys in the keyspace

Returns:: A list of graph keys in the keyspace.

RedisGraph command documentation: GRAPH.LIST

Compatibility:

New in RedisGraph version: 2.4.3

Cluster note

The command will be run on all primaries and return the union of the results

async constraint_drop(graph: KeyT, type: Literal[PureToken.MANDATORY, PureToken.UNIQUE], node: StringT | None = None, relationship: StringT | None = None, properties: Parameters[StringT] | None = None) → bool[source]¶

Deletes a constraint from specified graph

Parameters:

graph¶ – The name of the RedisGraph.
type¶ – The type of constraint to drop.
node¶ – The name of the node to drop the constraint from
relationship¶ – The name of the relationship to drop the constraint from
properties¶ – The properties to drop the constraint from

Returns:

True if the constraint was successfully dropped, False otherwise.

RedisGraph command documentation: GRAPH.CONSTRAINT DROP

Compatibility:

New in RedisGraph version: 2.12.0

async constraint_create(graph: KeyT, type: Literal[PureToken.MANDATORY, PureToken.UNIQUE], node: StringT | None = None, relationship: StringT | None = None, properties: Parameters[StringT] | None = None) → bool[source]¶

Creates a constraint on specified graph

Parameters:

graph¶ – The name of the graph.
type¶ – The type of constraint to create.
node¶ – The label of the node to apply the constraint to.
relationship¶ – The type of relationship to apply the constraint to.
properties¶ – The properties to apply the constraint to.

Returns:

True if the constraint was created successfully, False otherwise.

RedisGraph command documentation: GRAPH.CONSTRAINT CREATE

Compatibility:

New in RedisGraph version: 2.12.0

TimeSeries¶

class TimeSeries(client: AbstractExecutor)[source]¶

Container for the commands in the timeseries command group of the RedisTimeSeries module.

Added in version 4.12.

async create(key: KeyT, retention: int | timedelta | None = None, encoding: Literal[PureToken.COMPRESSED, PureToken.UNCOMPRESSED] | None = None, chunk_size: int | None = None, duplicate_policy: Literal[PureToken.BLOCK, PureToken.FIRST, PureToken.LAST, PureToken.MAX, PureToken.MIN, PureToken.SUM] | None = None, labels: Mapping[StringT, ValueT] | None = None) → bool[source]¶

Create a new time series with the given key.

Parameters:

key¶ – The key name for the time series.
retention¶ – Maximum age for samples compared to the highest reported timestamp, in milliseconds.
encoding¶ – Specifies the series samples encoding format as COMPRESSED or UNCOMPRESSED.
chunk_size¶ – Initial allocation size, in bytes, for the data part of each new chunk.
duplicate_policy¶ – Policy for handling insertion of multiple samples with identical timestamps.
labels¶ – A dictionary of labels to be associated with the time series.

Returns:

True if the time series was created successfully, False otherwise.

RedisTimeSeries command documentation: TS.CREATE

async delete(key: KeyT, fromtimestamp: int | datetime | StringT, totimestamp: int | datetime | StringT) → int[source]¶

Delete all samples between two timestamps for a given time series.

Parameters:

key¶ – Key name for the time series.
fromtimestamp¶ – Start timestamp for the range deletion.
totimestamp¶ – End timestamp for the range deletion.

Returns:

The number of samples that were deleted, or an error reply.

RedisTimeSeries command documentation: TS.DEL

Compatibility:

New in RedisTimeSeries version: 1.6.0

async alter(key: KeyT, labels: Mapping[StringT, StringT] | None = None, retention: int | None = None, chunk_size: int | None = None, duplicate_policy: Literal[PureToken.BLOCK, PureToken.FIRST, PureToken.LAST, PureToken.MAX, PureToken.MIN, PureToken.SUM] | None = None) → bool[source]¶

Update the retention, chunk size, duplicate policy, and labels of an existing time series.

Parameters:

key¶ – Key name for the time series.
labels¶ – Dictionary mapping labels to values that represent metadata labels of the key and serve as a secondary index.
retention¶ – Maximum retention period, compared to the maximum existing timestamp, in milliseconds.
chunk_size¶ – Initial allocation size, in bytes, for the data part of each new chunk.
duplicate_policy¶ – Policy for handling multiple samples with identical timestamps.

Returns:

True if executed correctly, False otherwise.

RedisTimeSeries command documentation: TS.ALTER

async add(key: KeyT, timestamp: int | datetime | StringT, value: int | float, retention: int | None = None, encoding: Literal[PureToken.COMPRESSED, PureToken.UNCOMPRESSED] | None = None, chunk_size: int | None = None, duplicate_policy: Literal[PureToken.BLOCK, PureToken.FIRST, PureToken.LAST, PureToken.MAX, PureToken.MIN, PureToken.SUM] | None = None, labels: Mapping[StringT, ValueT] | None = None) → int[source]¶

Add a sample to a time series.

Parameters:

key¶ – Name of the time series.
timestamp¶ – UNIX sample timestamp in milliseconds or * to set the timestamp according to the server clock.
value¶ – Numeric data value of the sample.
retention¶ – Maximum retention period, compared to the maximum existing timestamp, in milliseconds.
encoding¶ – Encoding format for the series sample.
chunk_size¶ – Memory size, in bytes, allocated for each data chunk.
duplicate_policy¶ – Policy for handling samples with identical timestamps.
labels¶ – Dictionary of labels associated with the sample.

Returns:

Number of samples added to the time series.

RedisTimeSeries command documentation: TS.ADD

async madd(ktvs: Parameters[Tuple[AnyStr, int, int | float]]) → Tuple[int, ...][source]¶

Append new samples to one or more time series.

Parameters:: ktvs¶ – A list of tuples, where each tuple contains the key name for the time series, an integer UNIX sample timestamp in milliseconds or * to set the timestamp according to the server clock, and a numeric data value of the sample.
Returns:: A tuple of integers representing the timestamp of each added sample

RedisTimeSeries command documentation: TS.MADD

Increments the value of the sample with the maximum existing timestamp, or creates a new sample with a value equal to the value of the sample with the maximum existing timestamp with a given increment.

Parameters:

key¶ – Name of the time series.
value¶ – Numeric data value of the sample.
labels¶ – Set of label-value pairs that represent metadata labels of the key and serve as a secondary index. Use it only if you are creating a new time series.
timestamp¶ – UNIX sample timestamp in milliseconds or * to set the timestamp according to the server clock. timestamp must be equal to or higher than the maximum existing timestamp. When not specified, the timestamp is set according to the server clock.
retention¶ – Maximum retention period, compared to the maximum existing timestamp, in milliseconds. Use it only if you are creating a new time series.
uncompressed¶ – Changes data storage from compressed (default) to uncompressed. Use it only if you are creating a new time series.
chunk_size¶ – Memory size, in bytes, allocated for each data chunk. Use it only if you are creating a new time series.

Returns:

The timestamp of the upserted sample, or an error.

RedisTimeSeries command documentation: TS.INCRBY

Decrease the value of the sample with the maximum existing timestamp, or create a new sample with a value equal to the value of the sample with the maximum existing timestamp with a given decrement.

Parameters:

key¶ – Key name for the time series.
value¶ – Numeric data value of the sample.
labels¶ – Mapping of labels to values that represent metadata labels of the key and serve as a secondary index. Use it only if you are creating a new time series.
timestamp¶ – UNIX sample timestamp in milliseconds or * to set the timestamp according to the server clock. When not specified, the timestamp is set according to the server clock.
retention¶ – Maximum retention period, compared to the maximum existing timestamp, in milliseconds. Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series.
uncompressed¶ – Changes data storage from compressed (default) to uncompressed. Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series.
chunk_size¶ – Memory size, in bytes, allocated for each data chunk. Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series.

Returns:

The timestamp of the upserted sample, or an error if the operation failed.

RedisTimeSeries command documentation: TS.DECRBY

async createrule(source: KeyT, destination: KeyT, aggregation: Literal[PureToken.AVG, PureToken.COUNT, PureToken.FIRST, PureToken.LAST, PureToken.MAX, PureToken.MIN, PureToken.RANGE, PureToken.STD_P, PureToken.STD_S, PureToken.SUM, PureToken.TWA, PureToken.VAR_P, PureToken.VAR_S], bucketduration: int | timedelta, aligntimestamp: int | None = None) → bool[source]¶

Create a compaction rule

Parameters:

source¶ – Key name for the source time series.
destination¶ – Key name for the destination (compacted) time series.
aggregation¶ – Aggregates results into time buckets by the given aggregation type
bucketduration¶ – Duration of each bucket, in milliseconds.
aligntimestamp¶ – Ensures that there is a bucket that starts exactly at aligntimestamp and aligns all other buckets accordingly. It is expressed in milliseconds. The default value is 0 aligned with the epoch.

Returns:

True if executed correctly, False otherwise.

RedisTimeSeries command documentation: TS.CREATERULE

Compatibility:

aligntimestamp: New in RedisTimeSeries version 1.8.0

async deleterule(source: KeyT, destination: KeyT) → bool[source]¶

Delete a compaction rule from a RedisTimeSeries sourceKey to a destinationKey.

Parameters:

source¶ – Key name for the source time series.
destination¶ – Key name for the destination (compacted) time series.

Returns:

True if the command executed correctly, False otherwise.

Warning

This command does not delete the compacted series.

RedisTimeSeries command documentation: TS.DELETERULE

Query a range in forward direction.

Parameters:

key¶ – The key name for the time series.
fromtimestamp¶ – Start timestamp for the range query (integer UNIX timestamp in milliseconds) or - to denote the timestamp of the earliest sample in the time series.
totimestamp¶ – End timestamp for the range query (integer UNIX timestamp in milliseconds) or + to denote the timestamp of the latest sample in the time series.
filter_by_ts¶ – List of specific timestamps to filter samples by.
min_value¶ – Minimum value to filter samples by.
max_value¶ – Maximum value to filter samples by.
count¶ – Limits the number of returned samples.
aggregator¶ – Aggregates samples into time buckets by the provided aggregation type.
bucketduration¶ – Duration of each bucket in milliseconds.
align¶ – Time bucket alignment control for aggregator.
buckettimestamp¶ – Timestamp of the first bucket.
empty¶ – If True, returns an empty list instead of raising an error when no data is available.
latest¶ – Used when a time series is a compaction. When True, the command also reports the compacted value of the latest, possibly partial, bucket, given that this bucket’s start time falls within [fromtimestamp, totimestamp].

Returns:

A tuple of samples, where each sample is a tuple of timestamp and value.

RedisTimeSeries command documentation: TS.RANGE

Compatibility:

latest: New in RedisTimeSeries version 1.8.0
empty: New in RedisTimeSeries version 1.8.0

Hint

Supports client side caching

Query a range in reverse direction from a RedisTimeSeries key.

Parameters:

key¶ – The key name for the time series.
fromtimestamp¶ – Start timestamp for the range query (integer UNIX timestamp in milliseconds) or - to denote the timestamp of the earliest sample in the time series.
totimestamp¶ – End timestamp for the range query (integer UNIX timestamp in milliseconds) or + to denote the timestamp of the latest sample in the time series.
filter_by_ts¶ – List of specific timestamps to filter samples by.
min_value¶ – Minimum value to filter samples by.
max_value¶ – Maximum value to filter samples by.
count¶ – Limit the number of returned samples.
aggregator¶ – Aggregates samples into time buckets by the provided aggregation type.
bucketduration¶ – Duration of each bucket in milliseconds.
align¶ – Time bucket alignment control for aggregator.
buckettimestamp¶ – Timestamp for the first bucket.
empty¶ – Return an empty list if no samples are found.
latest¶ – Report the compacted value of the latest, possibly partial, bucket.

Returns:

A tuple of timestamp-value pairs in reverse order.

RedisTimeSeries command documentation: TS.REVRANGE

Compatibility:

New in RedisTimeSeries version: 1.4.0
latest: New in RedisTimeSeries version 1.8.0
empty: New in RedisTimeSeries version 1.8.0

Hint

Supports client side caching

async mrange(fromtimestamp: int | datetime | StringT, totimestamp: int | datetime | StringT, filters: Parameters[StringT] | None = None, *, filter_by_ts: Parameters[int] | None = None, min_value: int | float | None = None, max_value: int | float | None = None, withlabels: bool | None = None, selected_labels: Parameters[StringT] | None = None, count: int | None = None, align: int | StringT | None = None, aggregator: Literal[PureToken.AVG, PureToken.COUNT, PureToken.FIRST, PureToken.LAST, PureToken.MAX, PureToken.MIN, PureToken.RANGE, PureToken.STD_P, PureToken.STD_S, PureToken.SUM, PureToken.TWA, PureToken.VAR_P, PureToken.VAR_S] | None = None, bucketduration: int | timedelta | None = None, buckettimestamp: StringT | None = None, groupby: StringT | None = None, reducer: Literal[PureToken.AVG, PureToken.COUNT, PureToken.FIRST, PureToken.LAST, PureToken.MAX, PureToken.MIN, PureToken.RANGE, PureToken.STD_P, PureToken.STD_S, PureToken.SUM, PureToken.VAR_P, PureToken.VAR_S] | None = None, empty: bool | None = None, latest: bool | None = None) → Dict[AnyStr, Tuple[Dict[AnyStr, AnyStr], Tuple[Tuple[int, float], ...] | Tuple[()]]][source]¶

Query a range across multiple time series by filters in forward direction.

Parameters:

fromtimestamp¶ – Start timestamp for the range query (integer UNIX timestamp in milliseconds) or - to denote the timestamp of the earliest sample amongst all time series that passes the filters.
totimestamp¶ – End timestamp for the range query (integer UNIX timestamp in milliseconds) or + to denote the timestamp of the latest sample amongst all time series that passes the filters
filters¶ – Filter expressions to apply to the time series.
filter_by_ts¶ – Timestamps to filter the time series by.
min_value¶ – Minimum value to filter the time series by.
max_value¶ – Maximum value to filter the time series by.
withlabels¶ – Whether to include labels in the response.
selected_labels¶ – Returns a subset of the label-value pairs that represent metadata labels of the time series. Use when a large number of labels exists per series, but only the values of some of the labels are required. If withlabels or selected_labels are not specified, by default, an empty mapping is reported as label-value pairs.
count¶ – Limit the number of samples returned.
align¶ – Time bucket alignment control for aggregator.
aggregator¶ – Aggregates samples into time buckets by the provided aggregation type.
bucketduration¶ – Duration of each bucket, in milliseconds.
buckettimestamp¶ – Timestamp of the first bucket.
groupby¶ – Label to group the samples by
reducer¶ – Aggregation type to aggregate the results in each group
empty¶ – Optional boolean to include empty time series in the response.
latest¶ – Report the compacted value of the latest, possibly partial, bucket.

Returns:

A dictionary containing the time series data.

RedisTimeSeries command documentation: TS.MRANGE

Compatibility:

latest: New in RedisTimeSeries version 1.8.0
empty: New in RedisTimeSeries version 1.8.0

Cluster note

The command will be run on all primaries and return the merged mapping

Query a range across multiple time series by filters in reverse direction.

Parameters:

fromtimestamp¶ – Start timestamp for the range query (integer UNIX timestamp in milliseconds) or - to denote the timestamp of the earliest sample amongst all time series that passes the filters.
totimestamp¶ – End timestamp for the range query (integer UNIX timestamp in milliseconds) or + to denote the timestamp of the latest sample amongst all time series that passes the filters
filters¶ – Filter expressions to apply to the time series.
filter_by_ts¶ – Timestamps to filter the time series by.
min_value¶ – Minimum value to filter the time series by.
max_value¶ – Maximum value to filter the time series by.
withlabels¶ – Whether to include labels in the response.
selected_labels¶ – Returns a subset of the label-value pairs that represent metadata labels of the time series. Use when a large number of labels exists per series, but only the values of some of the labels are required. If withlabels or selected_labels are not specified, by default, an empty mapping is reported as label-value pairs.
count¶ – Limit the number of samples returned.
align¶ – Time bucket alignment control for aggregator.
aggregator¶ – Aggregates samples into time buckets by the provided aggregation type.
bucketduration¶ – Duration of each bucket, in milliseconds.
buckettimestamp¶ – Timestamp of the first bucket.
groupby¶ – Label to group the samples by
reducer¶ – Aggregation type to aggregate the results in each group
empty¶ – Optional boolean to include empty time series in the response.
latest¶ – Report the compacted value of the latest, possibly partial, bucket.

Returns:

A dictionary containing the result of the query.

RedisTimeSeries command documentation: TS.MREVRANGE

Compatibility:

New in RedisTimeSeries version: 1.4.0
latest: New in RedisTimeSeries version 1.8.0
empty: New in RedisTimeSeries version 1.8.0

Cluster note

The command will be run on all primaries and return the merged mapping

async get(key: KeyT, latest: bool | None = None) → tuple[int, float] | tuple[()][source]¶

Get the sample with the highest timestamp from a given time series.

Parameters:

key¶ – The key name for the time series.
latest¶ – If the time series is a compaction, if True, reports the compacted value of the latest, possibly partial, bucket. When False, does not report the latest, possibly partial, bucket. When a time series is not a compaction, the parameter is ignored.

Returns:

A tuple of (timestamp, value) of the sample with the highest timestamp, or an empty tuple if the time series is empty.

RedisTimeSeries command documentation: TS.GET

Compatibility:

latest: New in RedisTimeSeries version 1.8.0

Hint

Supports client side caching

async mget(filters: Parameters[StringT], withlabels: bool | None = None, selected_labels: Parameters[StringT] | None = None, latest: bool | None = None) → Dict[AnyStr, Tuple[Dict[AnyStr, AnyStr], Tuple[int, float] | Tuple[()]]][source]¶

Get the sample with the highest timestamp from each time series matching a specific filter.

Parameters:

filters¶ – Filters time series based on their labels and label values. At least one label=value filter is required.
withlabels¶ – Includes in the reply all label-value pairs representing metadata labels of the time series. If withlabels or selected_labels are not specified, by default, an empty dictionary is reported as label-value pairs.
selected_labels¶ – Returns a subset of the label-value pairs that represent metadata labels of the time series. Use when a large number of labels exists per series, but only the values of some of the labels are required. If withlabels or selected_labels are not specified, by default, an empty mapping is reported as label-value pairs.
latest¶ – Used when a time series is a compaction. If True, the command also reports the compacted value of the latest possibly partial bucket, given that this bucket’s start time falls within [fromTimestamp, toTimestamp]. If False, the command does not report the latest possibly partial bucket. When a time series is not a compaction, the argument is ignored

Returns:

For each time series matching the specified filters, a dictionary is returned with the time series key name as the key and a tuple containing the label-value pairs and a single timestamp-value pair as the value.

RedisTimeSeries command documentation: TS.MGET

Compatibility:

latest: New in RedisTimeSeries version 1.8.0

Cluster note

The command will be run on all primaries and return the merged mapping

async info(key: KeyT, debug: bool | None = None) → dict[AnyStr, ResponseType][source]¶

Return information and statistics for a time series.

Parameters:

key¶ – Key name of the time series.
debug¶ – Optional flag to get a more detailed information about the chunks.

Returns:

Dictionary with information about the time series (name-value pairs).

RedisTimeSeries command documentation: TS.INFO

async queryindex(filters: Parameters[StringT]) → Set[AnyStr][source]¶

Get all time series keys matching a filter list.

Parameters:

filters¶ –

A list of filter expressions to match time series based on their labels and label values. Each filter expression has one of the following syntaxes:

label=value, where label equals value

label!=value, where label does not equal value

label=, where key does not have label label

label!=, where key has label label

label=(value1,value2,...), where key with label label equals one of the values in the list

label!=(value1,value2,...), where key with label label does not equal any of the values in the list

At least one label=value filter is required. Filters are conjunctive. For example, the filter type=temperature room=study means the a time series is a temperature time series of a study room. Don’t use whitespaces in the filter expression.

Returns:

A set of time series keys matching the filter list. The set is empty if no time series matches the filter. An error is returned on invalid filter expression.

RedisTimeSeries command documentation: TS.QUERYINDEX

Cluster note

The command will be run on all primaries and return the union of the results