TS.MRANGE

通过正向过滤器查询跨多个时间序列的范围

语法

TS.MRANGE fromTimestamp toTimestamp [LATEST] [FILTER BY TS Timestamp [Timestamp ...]] [FILTER BY VALUE min max] [WITHLABELS | SELECTED LABELS label1 [label1 ...]] [COUNT count] [[ALIGN value] AGGREGATION aggregators bucketDuration [BUCKETTIMESTAMP] [EMPTY]] FILTER [GROUPBY label REDUCE reducer] [EXCLUDEEMPTY]

引入版本：1.0.0

复杂度摘要：O(n/m+k)

[!NOTE] 此命令的行为在集群 Redis 环境中有所不同。请参阅 多键操作 页面了解更多信息。

通过正向过滤器查询跨多个时间序列的范围。从 Redis 8.6 开始，NaN 值包含在原始测量报告（不进行聚合的查询）中。

[!NOTE] 仅当当前用户对与过滤器匹配的所有键具有读取权限时，此命令才会回复。否则，它将回复“（错误）：当前用户没有对与指定过滤器匹配的一个或多个键的读取权限”。

示例

必需参数

fromTimestamp

是范围查询的开始时间戳（以毫秒为单位的整数Unix时间戳）或-，表示通过FILTER filterExpr...的所有时间序列中最早样本的时间戳。

toTimestamp

是范围查询的结束时间戳（以毫秒为单位的整数Unix时间戳）或+，表示通过FILTER filterExpr...的所有时间序列中最新样本的时间戳。

FILTER filterExpr...

根据标签和标签值过滤时间序列。

可选参数

LATEST（自 RedisTimeSeries 1.8 起）

当时间序列是压缩时使用。使用 LATEST，TS.MRANGE 还会报告最新（可能是部分）存储桶的压缩值，前提是该存储桶的开始时间落在 [fromTimestamp, toTimestamp] 范围内。如果没有 LATEST，TS.MRANGE 不会报告最新（可能是部分）存储桶。当时间序列不是压缩时，LATEST 被忽略。

compaction的最新bucket中的数据可能是部分的。存储桶是 关闭，并且仅在新样本到达时才进行压缩，该新样本将 打开 变为新的 最新的 存储桶。然而，在某些情况下，还需要最新（可能是部分）存储桶的压缩值。在这种情况下，请使用 LATEST。

FILTER_BY_TS ts...（自 RedisTimeSeries 1.6 起）

通过特定时间戳列表过滤样本。如果指定了确切的时间戳且落在 [fromTimestamp, toTimestamp] 范围内，则样本将通过过滤器。

与 AGGREGATION 一起使用时：样本在聚合之前经过过滤。

FILTER_BY_VALUE min max（自 RedisTimeSeries 1.6 起）

按最小值和最大值过滤样本。 min 和 max 不能是 NaN 值。

与 AGGREGATION 一起使用时：样本在聚合之前经过过滤。

WITHLABELS

在回复中包括表示时间序列的元数据标签的所有标签-值对。如果未指定 WITHLABELS 或 SELECTED_LABELS，默认情况下，将报告空列表作为标签值对。

SELECTED_LABELS label...（自 RedisTimeSeries 1.6 起）

返回表示时间序列的元数据标签的标签值对的子集。当每个系列存在大量标签，但仅需要某些标签的值时使用。如果未指定 WITHLABELS 或 SELECTED_LABELS，默认情况下，将报告空列表作为标签值对。

COUNT count

当不使用 AGGREGATION 时：限制每个时间序列报告的样本数量。

与AGGREGATION一起使用时：限制上报的桶的数量。

ALIGN align（自 RedisTimeSeries 1.6 起）

是AGGREGATION的时间桶对齐控制。它通过更改定义桶的参考时间戳来控制时间桶时间戳。

价值观包括：

  • start 或 -：参考时间戳将是查询开始间隔时间（fromTimestamp），不能是 -
  • end 或 +：参考时间戳将是查询结束间隔时间（toTimestamp），不能是 +
  • 特定时间戳：将参考时间戳与特定时间对齐

Note: When not provided, alignment is set to 0.

AGGREGATION aggregators bucketDuration

对于每个时间序列，将样本聚合到时间桶中，其中：

  • aggregators 是下表中的一个或多个以逗号分隔的聚合器：

    聚合器 说明
    avg 所有非 NaN 值的算术平均值
    sum 所有非 NaN 值的总和
    min 最小非 NaN 值
    max 最大非 NaN 值
    range 最大和最小非 NaN 值之间的差异
    count 非 NaN 值的数量
    countNaN NaN 值的数量（自 Redis 8.6 起）
    countAll 值的数量，包括 NaN 和非 NaN（自 Redis 8.6 起）
    first 桶中时间戳最小的非NaN值
    last 桶中时间戳最大的非NaN值
    std.p 非 NaN 值的总体标准差
    std.s 非 NaN 值的样本标准差
    var.p 非 NaN 值的总体方差
    var.s 非 NaN 值的样本方差
    twa 存储桶时间范围内的时间加权平均值（忽略 NaN 值）（自 RedisTimeSeries 1.8 起）

  • bucketDuration 是每个桶的持续时间，单位为毫秒。

注意：aggregators 可以是单个聚合器，也可以是用逗号分隔的多个聚合器，如下所示。聚合器之间不允许有空格。

聚合最小值、平均值、最大值

如果没有 ALIGN，存储桶开始时间是 bucketDuration 的倍数。

对于 ALIGN align，存储桶开始时间是 bucketDuration 的倍数，余数是 align % bucketDuration。

第一个桶开始时间小于或等于fromTimestamp。

[BUCKETTIMESTAMP bt]（自 RedisTimeSeries 1.8 起）

控制如何报告存储桶时间戳。

bt 为每个存储桶报告时间戳
- or start Bucket的开始时间（默认）
+ or end 桶的结束时间
~ or mid 桶的中间时间（如果不是整数则向下舍入）
[EMPTY]（自 RedisTimeSeries 1.8 起）

是一个标志，指定后也报告空桶的聚合。

聚合器 为每个空桶报告的值
sum, count 0
last 存储桶开始之前的最后一个样本的值。 NaN 当没有这样的样本时。
twa 存储桶时间范围内的平均值，基于存储桶开始前的最后一个样本和存储桶结束后的第一个样本的线性插值。 NaN 当没有这样的样本时。
min, max, range, avg, first, std.p, std.s NaN

无论 fromTimestamp 和 toTimestamp 的值如何，对于时间序列中最早样本之前结束或最新样本之后开始的存储桶，不会报告任何数据。

GROUPBY label REDUCE reducer（自 RedisTimeSeries 1.6 起）

将时间序列分成组，每个组包含与所提供的标签名称共享相同值的时间序列，然后聚合每个组中的结果。

当与 AGGREGATION 结合使用时，GROUPBY/REDUCE 将在聚合阶段后应用。当指定多个聚合器时，不允许使用 GROUPBY/REDUCE。

  • label 是标签名称。为所有共享此标签值的时间序列创建一个组。

  • reducer 是聚合类型，用于聚合各组中的结果。

    reducer 说明
    avg 所有非 NaN 值的算术平均值； NaN 如果没有这样的值（自 RedisTimeSeries 1.8 起）
    sum 所有非 NaN 值的总和； NaN 如果没有这样的值
    min 最小非 NaN 值； NaN 如果没有这样的值
    max 最大非 NaN 值； NaN 如果没有这样的值
    range 最大和最小非 NaN 值之间的差异； NaN 如果没有这样的值（自 RedisTimeSeries 1.8 起）
    count 非 NaN 值的数量（自 RedisTimeSeries 1.8 起）
    countNaN NaN 值的数量（自 Redis 8.6 起）
    countAll 值的数量，包括 NaN 和非 NaN（自 Redis 8.6 起）
    std.p 非 NaN 值的总体标准差； NaN 如果没有这样的值（自 RedisTimeSeries 1.8 起）
    std.s 非 NaN 值的样本标准差； NaN 如果没有这样的值（自 RedisTimeSeries 1.8 起）
    var.p 非 NaN 值的总体方差； NaN 如果没有这样的值（自 RedisTimeSeries 1.8 起）
    var.s 非 NaN 值的样本方差； NaN 如果没有这样的值（自 RedisTimeSeries 1.8 起）

Notes: - The produced time series is named <label>=<value> - The produced time series contains two labels with these label array structures: - __reducer__, the reducer used (e.g., "count") - __source__, the list of time series keys used to compute the grouped series (e.g., "key1,key2,key3")

EXCLUDEEMPTY（自Redis 8.10起）

从回复中排除任何在请求范围内没有样本的时间序列。默认情况下，每个通过 FILTER filterExpr... 的时间序列都会被报告，即使是那些在范围内没有样本的时间序列（使用空样本列表报告）。

范围内唯一样本为 NaN 的时间序列不被视为空，仍会报告。

EXCLUDEEMPTY不能与GROUPBY label REDUCE reducer一起使用；将它们结合起来会产生错误。

Note: An MRANGE command cannot be part of a transaction when running on a Redis cluster.

示例

Retrieve maximum stock price per timestamp

创建两只股票并添加它们在三个不同时间戳的价格。

127.0.0.1:6379> TS.CREATE 库存:A LABELS 类型库存名称 A OK 127.0.0.1:6379> TS.CREATE 库存:B LABELS 类型库存名称 B OK 127.0.0.1:6379> TS.MADD 库存:A 1000 100 库存:A 1010 110库存：A 1020 120 1)（整数）1000 2）（整数）1010 3）（整数）1020 127.0.0.1:6379> TS.MADD 库存：B 1000 120 库存：B 1010 110 库存：B 1020 100 1)（整数） 1000 2) (整数) 1010 3) (整数) 1020

您现在可以检索每个时间戳的最高股票价格。

127.0.0.1:6379> TS.MRANGE - + 带标签过滤器 type=stock GROUPBY 类型 REDUCE max 1) 1) "type=stock" 2) 1) 1) "type" 2) "stock" 2) 1) "减速机" 2) "max" 3) 1) "来源" 2) “库存：A，库存：B” 3) 1) 1) （整数）1000 2) 120 2) 1) （整数）1010 2) 110 3) 1) （整数）1020 2) 120

FILTER type=stock 子句返回表示股票价格的单个时间序列。 GROUPBY type REDUCE max 子句将时间序列拆分为具有相同类型值的组，然后对于每个时间戳，使用最大聚合器聚合共享相同类型值的所有序列。

Calculate average stock price and retrieve maximum average

创建两只股票并添加它们在九个不同时间戳的价格。

127.0.0.1:6379> TS.CREATE 库存:A LABELS 类型库存名称 A OK 127.0.0.1:6379> TS.CREATE 库存:B LABELS 类型库存名称 B OK 127.0.0.1:6379> TS.MADD 库存:A 1000 100 库存:A 1010 110库存：A 1020 120 1)（整数）1000 2）（整数）1010 3）（整数）1020 127.0.0.1:6379> TS.MADD 库存：B 1000 120 库存：B 1010 110 库存：B 1020 100 1)（整数） 1000 2) (整数) 1010 3) (整数) 1020 127.0.0.1:6379> TS.MADD 股票：A 2000 200 股票：A 2010 210 股票：A 2020 220 1) (整数) 2000 2) (整数) 2010 3) （整数）2020 127.0.0.1:6379> TS.MADD 股票：B 2000 220 股票：B 2010 210 股票：B 2020 200 1)（整数）2000 2）（整数）2010 3）（整数）2020 127.0.0.1:6379> TS.MADD 库存：A 3000 300 库存：A 3010 310 库存：A 3020 320 1) (整数) 3000 2) (整数) 3010 3) (整数) 3020 127.0.0.1:6379> TS.MADD库存：B 3000 320 库存：B 3010 310 库存：B 3020 300 1) (整数) 3000 2) (整数) 3010 3) (整数) 3020

现在，对于每只股票，计算每 1000 毫秒时间范围内的平均股票价格，然后检索该时间范围内具有最大平均值的股票。

127.0.0.1:6379> TS.MRANGE - + 带标签聚合平均 1000 过滤器类型=stock GROUPBY 类型 REDUCE max 1) 1) "type=stock" 2) 1) 1) "type" 2) "stock" 2) 1) "减速机" 2) "max" 3) 1) "来源" 2) "库存：A，库存：B" 3) 1) 1) （整数）1000 2) 110 2) 1) （整数）2000 2) 210 3) 1) （整数）3000 2) 310

Group query results

查询指标标签等于 cpu 的所有时间序列，然后根据其 metric_name 标签值对时间序列进行分组，并为每个组返回最大值以及具有该值的时间序列键 (来源)。

127.0.0.1:6379> TS.ADD ts1 1548149180000 90 标签指标 cpu metric_name 系统（整数） 1548149180000 127.0.0.1:6379> TS.ADD ts1 1548149185000 45 （整数）1548149185000 127.0.0.1:6379> TS.ADD ts2 1548149180000 99 个标签指标 cpu metric_name 用户（整数）1548149180000 127.0.0.1:6379> TS.MRANGE - +WITHLABELS FILTER metric=cpu GROUPBY metric_name REDUCE max 1) 1) "metric_name=system" 2) 1) 1) "metric_name" 2) "system" 2) 1) "减速机" 2) "max" 3) 1) "来源" 2) "ts1" 3) 1) 1) （整数） 1548149180000 2) 90 2) 1)（整数） 1548149185000 2) 45 2) 1) “metric_name=用户” 2) 1) 1) “metric_name” 2) “用户” 2) 1) “减速机” 2) “最大” 3) 1) “来源” 2) “ts2” 3) 1) 1)（整数）1548149180000 2) 99

Filter query by value

查询所有指标标签等于cpu的时间序列，然后过滤大于等于90.0、小于等于100.0的值。

127.0.0.1:6379> TS.ADD ts1 1548149180000 90 标签指标 cpu metric_name 系统（整数） 1548149180000 127.0.0.1:6379> TS.ADD ts1 1548149185000 45 （整数）1548149185000 127.0.0.1:6379> TS.ADD ts2 1548149180000 99 个标签指标 cpu metric_name 用户（整数）1548149180000 127.0.0.1:6379> TS.MRANGE - + FILTER_BY_VALUE 90 100 带标签过滤器 metric=cpu 1) 1) "ts1" 2) 1) 1) "metric" 2) "cpu" 2) 1) "metric_name" 2) "system" 3) 1) 1) （整数） 1548149180000 2) 90 2) 1) "ts2" 2) 1) 1) “指标” 2) “cpu” 2) 1) “metric_name” 2) “用户” 3) 1) 1) （整数）1548149180000 2) 99

Query using a label

查询所有指标标签等于cpu的时间序列，但只返回团队标签。

127.0.0.1:6379> TS.ADD ts1 1548149180000 90 标签指标 cpu metric_name 系统团队 NY (整数) 1548149180000 127.0.0.1:6379> TS.ADD ts1 1548149185000 45（整数）1548149185000 127.0.0.1:6379> TS.ADD ts2 1548149180000 99 标签指标 cpu metric_name 用户团队 SF（整数）1548149180000 127.0.0.1:6379> TS.MRANGE - + SELECTED_LABELS 团队过滤指标=cpu 1) 1) "ts1" 2) 1) 1) "团队" 2) "NY" 3) 1) 1) （整数） 1548149180000 2) 90 2) 1) （整数） 1548149185000 2) 45 2) 1) “ts2”2) 1) 1) “团队”2) “SF”3) 1) 1)（整数）1548149180000 2) 99

Exclude empty time series from the reply

创建三个共享标签 s=1 的时间序列，然后添加样本，以便其中只有两个具有 - 500 范围内的数据。

127.0.0.1:6379> TS.CREATE s 标签 s 1 t 1 确定 127.0.0.1:6379> TS.CREATE t 标签 s 1 t 1 确定 127.0.0.1:6379> TS.CREATE u 标签 s 1 t 1 确定127.0.0.1:6379> TS.MADD s 100 100 t 100 100 s 200 200 t 300 300 s 400 400 t 400 400 u 2000 2000 1) (整数) 100 2) (整数) 100 3) (整数) 200 4) (整数) 300 5) (整数) 400 6) (整数) 400 7) (整数) 2000

使用 EXCLUDEEMPTY 查询 - 500 范围。时间序列 u 的唯一样本位于时间戳 2000，该范围内没有样本，因此从回复中省略。

127.0.0.1:6379> TS.MRANGE - 500 带标签排除过滤器 s=1 1) 1) "s" 2) 1) 1) "s" 2) "1" 2) 1) "t" 2) "1" 3) 1) 1) （整数） 100 2) 100 2) 1) (整数) 200 2) 200 3) 1) (整数) 400 2) 400 2) 1) "t" 2) 1) 1) "s" 2) "1" 2) 1) "t" 2) "1" 3) 1) 1) (整数) 100 2) 100 2) 1) (整数) 300 2) 300 3) 1) (整数) 400 2) 400

如果没有 EXCLUDEEMPTY，也会报告 u，但样本列表为空。

127.0.0.1:6379> TS.MRANGE - 500 带标签过滤器 s=1 1) 1) "s" ... 2) 1) "t" ... 3) 1) "u" 2) 1) 1) "s" 2) "1" 2) 1) "t" 2) "1" 3) （空数组）

Redis Software 与 Redis Cloud 兼容性

Redis
软件		 Redis
Cloud		 说明
✅ 支持
 ✅ 灵活且每年一次
✅ 免费和固定

返回值

RESP2

如果未指定 GROUPBY label REDUCE reducer：

数组回复：对于与指定过滤器匹配的每个时间序列，报告以下内容： - 批量字符串回复：时间序列键名称 - 数组回复：标签值对（批量字符串回复、批量字符串回复） - 默认情况下，报告空数组 - 如果指定 WITHLABELS，则报告与该时间序列关联的所有标签 - 如果指定 SELECTED_LABELS label...，则报告所选标签（未定义此类标签时为空值） - 数组回复：表示与范围匹配的所有样本/聚合： - 没有 AGGREGATION 或使用单个聚合器：表示（时间戳、值）的时间戳值对（整数回复、简单字符串回复） - 使用多个聚合器：表示（时间戳、值...）的时间戳值元组（整数回复、多个 简单字符串回复）

如果指定了 GROUPBY label REDUCE reducer：

数组回复：对于与指定过滤器匹配的每组时间序列，报告以下内容： - 批量字符串回复 格式为 label=value，其中 label 是 GROUPBY 标签参数 - 数组回复：标签值对（批量字符串回复、批量字符串回复）： - 默认情况下，报告空数组 - 如果指定 WITHLABELS，则报告 GROUPBY 标签参数和值报告 - 如果指定了 SELECTED_LABELS label...，则报告选定的标签（当未定义此类标签或标签对于所有分组时间序列不具有相同值时为空值） - 数组回复：单个对（批量字符串回复、批量字符串回复）：GROUPBY 标签参数和值，或空数组 - 数组回复：单个对（批量字符串回复、批量字符串回复）：字符串 __reducer__ 和缩减器参数 - 数组回复：单个对（批量字符串回复、批量字符串回复）：字符串 __source__ 和以“,”分隔的时间序列键名称 - 数组回复：表示与范围匹配的所有样本/聚合： - 没有 AGGREGATION 或使用单个聚合器：时间戳值对（整数回复、 简单字符串回复）表示（时间戳，值） - 具有多个聚合器：时间戳值元组（整数回复，多个简单字符串回复）表示（时间戳，值...）

RESP3

如果未指定 GROUPBY label REDUCE reducer：

地图回复：对于与指定过滤器匹配的每个时间序列，报告以下内容： - 批量字符串回复：时间序列键名称 - 地图回复 或 数组回复：标签值对 - 默认情况下，报告空映射 - 如果指定 WITHLABELS，则与此时间序列关联的所有标签都报告为映射 - 如果指定 SELECTED_LABELS label...，则将所选标签报告为映射（未定义此类标签时为空值） -其他元数据，包括聚合器信息 - 数组回复：表示与范围匹配的所有样本/聚合： - 没有 AGGREGATION 或使用单个聚合器：表示（时间戳、值）的时间戳值对（整数回复、双重回复） - 使用多个聚合器：表示（时间戳、值...）的时间戳值元组（整数回复、多个 双重回复）

如果指定了 GROUPBY label REDUCE reducer：

与 RESP2 类似的结构，但具有基于地图的标签和元数据组织，以及双值而不是字符串值。

参见

TS.RANGE | TS.MREVRANGE | TS.REVRANGE

Redis时间系列

资料来源：Redis 官方 TS.MRANGE 文档；中文内容参考 Redis 文档许可。