Redis TimeSeries 一次查询多个聚合器的结果组织

我第一次把 RedisTimeSeries 的监控查询从“每个统计值发一次请求”改成一次返回多个聚合器时，真正需要调整的不是命令本身，而是结果对象：Redis 返回的是按声明顺序排列的时间戳元组，而不是带有 min、avg、max 名称的对象。只要先固定查询顺序，再在应用侧按位置映射，结果就很容易维护。

官方资料：https://redis.io/docs/latest/commands/ts.mrange/

本文的核心做法是：用 TS.MRANGE 的 AGGREGATION min,avg,max 60000 一次计算同一时间桶的多项统计，并把每个结果元组固定解析为“时间戳、最小值、平均值、最大值”。如果需求是跨多个序列按标签归并，则改用单个聚合器配合 GROUPBY ... REDUCE ...，不要把两种模式强行拼在一起。

我先把旧查询改成一个结果契约

旧代码通常分别查询最小值、平均值和最大值，然后在客户端按时间戳合并。这样做的问题是请求数变成三倍，三个查询的桶边界也可能不一致，最后合并时还要处理缺失桶。RedisTimeSeries 的多聚合器能力适合把这组“同一序列、同一时间桶”的统计放回服务端完成。

这个能力依赖 RedisTimeSeries 的查询聚合支持；官方命令文档还特别说明，多个聚合器用逗号分隔，聚合器之间不能留空格。本文采用 60000 毫秒桶，只讨论查询时聚合，不讨论把结果写入新的压缩序列。

先用标签把时序键变成可筛选的数据集

TS.MRANGE 不像 TS.RANGE 那样直接接收一个 key，而是通过标签过滤多个时序。实际项目里，建议把“业务维度”和“指标名称”写成稳定标签；key 负责唯一性，标签负责查询条件。下面的命令只展示准备数据的形状：

# 为三个地点创建同一种 CPU 指标，标签名保持一致，便于 MRANGE 过滤
TS.CREATE sensor:bj:cpu LABELS metric cpu region north
TS.CREATE sensor:sh:cpu LABELS metric cpu region east
TS.CREATE sensor:gz:cpu LABELS metric cpu region south

# 用相同的时间戳写入示例样本，方便比较同一时间桶中的聚合结果
TS.MADD sensor:bj:cpu 1710000000000 42.0 sensor:bj:cpu 1710000030000 48.0 \
        sensor:sh:cpu 1710000000000 55.0 sensor:sh:cpu 1710000030000 61.0 \
        sensor:gz:cpu 1710000000000 37.0 sensor:gz:cpu 1710000030000 44.0

这里的 region 只是筛选和后续分组的维度示例。若一个 key 同时承载不同指标，必须在过滤条件中明确写出 metric=cpu，否则结果集合会混入不相干的时序。

一次查询拿到多个聚合值时，返回结果怎么读

查询语句的关键部分如下：

# 一次查询所有 CPU 时序，按 1 分钟桶返回最小值、平均值和最大值
# 结果中的三个数依次对应 min、avg、max，顺序不要在客户端临时猜测
TS.MRANGE - + \
  AGGREGATION min,avg,max 60000 \
  FILTER metric=cpu

如果某个时间桶里有数据，返回的样本可按下面的抽象形式理解：[timestamp, minValue, avgValue, maxValue]。比如声明顺序是 min,avg,max，就不要把第二个值当成平均值、第三个值当成最大值之后再按字段名重新排序；应用侧应该把“查询字符串”和“解析结构”一起维护。

RESP2 下这些数值通常以字符串形式出现在数组里，RESP3 会使用更结构化的返回表示。无论客户端协议是哪一种，业务层最好尽快转换为自己的类型，而不是让控制器、报表和缓存层重复理解 Redis 的嵌套数组。

// Bucket 固定承接 TS.MRANGE 的 [timestamp, min, avg, max] 元组。
// 解析前先检查长度，避免空桶或协议差异造成越界访问。
type Bucket struct {
	Timestamp int64
	Min       float64
	Avg       float64
	Max       float64
}

func decodeBucket(row []string) (Bucket, error) {
	// 多聚合器至少应有时间戳和三个聚合值。
	if len(row) != 4 {
		return Bucket{}, fmt.Errorf("unexpected bucket fields: %d", len(row))
	}

	timestamp, err := strconv.ParseInt(row[0], 10, 64)
	if err != nil {
		return Bucket{}, fmt.Errorf("parse timestamp: %w", err)
	}
	minValue, err := strconv.ParseFloat(row[1], 64)
	if err != nil {
		return Bucket{}, fmt.Errorf("parse min: %w", err)
	}
	avgValue, err := strconv.ParseFloat(row[2], 64)
	if err != nil {
		return Bucket{}, fmt.Errorf("parse avg: %w", err)
	}
	maxValue, err := strconv.ParseFloat(row[3], 64)
	if err != nil {
		return Bucket{}, fmt.Errorf("parse max: %w", err)
	}

	return Bucket{Timestamp: timestamp, Min: minValue, Avg: avgValue, Max: maxValue}, nil
}

示例中的字段顺序不是 Redis 自动附带的字段名，而是由 AGGREGATION 参数决定的契约。以后如果改成 max,avg，就必须同步修改结构和解码器；更稳妥的做法是把聚合器列表定义成常量，查询构造和结果解码共用它。

多聚合器与跨序列归并要分成两种查询

我迁移时最容易踩到的边界是：多聚合器解决“每条时序在每个桶里要多个统计值”，而 GROUPBY ... REDUCE ... 解决“多条时序按标签合成一条分组结果”。Redis 官方文档明确说明，GROUPBY/REDUCE 不能和多个聚合器一起使用。

如果目标是每个区域得到一条平均曲线，可以这样写：

# 先按 1 分钟对每条时序求平均，再按 region 跨序列求平均
# 这里使用单个 avg，因为 GROUPBY/REDUCE 不能与 min,avg,max 同时出现
TS.MRANGE - + \
  AGGREGATION avg 60000 \
  FILTER metric=cpu \
  GROUPBY region REDUCE avg

这种返回结果的组织方式会变成分组序列，例如 region=north，并带有 reducer 和来源序列等元信息；它不再是“每个原始 key 一组、每个桶三列”的结构。如果报表既要每个区域的 min/avg/max，又要跨区域的总平均，应该拆成两个明确的查询契约，或者先拿多聚合器结果再由应用侧按业务定义归并，不能把两个命令片段简单拼接。

迁移时我会保留的四项检查

从三个独立查询迁移到一次多聚合器查询后，我会把下面四项写进代码评审清单：

• 聚合器顺序是否在查询构造、结果解码和接口文档中保持一致。
• 时间桶是否固定了时长与对齐方式，避免不同查询出现边界偏移。
• 筛选标签是否只包含同一指标，空桶、缺失序列和无数据范围如何呈现。
• 需求究竟是单序列多列统计，还是跨序列分组；若是后者，是否改为单聚合器加 GROUPBY/REDUCE。

我的结论是：当页面需要同一批时序在同一时间桶中的 min、avg、max 时，多聚合器能让请求和结果边界更清楚；当页面需要按标签汇总多条时序时，优先采用单聚合器的分组查询。把返回结构先设计成稳定的业务对象，再决定用哪一种 Redis 查询，迁移成本会低很多。

相关问题

多个聚合器之间可以写空格吗？

不建议。官方语法使用逗号分隔，例如 min,avg,max，不要写成带空格的列表。

为什么 GROUPBY 和 min,avg,max 一起执行会失败？

两者处在不同的结果组织层：前者跨序列归并，后者为每条序列生成多值元组。官方命令约束禁止把它们叠加，应该拆成两次查询或重新定义指标。