Redis TDIGEST.BYRANK 怎样按排名查询分位摘要

Redis TDIGEST.BYRANK key rank [rank ...] 根据排名返回 t-digest 摘要中的数值估计。排名从 0 开始，按观测值从小到大计：0 对应最小观测值，样本数为 n 时，n-1 对应最大观测值。它查的是指定位置的数值，不返回原始记录或成员 ID，也不是输入百分比后直接查分位数。

官方地址：https://redis.io/docs/latest/commands/tdigest.byrank/

先定义样本来源和排名含义

考虑把一个时间窗口内的请求耗时写入摘要，再读取若干排序位置。这里的“排名”是数值分布中的顺序，与用户排行榜成员的名次不同。t-digest 汇总数值分布，不能借 BYRANK 还原第几个请求的详细内容。

我会先固定指标单位、窗口范围和重复事件处理规则。例如耗时统一用毫秒，不能把秒与毫秒混写到同一个键。相同数值的多次观测仍属于多次样本，样本数不是不同数值的数量。若重试把同一事件写入两次，摘要不会自动替应用识别它们是同一业务事件。

创建摘要并写入同一窗口的数据

部署需要实际提供 TDIGEST 命令，不能仅凭连接成功就假定能力存在。下列命令供读者在支持该能力的测试实例使用；本文未运行 Redis，未生成实际查询回执。演示键应保持独立，避免把已有业务数据混进样本。

# 创建一份独立摘要，压缩参数是精度和内存的取舍。
redis-cli TDIGEST.CREATE 'demo:tdigest170:latency-ms' COMPRESSION 100

# 给演示数据设置生命周期，再写入八次观测；重复值也计入样本。
redis-cli EXPIRE 'demo:tdigest170:latency-ms' 300
redis-cli TDIGEST.ADD 'demo:tdigest170:latency-ms' 12 18 18 25 37 46 65 90

# 查看 Observations 等信息，不把节点数误认为样本数。
redis-cli TDIGEST.INFO 'demo:tdigest170:latency-ms'

TDIGEST.INFO 中 Observations 表示已加入摘要的观测数，Merged nodes、Unmerged nodes 等描述摘要内部组织，不能拿它们直接代替 n。Compression 控制精度和内存之间的取舍，并不意味着“每个排名都能精确还原”。调整参数时应考虑代表性数据的误差需求，而不是为所有指标套同一个越大越好的配置。

按零基排名查询近似值

# 查询零基位置 0、3、7，返回顺序对应请求排名的顺序。
redis-cli TDIGEST.BYRANK 'demo:tdigest170:latency-ms' 0 3 7

# 也可一次请求不同排列的排名，调用方应逐项对应结果。
redis-cli TDIGEST.BYRANK 'demo:tdigest170:latency-ms' 7 0 3

给定上面的八个观测，rank=7 是末位，rank=8 已超出样本位置。官方文档保证最小与最大观测位置的准确返回；中间位置应作为估计值理解，不要把原始排序数组在第 3 位的值写成必然精确的服务返回。

排名参数是非负整数，不是 0 到 1 之间的比例。若产品入口表达的是某个百分位，需明确采用的统计定义和排名换算规则，或者使用相应分位查询接口；不能直接把 0.95 当作整数排名，也不应把 95 无条件解释为 P95。

读取 INFO 后再读 BYRANK 是两次命令，若期间仍有观测写入，n 可能已经改变。对于需要按固定样本数解释末位的报表，可以使用已经完成的窗口摘要。不要因为两次命令都成功，就声称它们属于同一时刻的业务快照。

区分异常值、空摘要和命令错误

客户端返回结构受 RESP 版本和客户端接口影响。按所用驱动读取浮点值，并在对外序列化前识别非有限数值；不要把 inf、nan 自动改成 0，否则零耗时会与没有数据、排名越界混在一起。对于 JSON API，可以使用明确的状态字段并将不可报告的数值设为 null，具体协议由应用约定。

重复数值会让多个排名得到相同或相近的估计，这不必然表示命令失效。摘要压缩也意味着不能依据返回值去定位某个原始事件。需要事件级回溯时，应另存原始明细或可追溯引用。

为窗口结果保留上下文与清理规则

结果记录建议包含窗口标识、指标单位、摘要键版本、观测数、请求排名和估计值状态。窗口完成后转为只读，能让报表含义更稳定。摘要键过期后，应返回“窗口不可用”，而不是悄悄创建一份空摘要伪装成原窗口。

TTL 作用于整个键，不会按观测时间逐条移除旧样本。若把长时间持续写入的一个摘要当成滑动窗口，就会混入窗口外观测。更清楚的做法是按业务窗口独立建键，并安排归档与过期；跨窗口汇总还需要单独定义口径。

BYRANK 能返回原始样本吗？不能，它返回排名位置的数值估计，不是明细记录检索。

为什么输入 n 会得到 inf？因为零基最后位置是 n-1，n 已在有效样本排名之外。

增加压缩参数就能当作精确排序列表吗？不能。它仍然是分布摘要，应根据误差目标选择；需要精确明细排序时应使用适合保存原始数据的模型。

接口依据：TDIGEST.BYRANK、TDIGEST.INFO、TDIGEST.CREATE。