Redis TDIGEST.CDF与QUANTILE的查询方向有什么区别

Redis t-digest 里，TDIGEST.CDF 和 TDIGEST.QUANTILE 都是在同一个概率草图上做近似查询，但方向正好相反：CDF 接收一个具体数值，返回不超过该数值的累计比例；QUANTILE 接收 0 到 1 之间的分位数，返回对应的估计数值。把“阈值问比例”和“比例问阈值”分开，接口就不容易写反。

官方文档：https://redis.io/docs/latest/commands/tdigest.cdf/

要判断“有多少请求不超过 100ms”，使用 TDIGEST.CDF；要找“P95 延迟是多少”，使用 TDIGEST.QUANTILE。两者都只返回 t-digest 的估算结果，不等同于保存全部明细后的精确排序。

先把两条命令的输入输出方向分开

TDIGEST.CDF key value [value ...] 的输入是一个或多个业务阈值，例如 100、300、1000 毫秒；返回每个阈值对应的累计比例。这个比例按文档定义为“小于该值的观测数，加上等于该值观测数的一半”所形成的估计分数。

TDIGEST.QUANTILE key quantile [quantile ...] 的输入是 0 到 1 的分位数，例如 0.5、0.95；返回每个分位数对应的浮点估计值。可以记成一张反向映射表：

用同一份样本看 CDF 与 QUANTILE 如何互相映射

下面用一组小样本建立同一个 sketch。命令块中的注释只说明实验意图，结果是为了展示参数方向，不应当被当作线上运行截图。

# 创建 t-digest；COMPRESSION 影响草图的空间与近似精度
redis-cli TDIGEST.CREATE latency COMPRESSION 100
# 写入一组模拟请求延迟，单位统一为毫秒
redis-cli TDIGEST.ADD latency 20 35 40 60 80 100 120 180 260 420
# 给定分位数，反查估计延迟值
redis-cli TDIGEST.QUANTILE latency 0.5 0.95
# 给定阈值，反查累计比例
redis-cli TDIGEST.CDF latency 100 200

阅读返回值时不要把两行结果互换：第一行的两个数是 P50、P95 的延迟估计，第二行的两个数是 100ms、200ms 阈值的累计比例。真实数据量增大后，t-digest 会压缩观测分布，所以结果仍是近似值。

按业务问题选择阈值查询还是分位点查询

如果监控规则已经给出阈值，例如“请求耗时不超过 300ms 的比例是否达到 99%”，先调用 CDF，再把返回的小数与 0.99 比较。如果产品报表要展示 P50、P95、P99，则调用 QUANTILE，让分位数作为输入。

这两个命令可以帮助互相解释，但不保证把一次 CDF 结果再反推回完全相同的 QUANTILE 数值。原因是 t-digest 对分布做了压缩，边界和重复值还会影响近似。若业务需要逐条审计、精确排名或可重放明细，应保存原始样本或采用专门的精确统计方案。

处理估算误差、空 sketch 与批量参数

两条命令都允许一次传入多个查询参数，返回顺序与输入顺序对应。参数必须落在各自的语义范围内：QUANTILE 的分位数应在 0 和 1 之间；CDF 的 value 是浮点阈值。key 不存在或不是 t-digest 类型时，不应把错误吞掉后继续写入业务指标。

空 sketch 是另一个容易漏掉的状态。官方返回信息说明，空结构查询会对所有分位数返回 nan；这代表当前没有可用观测，不是“延迟为零”或“达标率为零”。采集端应把 nan 转为缺失状态，等待首批样本进入后再参与聚合。

用一张决策表固定接口封装方式

封装函数时，可以把名称写成 fractionAt(value) 和 valueAt(quantile)，不要让两个函数都只叫“query”。这样在告警、报表和容量评估之间传递参数时，错误方向会更早暴露。

常见问题

TDIGEST.CDF 返回的是精确百分比吗？

不是。它返回 t-digest 对累计比例的估计；如果需要精确百分比，必须保留足够的原始数据并进行精确统计。

QUANTILE 的参数可以写 95 吗？

不可以。命令使用 0 到 1 的分数，P95 应写成 0.95，而不是 95。

为什么空 sketch 不能当成零延迟？

因为空 sketch 没有观测值，nan 表示暂时不可估计。把它转成零会让监控和报表产生虚假的好结果。

记住“阈值问比例用 CDF，比例问阈值用 QUANTILE”，再为两种返回值分别处理近似和缺失状态，Redis t-digest 的查询方向就能稳定落到业务接口里。