RedisTimeSeries 命令

这些是用于与 RedisTimeSeries 模块 交互的命令。下面是一个简短的示例，以及命令本身的文档。

创建一个保留时间为 5 秒的时间序列对象

import redis
r = redis.Redis()
r.ts().create(2, retention_msecs=5000)

class redis.commands.timeseries.commands.TimeSeriesCommands

RedisTimeSeries Commands.

add(key, timestamp, value, retention_msecs=None, uncompressed=False, labels=None, chunk_size=None, duplicate_policy=None, ignore_max_time_diff=None, ignore_max_val_diff=None, on_duplicate=None)

Append a sample to a time series. When the specified key does not exist, a new time series is created.

For more information see https://redis.io/commands/ts.add/

参数:

• key (bytes | str | memoryview) -- The time-series key.

• timestamp (int | str) -- Timestamp of the sample. * can be used for automatic timestamp (using the system clock).

• value (int | float) -- Numeric data value of the sample.

• retention_msecs (int | None) -- Maximum age for samples, compared to the highest reported timestamp in milliseconds. If None or 0 is passed, the series is not trimmed at all.

• uncompressed (bool | None) -- Changes data storage from compressed (default) to uncompressed.

• labels (Dict[str, str] | None) -- A dictionary of label-value pairs that represent metadata labels of the key.

• chunk_size (int | None) -- Memory size, in bytes, allocated for each data chunk. Must be a multiple of 8 in the range [48..1048576]. In earlier versions of the module the minimum value was different.

• duplicate_policy (str | None) --

  Policy for handling multiple samples with identical timestamps. Can be one of:

  • 'block': An error will occur and the new value will be ignored.

  • 'first': Ignore the new value.

  • 'last': Override with the latest value.

  • 'min': Only override if the value is lower than the existing value.

  • 'max': Only override if the value is higher than the existing value.

  • 'sum': If a previous sample exists, add the new sample to it so that the updated value is equal to (previous + new). If no previous sample exists, set the updated value equal to the new value.

• ignore_max_time_diff (int | None) -- A non-negative integer value, in milliseconds, that sets an ignore threshold for added timestamps. If the difference between the last timestamp and the new timestamp is lower than this threshold, the new entry is ignored. Only applicable if duplicate_policy is set to last, and if ignore_max_val_diff is also set. Available since RedisTimeSeries version 1.12.0.

• ignore_max_val_diff (int | float | None) -- A non-negative floating point value, that sets an ignore threshold for added values. If the difference between the last value and the new value is lower than this threshold, the new entry is ignored. Only applicable if duplicate_policy is set to last, and if ignore_max_time_diff is also set. Available since RedisTimeSeries version 1.12.0.

• on_duplicate (str | None) -- Use a specific duplicate policy for the specified timestamp. Overrides the duplicate policy set by duplicate_policy.

alter(key, retention_msecs=None, labels=None, chunk_size=None, duplicate_policy=None, ignore_max_time_diff=None, ignore_max_val_diff=None)

Update an existing time series.

For more information see https://redis.io/commands/ts.alter/

参数:

• key (bytes | str | memoryview) -- The time-series key.

• retention_msecs (int | None) -- Maximum age for samples, compared to the highest reported timestamp in milliseconds. If None or 0 is passed, the series is not trimmed at all.

• labels (Dict[str, str] | None) -- A dictionary of label-value pairs that represent metadata labels of the key.

• chunk_size (int | None) -- Memory size, in bytes, allocated for each data chunk. Must be a multiple of 8 in the range [48..1048576]. In earlier versions of the module the minimum value was different. Changing this value does not affect existing chunks.

• duplicate_policy (str | None) --

  Policy for handling multiple samples with identical timestamps. Can be one of:

  • 'block': An error will occur and the new value will be ignored.

  • 'first': Ignore the new value.

  • 'last': Override with the latest value.

  • 'min': Only override if the value is lower than the existing value.

  • 'max': Only override if the value is higher than the existing value.

  • 'sum': If a previous sample exists, add the new sample to it so that the updated value is equal to (previous + new). If no previous sample exists, set the updated value equal to the new value.

• ignore_max_time_diff (int | None) -- A non-negative integer value, in milliseconds, that sets an ignore threshold for added timestamps. If the difference between the last timestamp and the new timestamp is lower than this threshold, the new entry is ignored. Only applicable if duplicate_policy is set to last, and if ignore_max_val_diff is also set. Available since RedisTimeSeries version 1.12.0.

• ignore_max_val_diff (int | float | None) -- A non-negative floating point value, that sets an ignore threshold for added values. If the difference between the last value and the new value is lower than this threshold, the new entry is ignored. Only applicable if duplicate_policy is set to last, and if ignore_max_time_diff is also set. Available since RedisTimeSeries version 1.12.0.

create(key, retention_msecs=None, uncompressed=False, labels=None, chunk_size=None, duplicate_policy=None, ignore_max_time_diff=None, ignore_max_val_diff=None)

Create a new time-series.

For more information see https://redis.io/commands/ts.create/

参数:

• key (bytes | str | memoryview) -- The time-series key.

• retention_msecs (int | None) -- Maximum age for samples, compared to the highest reported timestamp in milliseconds. If None or 0 is passed, the series is not trimmed at all.

• uncompressed (bool | None) -- Changes data storage from compressed (default) to uncompressed.

• labels (Dict[str, str] | None) -- A dictionary of label-value pairs that represent metadata labels of the key.

• chunk_size (int | None) -- Memory size, in bytes, allocated for each data chunk. Must be a multiple of 8 in the range [48..1048576]. In earlier versions of the module the minimum value was different.

• duplicate_policy (str | None) --

  Policy for handling multiple samples with identical timestamps. Can be one of:

  • 'block': An error will occur and the new value will be ignored.

  • 'first': Ignore the new value.

  • 'last': Override with the latest value.

  • 'min': Only override if the value is lower than the existing value.

  • 'max': Only override if the value is higher than the existing value.

  • 'sum': If a previous sample exists, add the new sample to it so that the updated value is equal to (previous + new). If no previous sample exists, set the updated value equal to the new value.

• ignore_max_time_diff (int | None) -- A non-negative integer value, in milliseconds, that sets an ignore threshold for added timestamps. If the difference between the last timestamp and the new timestamp is lower than this threshold, the new entry is ignored. Only applicable if duplicate_policy is set to last, and if ignore_max_val_diff is also set. Available since RedisTimeSeries version 1.12.0.

• ignore_max_val_diff (int | float | None) -- A non-negative floating point value, that sets an ignore threshold for added values. If the difference between the last value and the new value is lower than this threshold, the new entry is ignored. Only applicable if duplicate_policy is set to last, and if ignore_max_time_diff is also set. Available since RedisTimeSeries version 1.12.0.

createrule(source_key, dest_key, aggregation_type, bucket_size_msec, align_timestamp=None)

Create a compaction rule from values added to source_key into dest_key.

For more information see https://redis.io/commands/ts.createrule/

参数:

• source_key (bytes | str | memoryview) -- Key name for source time series.

• dest_key (bytes | str | memoryview) -- Key name for destination (compacted) time series.

• aggregation_type (str) -- Aggregation type: One of the following: [avg, sum, min, max, range, count, first, last, std.p, std.s, var.p, var.s, twa]

• bucket_size_msec (int) -- Duration of each bucket, in milliseconds.

• align_timestamp (int | None) -- Assure that there is a bucket that starts at exactly align_timestamp and align all other buckets accordingly.

decrby(key, value, timestamp=None, retention_msecs=None, uncompressed=False, labels=None, chunk_size=None, duplicate_policy=None, ignore_max_time_diff=None, ignore_max_val_diff=None)

Decrement the latest sample's of a series. When the specified key does not exist, a new time series is created.

This command can be used as a counter or gauge that automatically gets history as a time series.

For more information see https://redis.io/commands/ts.decrby/

参数:

• key (bytes | str | memoryview) -- The time-series key.

• value (int | float) -- Numeric value to subtract (subtrahend).

• timestamp (int | str | None) -- Timestamp of the sample. * can be used for automatic timestamp (using the system clock). timestamp must be equal to or higher than the maximum existing timestamp in the series. When equal, the value of the sample with the maximum existing timestamp is decreased. If it is higher, a new sample with a timestamp set to timestamp is created, and its value is set to the value of the sample with the maximum existing timestamp minus subtrahend.

• retention_msecs (int | None) -- Maximum age for samples, compared to the highest reported timestamp in milliseconds. If None or 0 is passed, the series is not trimmed at all.

• uncompressed (bool | None) -- Changes data storage from compressed (default) to uncompressed.

• labels (Dict[str, str] | None) -- A dictionary of label-value pairs that represent metadata labels of the key.

• chunk_size (int | None) -- Memory size, in bytes, allocated for each data chunk. Must be a multiple of 8 in the range [48..1048576]. In earlier versions of the module the minimum value was different.

• duplicate_policy (str | None) --

  Policy for handling multiple samples with identical timestamps. Can be one of:

  • 'block': An error will occur and the new value will be ignored.

  • 'first': Ignore the new value.

  • 'last': Override with the latest value.

  • 'min': Only override if the value is lower than the existing value.

  • 'max': Only override if the value is higher than the existing value.

  • 'sum': If a previous sample exists, add the new sample to it so that the updated value is equal to (previous + new). If no previous sample exists, set the updated value equal to the new value.

• ignore_max_time_diff (int | None) -- A non-negative integer value, in milliseconds, that sets an ignore threshold for added timestamps. If the difference between the last timestamp and the new timestamp is lower than this threshold, the new entry is ignored. Only applicable if duplicate_policy is set to last, and if ignore_max_val_diff is also set. Available since RedisTimeSeries version 1.12.0.

• ignore_max_val_diff (int | float | None) -- A non-negative floating point value, that sets an ignore threshold for added values. If the difference between the last value and the new value is lower than this threshold, the new entry is ignored. Only applicable if duplicate_policy is set to last, and if ignore_max_time_diff is also set. Available since RedisTimeSeries version 1.12.0.

返回:

The timestamp of the sample that was modified or added.

delete(key, from_time, to_time)

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

The given timestamp interval is closed (inclusive), meaning that samples whose timestamp equals from_time or to_time are also deleted.

For more information see https://redis.io/commands/ts.del/

参数:

• key (bytes | str | memoryview) -- The time-series key.

• from_time (int) -- Start timestamp for the range deletion.

• to_time (int) -- End timestamp for the range deletion.

返回:

The number of samples deleted.

deleterule(source_key, dest_key)

Delete a compaction rule from source_key to dest_key.

For more information see https://redis.io/commands/ts.deleterule/

参数:

• source_key (bytes | str | memoryview)

• dest_key (bytes | str | memoryview)

get(key, latest=False)

Get the last sample of key.

For more information see https://redis.io/commands/ts.get/

参数:

• latest (bool | None) -- Used when a time series is a compaction, reports the compacted value of the latest (possibly partial) bucket.

• key (bytes | str | memoryview)

incrby(key, value, timestamp=None, retention_msecs=None, uncompressed=False, labels=None, chunk_size=None, duplicate_policy=None, ignore_max_time_diff=None, ignore_max_val_diff=None)

Increment the latest sample's of a series. When the specified key does not exist, a new time series is created.

This command can be used as a counter or gauge that automatically gets history as a time series.

For more information see https://redis.io/commands/ts.incrby/

参数:

• key (bytes | str | memoryview) -- The time-series key.

• value (int | float) -- Numeric value to be added (addend).

• timestamp (int | str | None) -- Timestamp of the sample. * can be used for automatic timestamp (using the system clock). timestamp must be equal to or higher than the maximum existing timestamp in the series. When equal, the value of the sample with the maximum existing timestamp is increased. If it is higher, a new sample with a timestamp set to timestamp is created, and its value is set to the value of the sample with the maximum existing timestamp plus the addend.

• retention_msecs (int | None) -- Maximum age for samples, compared to the highest reported timestamp in milliseconds. If None or 0 is passed, the series is not trimmed at all.

• uncompressed (bool | None) -- Changes data storage from compressed (default) to uncompressed.

• labels (Dict[str, str] | None) -- A dictionary of label-value pairs that represent metadata labels of the key.

• chunk_size (int | None) -- Memory size, in bytes, allocated for each data chunk. Must be a multiple of 8 in the range [48..1048576]. In earlier versions of the module the minimum value was different.

• duplicate_policy (str | None) --

  Policy for handling multiple samples with identical timestamps. Can be one of:

  • 'block': An error will occur and the new value will be ignored.

  • 'first': Ignore the new value.

  • 'last': Override with the latest value.

  • 'min': Only override if the value is lower than the existing value.

  • 'max': Only override if the value is higher than the existing value.

  • 'sum': If a previous sample exists, add the new sample to it so that the updated value is equal to (previous + new). If no previous sample exists, set the updated value equal to the new value.

• ignore_max_time_diff (int | None) -- A non-negative integer value, in milliseconds, that sets an ignore threshold for added timestamps. If the difference between the last timestamp and the new timestamp is lower than this threshold, the new entry is ignored. Only applicable if duplicate_policy is set to last, and if ignore_max_val_diff is also set. Available since RedisTimeSeries version 1.12.0.

• ignore_max_val_diff (int | float | None) -- A non-negative floating point value, that sets an ignore threshold for added values. If the difference between the last value and the new value is lower than this threshold, the new entry is ignored. Only applicable if duplicate_policy is set to last, and if ignore_max_time_diff is also set. Available since RedisTimeSeries version 1.12.0.

返回:

The timestamp of the sample that was modified or added.

info(key)

Get information of key.

For more information see https://redis.io/commands/ts.info/

参数:

key (bytes | str | memoryview)

madd(ktv_tuples)

Append new samples to one or more time series.

Each time series must already exist.

The method expects a list of tuples. Each tuple should contain three elements: (key, timestamp, value). The value will be appended to the time series identified by 'key', at the given 'timestamp'.

For more information see https://redis.io/commands/ts.madd/

参数:

ktv_tuples (List[Tuple[bytes | str | memoryview, int | str, int | float]]) --

A list of tuples, where each tuple contains:

• key: The key of the time series.

• timestamp: The timestamp at which the value should be appended.

• value: The value to append to the time series.

返回:

A list that contains, for each sample, either the timestamp that was used, or an error, if the sample could not be added.

mget(filters, with_labels=False, select_labels=None, latest=False)

Get the last samples matching the specific filter.

For more information see https://redis.io/commands/ts.mget/

参数:

• filters (List[str]) -- Filter to match the time-series labels.

• with_labels (bool | None) -- Include in the reply all label-value pairs representing metadata labels of the time series.

• select_labels (List[str] | None) -- Include in the reply only a subset of the key-value pair labels o the time series.

• latest (bool | None) -- Used when a time series is a compaction, reports the compacted value of the latest possibly partial bucket.

mrange(from_time, to_time, filters, count=None, aggregation_type=None, bucket_size_msec=0, with_labels=False, filter_by_ts=None, filter_by_min_value=None, filter_by_max_value=None, groupby=None, reduce=None, select_labels=None, align=None, latest=False, bucket_timestamp=None, empty=False)

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

For more information see https://redis.io/commands/ts.mrange/

参数:

• from_time (int | str) -- Start timestamp for the range query. - can be used to express the minimum possible timestamp (0).

• to_time (int | str) -- End timestamp for range query, + can be used to express the maximum possible timestamp.

• filters (List[str]) -- Filter to match the time-series labels.

• count (int | None) -- Limits the number of returned samples.

• aggregation_type (str | None) -- Optional aggregation type. Can be one of [avg, sum, min, max, range, count, first, last, std.p, std.s, var.p, var.s, twa]

• bucket_size_msec (int | None) -- Time bucket for aggregation in milliseconds.

• with_labels (bool | None) -- Include in the reply all label-value pairs representing metadata labels of the time series.

• filter_by_ts (List[int] | None) -- List of timestamps to filter the result by specific timestamps.

• filter_by_min_value (int | None) -- Filter result by minimum value (must mention also filter_by_max_value).

• filter_by_max_value (int | None) -- Filter result by maximum value (must mention also filter_by_min_value).

• groupby (str | None) -- Grouping by fields the results (must mention also reduce).

• reduce (str | None) -- Applying reducer functions on each group. Can be one of [avg sum, min, max, range, count, std.p, std.s, var.p, var.s].

• select_labels (List[str] | None) -- Include in the reply only a subset of the key-value pair labels of a series.

• align (int | str | None) -- Timestamp for alignment control for aggregation.

• latest (bool | None) -- Used when a time series is a compaction, reports the compacted value of the latest possibly partial bucket.

• bucket_timestamp (str | None) -- Controls how bucket timestamps are reported. Can be one of [-, low, +, high, ~, mid].

• empty (bool | None) -- Reports aggregations for empty buckets.

mrevrange(from_time, to_time, filters, count=None, aggregation_type=None, bucket_size_msec=0, with_labels=False, filter_by_ts=None, filter_by_min_value=None, filter_by_max_value=None, groupby=None, reduce=None, select_labels=None, align=None, latest=False, bucket_timestamp=None, empty=False)

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

For more information see https://redis.io/commands/ts.mrevrange/

参数:

• from_time (int | str) -- Start timestamp for the range query. '-' can be used to express the minimum possible timestamp (0).

• to_time (int | str) -- End timestamp for range query, '+' can be used to express the maximum possible timestamp.

• filters (List[str]) -- Filter to match the time-series labels.

• count (int | None) -- Limits the number of returned samples.

• aggregation_type (str | None) -- Optional aggregation type. Can be one of [avg, sum, min, max, range, count, first, last, std.p, std.s, var.p, var.s, twa].

• bucket_size_msec (int | None) -- Time bucket for aggregation in milliseconds.

• with_labels (bool | None) -- Include in the reply all label-value pairs representing metadata labels of the time series.

• filter_by_ts (List[int] | None) -- List of timestamps to filter the result by specific timestamps.

• filter_by_min_value (int | None) -- Filter result by minimum value (must mention also filter_by_max_value).

• filter_by_max_value (int | None) -- Filter result by maximum value (must mention also filter_by_min_value).

• groupby (str | None) -- Grouping by fields the results (must mention also reduce).

• reduce (str | None) -- Applying reducer functions on each group. Can be one of [avg sum, min, max, range, count, std.p, std.s, var.p, var.s].

• select_labels (List[str] | None) -- Include in the reply only a subset of the key-value pair labels of a series.

• align (int | str | None) -- Timestamp for alignment control for aggregation.

• latest (bool | None) -- Used when a time series is a compaction, reports the compacted value of the latest possibly partial bucket.

• bucket_timestamp (str | None) -- Controls how bucket timestamps are reported. Can be one of [-, low, +, high, ~, mid].

• empty (bool | None) -- Reports aggregations for empty buckets.

queryindex(filters)

Get all time series keys matching the filter list.

For more information see https://redis.io/commands/ts.queryindex/

参数:

filters (List[str])

range(key, from_time, to_time, count=None, aggregation_type=None, bucket_size_msec=0, filter_by_ts=None, filter_by_min_value=None, filter_by_max_value=None, align=None, latest=False, bucket_timestamp=None, empty=False)

Query a range in forward direction for a specific time-series.

For more information see https://redis.io/commands/ts.range/

参数:

• key (bytes | str | memoryview) -- Key name for timeseries.

• from_time (int | str) -- Start timestamp for the range query. - can be used to express the minimum possible timestamp (0).

• to_time (int | str) -- End timestamp for range query, + can be used to express the maximum possible timestamp.

• count (int | None) -- Limits the number of returned samples.

• aggregation_type (str | None) -- Optional aggregation type. Can be one of [avg, sum, min, max, range, count, first, last, std.p, std.s, var.p, var.s, twa]

• bucket_size_msec (int | None) -- Time bucket for aggregation in milliseconds.

• filter_by_ts (List[int] | None) -- List of timestamps to filter the result by specific timestamps.

• filter_by_min_value (int | None) -- Filter result by minimum value (must mention also filter by_max_value).

• filter_by_max_value (int | None) -- Filter result by maximum value (must mention also filter by_min_value).

• align (int | str | None) -- Timestamp for alignment control for aggregation.

• latest (bool | None) -- Used when a time series is a compaction, reports the compacted value of the latest possibly partial bucket.

• bucket_timestamp (str | None) -- Controls how bucket timestamps are reported. Can be one of [-, low, +, high, ~, mid].

• empty (bool | None) -- Reports aggregations for empty buckets.

revrange(key, from_time, to_time, count=None, aggregation_type=None, bucket_size_msec=0, filter_by_ts=None, filter_by_min_value=None, filter_by_max_value=None, align=None, latest=False, bucket_timestamp=None, empty=False)

Query a range in reverse direction for a specific time-series.

Note: This command is only available since RedisTimeSeries >= v1.4

For more information see https://redis.io/commands/ts.revrange/

参数:

• key (bytes | str | memoryview) -- Key name for timeseries.

• from_time (int | str) -- Start timestamp for the range query. - can be used to express the minimum possible timestamp (0).

• to_time (int | str) -- End timestamp for range query, + can be used to express the maximum possible timestamp.

• count (int | None) -- Limits the number of returned samples.

• aggregation_type (str | None) -- Optional aggregation type. Can be one of [avg, sum, min, max, range, count, first, last, std.p, std.s, var.p, var.s, twa]

• bucket_size_msec (int | None) -- Time bucket for aggregation in milliseconds.

• filter_by_ts (List[int] | None) -- List of timestamps to filter the result by specific timestamps.

• filter_by_min_value (int | None) -- Filter result by minimum value (must mention also filter_by_max_value).

• filter_by_max_value (int | None) -- Filter result by maximum value (must mention also filter_by_min_value).

• align (int | str | None) -- Timestamp for alignment control for aggregation.

• latest (bool | None) -- Used when a time series is a compaction, reports the compacted value of the latest possibly partial bucket.

• bucket_timestamp (str | None) -- Controls how bucket timestamps are reported. Can be one of [-, low, +, high, ~, mid].

• empty (bool | None) -- Reports aggregations for empty buckets.