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.

delete(key: KeyT, path: StringT | None = None) → CommandRequest[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: CommandName.JSON_DEL

get(key: KeyT, *paths: StringT) → CommandRequest[JsonType][source]¶

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: CommandName.JSON_GET

Hint

Supports client side caching

forget(key: KeyT, path: RedisValueT | None = None) → CommandRequest[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: CommandName.JSON_FORGET

toggle(key: KeyT, path: RedisValueT) → CommandRequest[JsonType][source]¶

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: CommandName.JSON_TOGGLE

Compatibility:

New in RedisJSON version: 2.0.0

clear(key: KeyT, path: RedisValueT | None = None) → CommandRequest[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: CommandName.JSON_CLEAR

Compatibility:

New in RedisJSON version: 2.0.0

set(key: KeyT, path: RedisValueT, value: JsonType, condition: Literal[PureToken.NX, PureToken.XX] | None = None) → CommandRequest[bool][source]¶

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: CommandName.JSON_SET

mget(keys: Parameters[KeyT], path: StringT) → CommandRequest[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: CommandName.JSON_MGET

Cluster note

The command will be routed to the nodes serving the keys in the command and return the concatenations of the results.

To disable this behavior set RedisCluster.non_atomic_cross_slot to False

mset(triplets: Parameters[tuple[KeyT, StringT, JsonType]]) → CommandRequest[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: CommandName.JSON_MSET

Compatibility:

New in RedisJSON version: 2.6.0

Cluster note

The command will be routed to the nodes serving the keys in the command and return True if all responses are True.

To disable this behavior set RedisCluster.non_atomic_cross_slot to False

merge(key: KeyT, path: StringT, value: JsonType) → CommandRequest[bool][source]¶

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: CommandName.JSON_MERGE

Compatibility:

New in RedisJSON version: 2.6.0

numincrby(key: KeyT, path: RedisValueT, value: int | float) → CommandRequest[JsonType][source]¶

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: CommandName.JSON_NUMINCRBY

nummultby(key: KeyT, path: RedisValueT, value: int | float) → CommandRequest[JsonType][source]¶

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: CommandName.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: CommandName.JSON_STRAPPEND

strlen(key: KeyT, path: KeyT | None = None) → CommandRequest[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: CommandName.JSON_STRLEN

Hint

Supports client side caching

arrappend(key: KeyT, values: Parameters[JsonType], path: KeyT | None = None) → CommandRequest[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: CommandName.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: CommandName.JSON_ARRINDEX

Hint

Supports client side caching

arrinsert(key: KeyT, path: RedisValueT, index: int, values: Parameters[JsonType]) → CommandRequest[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: CommandName.JSON_ARRINSERT

arrlen(key: KeyT, path: KeyT | None = None) → CommandRequest[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: CommandName.JSON_ARRLEN

Hint

Supports client side caching

arrpop(key: KeyT, path: KeyT | None = None, index: int | None = None) → CommandRequest[JsonType][source]¶

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: CommandName.JSON_ARRPOP

arrtrim(key: KeyT, path: RedisValueT, start: int, stop: int) → CommandRequest[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: CommandName.JSON_ARRTRIM

objkeys(key: KeyT, path: StringT | None = None) → CommandRequest[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: CommandName.JSON_OBJKEYS

objlen(key: KeyT, path: KeyT | None = None) → CommandRequest[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: CommandName.JSON_OBJLEN

type(key: KeyT, path: KeyT | None = None) → CommandRequest[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: CommandName.JSON_TYPE

Hint

Supports client side caching

resp(key: KeyT, path: KeyT | None = None) → CommandRequest[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: CommandName.JSON_RESP

Compatibility:

Deprecated in RedisJSON version: 2.6.0

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

Reports the size in bytes of a key

RedisJSON command documentation: CommandName.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.

reserve(key: KeyT, error_rate: int | float, capacity: int, expansion: int | None = None, nonscaling: bool | None = None) → CommandRequest[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: CommandName.BF_RESERVE

add(key: KeyT, item: ValueT) → CommandRequest[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: CommandName.BF_ADD

madd(key: KeyT, items: Parameters[ValueT]) → CommandRequest[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: CommandName.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: CommandName.BF_INSERT

exists(key: KeyT, item: ValueT) → CommandRequest[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: CommandName.BF_EXISTS

Hint

Supports client side caching

mexists(key: KeyT, items: Parameters[ValueT]) → CommandRequest[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: CommandName.BF_MEXISTS

Hint

Supports client side caching

scandump(key: KeyT, iterator: int) → CommandRequest[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: CommandName.BF_SCANDUMP

loadchunk(key: KeyT, iterator: int, data: bytes) → CommandRequest[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: CommandName.BF_LOADCHUNK

info(key: KeyT, single_value: Literal[PureToken.CAPACITY, PureToken.EXPANSION, PureToken.FILTERS, PureToken.ITEMS, PureToken.SIZE] | None = None) → CommandRequest[int] | CommandRequest[dict[AnyStr, 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: CommandName.BF_INFO

Hint

Supports client side caching

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

Returns the cardinality of a Bloom filter

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

RedisBloom command documentation: CommandName.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.

reserve(key: KeyT, capacity: int, bucketsize: int | None = None, maxiterations: int | None = None, expansion: int | None = None) → CommandRequest[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: CommandName.CF_RESERVE

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

Adds an item to a Cuckoo Filter

Parameters:

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

RedisBloom command documentation: CommandName.CF_ADD

addnx(key: KeyT, item: ValueT) → CommandRequest[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: CommandName.CF_ADDNX

insert(key: KeyT, items: Parameters[ValueT], capacity: int | None = None, nocreate: bool | None = None) → CommandRequest[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: CommandName.CF_INSERT

insertnx(key: KeyT, items: Parameters[ValueT], capacity: int | None = None, nocreate: bool | None = None) → CommandRequest[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: CommandName.CF_INSERTNX

exists(key: KeyT, item: ValueT) → CommandRequest[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: CommandName.CF_EXISTS

Hint

Supports client side caching

mexists(key: KeyT, items: Parameters[ValueT]) → CommandRequest[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: CommandName.CF_MEXISTS

Hint

Supports client side caching

delete(key: KeyT, item: ValueT) → CommandRequest[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: CommandName.CF_DEL

count(key: KeyT, item: ValueT) → CommandRequest[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: CommandName.CF_COUNT

Hint

Supports client side caching

scandump(key: KeyT, iterator: int) → CommandRequest[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: CommandName.CF_SCANDUMP

loadchunk(key: KeyT, iterator: int, data: StringT) → CommandRequest[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: CommandName.CF_LOADCHUNK

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

Returns information about a Cuckoo Filter

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

RedisBloom command documentation: CommandName.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.

initbydim(key: KeyT, width: int, depth: int) → CommandRequest[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: CommandName.CMS_INITBYDIM

Compatibility:

New in RedisBloom version: 2.0.0

initbyprob(key: KeyT, error: int | float, probability: int | float) → CommandRequest[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: CommandName.CMS_INITBYPROB

Compatibility:

New in RedisBloom version: 2.0.0

incrby(key: KeyT, items: Mapping[StringT, int]) → CommandRequest[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: CommandName.CMS_INCRBY

Compatibility:

New in RedisBloom version: 2.0.0

query(key: KeyT, items: Parameters[StringT]) → CommandRequest[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: CommandName.CMS_QUERY

Compatibility:

New in RedisBloom version: 2.0.0

Hint

Supports client side caching

merge(destination: KeyT, sources: Parameters[KeyT], weights: Parameters[int | float] | None = None) → CommandRequest[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: CommandName.CMS_MERGE

Compatibility:

New in RedisBloom version: 2.0.0

info(key: KeyT) → CommandRequest[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: CommandName.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.

create(key: KeyT, compression: int | None = None) → CommandRequest[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: CommandName.TDIGEST_CREATE

Compatibility:

New in RedisBloom version: 2.4.0

reset(key: KeyT) → CommandRequest[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: CommandName.TDIGEST_RESET

Compatibility:

New in RedisBloom version: 2.4.0

add(key: KeyT, values: Parameters[int | float]) → CommandRequest[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: CommandName.TDIGEST_ADD

Compatibility:

New in RedisBloom version: 2.4.0

merge(destination_key: KeyT, source_keys: Parameters[KeyT], compression: int | None = None, override: bool | None = None) → CommandRequest[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: CommandName.TDIGEST_MERGE

Compatibility:

New in RedisBloom version: 2.4.0

min(key: KeyT) → CommandRequest[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: CommandName.TDIGEST_MIN

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

max(key: KeyT) → CommandRequest[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: CommandName.TDIGEST_MAX

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

quantile(key: KeyT, quantiles: Parameters[int | float]) → CommandRequest[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: CommandName.TDIGEST_QUANTILE

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

cdf(key: KeyT, values: Parameters[int | float]) → CommandRequest[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: CommandName.TDIGEST_CDF

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

trimmed_mean(key: KeyT, low_cut_quantile: int | float, high_cut_quantile: int | float) → CommandRequest[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: CommandName.TDIGEST_TRIMMED_MEAN

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

rank(key: KeyT, values: Parameters[int | float]) → CommandRequest[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: CommandName.TDIGEST_RANK

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

revrank(key: KeyT, values: Parameters[int | float]) → CommandRequest[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: CommandName.TDIGEST_REVRANK

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

byrank(key: KeyT, ranks: Parameters[int | float]) → CommandRequest[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: CommandName.TDIGEST_BYRANK

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

byrevrank(key: KeyT, reverse_ranks: Parameters[int | float]) → CommandRequest[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: CommandName.TDIGEST_BYREVRANK

Compatibility:

New in RedisBloom version: 2.4.0

Hint

Supports client side caching

info(key: KeyT) → CommandRequest[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: CommandName.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.

reserve(key: KeyT, topk: int, width: int | None = None, depth: int | None = None, decay: int | float | None = None) → CommandRequest[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: CommandName.TOPK_RESERVE

Compatibility:

New in RedisBloom version: 2.0.0

add(key: KeyT, items: Parameters[AnyStr]) → CommandRequest[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: CommandName.TOPK_ADD

Compatibility:

New in RedisBloom version: 2.0.0

incrby(key: KeyT, items: Mapping[StringT, int]) → CommandRequest[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: CommandName.TOPK_INCRBY

Compatibility:

New in RedisBloom version: 2.0.0

query(key: KeyT, items: Parameters[StringT]) → CommandRequest[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: CommandName.TOPK_QUERY

Compatibility:

New in RedisBloom version: 2.0.0

Hint

Supports client side caching

count(key: KeyT, items: Parameters[StringT]) → CommandRequest[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: CommandName.TOPK_COUNT

Compatibility:

New in RedisBloom version: 2.0.0

list(key: KeyT, withcount: bool | None = None) → CommandRequest[dict[AnyStr, int]] | CommandRequest[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: CommandName.TOPK_LIST

Compatibility:

New in RedisBloom version: 2.0.0

Hint

Supports client side caching

info(key: KeyT) → CommandRequest[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: CommandName.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.
indexall¶ – If True maintains an inverted index of all document IDs to optimize wildcard queries in heavy update scenarios.

RediSearch command documentation: CommandName.FT_CREATE

Compatibility:

indexall: New in RediSearch version 8.0

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

Returns information and statistics on the index

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

RediSearch command documentation: CommandName.FT_INFO

explain(index: KeyT, query: StringT, dialect: int | None = None) → CommandRequest[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: CommandName.FT_EXPLAIN

Compatibility:

dialect: New in RediSearch version 2.4.3

alter(index: KeyT, field: Field, skipinitialscan: bool | None = None) → CommandRequest[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: CommandName.FT_ALTER

dropindex(index: KeyT, delete_docs: bool | None = None) → CommandRequest[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: CommandName.FT_DROPINDEX

Compatibility:

New in RediSearch version: 2.0.0

aliasadd(alias: StringT, index: KeyT) → CommandRequest[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: CommandName.FT_ALIASADD

aliasupdate(alias: StringT, index: KeyT) → CommandRequest[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: CommandName.FT_ALIASUPDATE

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

Deletes an alias from the index

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

RediSearch command documentation: CommandName.FT_ALIASDEL

Cluster note

The command will be routed to a random node in the cluster and return the response from the node.

tagvals(index: KeyT, field_name: StringT) → CommandRequest[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: CommandName.FT_TAGVALS

synupdate(index: KeyT, synonym_group: StringT, terms: Parameters[StringT], skipinitialscan: bool | None = None) → CommandRequest[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: CommandName.FT_SYNUPDATE

Compatibility:

New in RediSearch version: 1.2.0

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

Dumps the contents of a synonym group

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

RediSearch command documentation: CommandName.FT_SYNDUMP

Compatibility:

New in RediSearch version: 1.2.0

spellcheck(index: KeyT, query: StringT, distance: int | None = None, include: StringT | None = None, exclude: StringT | None = None, dialect: int | None = None) → CommandRequest[dict[AnyStr, OrderedDict[AnyStr, float]]][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: CommandName.FT_SPELLCHECK

Compatibility:

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

dictadd(name: StringT, terms: Parameters[StringT]) → CommandRequest[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: CommandName.FT_DICTADD

Compatibility:

New in RediSearch version: 1.4.0

dictdel(name: StringT, terms: Parameters[StringT]) → CommandRequest[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: CommandName.FT_DICTDEL

Compatibility:

New in RediSearch version: 1.4.0

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

Dumps all terms in the given dictionary

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

RediSearch command documentation: CommandName.FT_DICTDUMP

Compatibility:

New in RediSearch version: 1.4.0

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

Returns a list of all existing indexes

RediSearch command documentation: CommandName.FT__LIST

Compatibility:

New in RediSearch version: 2.0.0

Cluster note

The command will be routed to all primaries in the cluster and return the union of the results.

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

Sets runtime configuration options

RediSearch command documentation: CommandName.FT_CONFIG_SET

Compatibility:

Deprecated in RediSearch version: 8.0.0

Cluster note

The command will be routed to all primaries in the cluster and return the first response if all responses are consistent.

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

Retrieves runtime configuration options

RediSearch command documentation: CommandName.FT_CONFIG_GET

Compatibility:

Deprecated in RediSearch version: 8.0.0

Cluster note

The command will be routed to a random node in the cluster and return the response from the 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: CommandName.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: CommandName.FT_AGGREGATE

Compatibility:

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

Performs hybrid search combining text search and vector similarity with configurable fusion methods.

Parameters:

index¶ – Name of the Redis index to search.
search¶ – Base filtering query to retrieve documents.
vector_field¶ – The vector field in the index to search against
vector_data¶ – The vector data to use for similarity comparison
scorer¶ – Scoring algorithm to use
search_score_alias¶ – Alias for the search score
k¶ – K value for performing K-nearest neighbour search
ef_runtime¶ – controls the range search accuracy vs. speed tradeoff.
radius¶ – maximum distance for range matches
epsilon¶ – precision controls for range matches
vector_score_alias¶ – Alias for the vector search score
vector_filter¶ – Filter to use to select which documents are considered for vector similarity.
combine¶ – How to fuse the text search and vector similarity results.
transforms¶ – List of transformations to apply to the results.
sortby¶ – The fields to sort by and the direction to sort.
offset¶ – Number of results to skip.
limit¶ – Maximum number of results to return.
load¶ – Load document attributes from the source document.
timeout¶ – Maximum time to wait for the query to complete.
parameters¶ – Additional parameters to pass to the query.

RediSearch command documentation: CommandName.FT_HYBRID

Compatibility:

New in RediSearch version: 8.4.0

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

Reads from a cursor

RediSearch command documentation: CommandName.FT_CURSOR_READ

Compatibility:

New in RediSearch version: 1.1.0

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

Deletes a cursor

RediSearch command documentation: CommandName.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.GEOSHAPE, 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 search concepts 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 Vector index 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

class RRFCombine(window: int | None = None, score_alias: StringT | None = None, constant: int | None = None)[source]¶: RRF (Reciprocal Rank Fusion) method to be used in hybrid() with combine

class LinearCombine(window: int | None = None, score_alias: StringT | None = None, alpha: int | None = None, beta: int | None = None)[source]¶: Linear combination with ALPHA and BETA weights to be used in hybrid() with combine

Autocomplete¶

class Autocomplete(client: AbstractExecutor)[source]¶

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

Added in version 4.12.

sugadd(key: KeyT, string: StringT, score: int | float, increment_score: bool | None = None, payload: StringT | None = None) → CommandRequest[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: CommandName.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: CommandName.FT_SUGGET

Hint

Supports client side caching

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

Deletes a string from a suggestion index

Parameters:

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

RediSearch command documentation: CommandName.FT_SUGDEL

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

Gets the size of an auto-complete suggestion dictionary

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

RediSearch command documentation: CommandName.FT_SUGLEN

TimeSeries¶

class TimeSeries(client: AbstractExecutor)[source]¶

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

Added in version 4.12.

create(key: KeyT, retention: int | timedelta | None = None, encoding: Literal[PureToken.COMPRESSED, PureToken.UNCOMPRESSED] | None = None, chunk_size: int | None = None, duplicate_policy: None | Literal[PureToken.BLOCK, PureToken.FIRST, PureToken.LAST, PureToken.MAX, PureToken.MIN, PureToken.SUM] = None, labels: Mapping[MappingKeyT, ValueT] | None = None) → CommandRequest[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: CommandName.TS_CREATE

delete(key: KeyT, fromtimestamp: int | datetime | StringT, totimestamp: int | datetime | StringT) → CommandRequest[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: CommandName.TS_DEL

Compatibility:

New in RedisTimeSeries version: 1.6.0

alter(key: KeyT, labels: Mapping[MappingKeyT, StringT] | None = None, retention: int | None = None, chunk_size: int | None = None, duplicate_policy: None | Literal[PureToken.BLOCK, PureToken.FIRST, PureToken.LAST, PureToken.MAX, PureToken.MIN, PureToken.SUM] = None) → CommandRequest[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: CommandName.TS_ALTER

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: None | Literal[PureToken.BLOCK, PureToken.FIRST, PureToken.LAST, PureToken.MAX, PureToken.MIN, PureToken.SUM] = None, labels: Mapping[MappingKeyT, ValueT] | None = None) → CommandRequest[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: CommandName.TS_ADD

madd(ktvs: Parameters[tuple[AnyStr, int, int | float]]) → CommandRequest[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: CommandName.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: CommandName.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: CommandName.TS_DECRBY

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, PureToken.COUNTALL, PureToken.COUNTNAN], bucketduration: int | timedelta, aligntimestamp: int | None = None) → CommandRequest[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: CommandName.TS_CREATERULE

Compatibility:

aligntimestamp: New in RedisTimeSeries version 1.8.0

deleterule(source: KeyT, destination: KeyT) → CommandRequest[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: CommandName.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: CommandName.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: CommandName.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

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: None | 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, PureToken.COUNTALL, PureToken.COUNTNAN] = None, bucketduration: int | timedelta | None = None, buckettimestamp: StringT | None = None, groupby: StringT | None = None, reducer: None | 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, empty: bool | None = None, latest: bool | None = None) → CommandRequest[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: CommandName.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 routed to all primaries in the cluster 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: CommandName.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 routed to all primaries in the cluster and return the merged mapping.

get(key: KeyT, latest: bool | None = None) → CommandRequest[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: CommandName.TS_GET

Compatibility:

latest: New in RedisTimeSeries version 1.8.0

Hint

Supports client side caching

mget(filters: Parameters[StringT], withlabels: bool | None = None, selected_labels: Parameters[StringT] | None = None, latest: bool | None = None) → CommandRequest[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: CommandName.TS_MGET

Compatibility:

latest: New in RedisTimeSeries version 1.8.0

Cluster note

The command will be routed to all primaries in the cluster and return the merged mapping.

info(key: KeyT, debug: bool | None = None) → CommandRequest[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: CommandName.TS_INFO

queryindex(filters: Parameters[StringT]) → CommandRequest[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: CommandName.TS_QUERYINDEX

Cluster note

The command will be routed to all primaries in the cluster and return the union of the results.