Redis TopK.ADD 返回被淘汰元素时怎么判断哪个候选退出

Redis TopK.ADD 返回的不是“成功/失败”标记，而是一个与输入 item 按位置对齐的数组。某个位置返回字符串，表示对应的新 item 进入 Top-K 时挤出了一个旧候选；返回 nil/null，表示这个位置没有候选退出。要判断哪个候选退出，先看返回槽位，再把非空值当作被挤出的旧候选读取。

官方地址：https://redis.io/docs/latest/commands/topk.add/

例如执行 TOPK.ADD topk foo bar 42 后得到 nil、baz、nil，应解释为 bar 这次写入挤出了 baz；不能把返回值 baz 当成新加入的 item，也不能把它理解成 Redis 因内存不足删除了一个 key。

先把返回数组和输入 item 按位置对齐

TOPK.ADD key items [items ...] 可以一次接收多个 item。返回数组的第 1 个元素对应第 1 个输入，第 2 个元素对应第 2 个输入，以此类推。只有某个新 item 进入了当前 Top-K，并因此让旧候选退出时，对应槽位才会出现被挤出的字符串。

官方示例中的结果可以按下面的表来读：

因此，批量命令不要只做“返回数组非空”判断。应用侧应保留输入数组，用下标把 items[i] 和 dropped[i] 绑定起来；这样才能记录“谁进入、谁退出”的事件。

单个和批量写入都用同一条判定规则

单个 item 时，返回结果可以直接判定；多个 item 时，按数组位置逐项判定。下面的命令只演示读取语义，注释说明了每一步的目的：

# 先确保 Top-K sketch 已经存在；TOPK.ADD 不负责初始化 key
redis-cli TOPK.RESERVE topk 3

# 每个输入位置都会得到一个返回槽位
redis-cli TOPK.ADD topk foo bar 42

# 单个写入时，非空返回值就是被挤出的旧候选
redis-cli TOPK.ADD topk new_candidate

如果客户端返回数组中的第二项是 baz，判断式可以写成：items[1] = bar、dropped[1] = baz，所以记录一条“bar 触发 baz 退出”的事件。若该槽位为 nil 或 RESP3 的 null，不要当作异常重试；它只是说明这次更新没有让旧候选退出。

还要把命令错误和正常空槽位分开：不存在 Top-K key、参数数量不对或 key 类型错误属于命令错误；非空数组中的 nil/null 属于正常返回内容。这样日志和告警才不会把每次未发生淘汰都报成故障。

用三条命令复查候选是否真的退出

TOPK.ADD 的返回值适合记录“本次更新发生了什么”，而复查当前状态时要看另外三个命令：

• TOPK.LIST topk：查看当前 Top-K 列表，确认被返回的旧候选是否已经不在当前列表中。
• TOPK.QUERY topk baz：查询某个候选是否仍被视为 Top-K 成员，结果是成员关系，不是退出事件。
• TOPK.COUNT topk bar baz：读取候选的概率计数，用来辅助解释排名变化，不能把它当作精确频次。

# 查看写入之后当前保留的 K 个候选
redis-cli TOPK.LIST topk

# 检查被返回的候选是否仍在 Top-K 成员集合中
redis-cli TOPK.QUERY topk baz

# 对比触发写入的新候选和被挤出的旧候选的近似计数
redis-cli TOPK.COUNT topk bar baz

这三步的顺序很实用：先保存 TOPK.ADD 回执，再按需查询当前列表和成员关系。不要反过来只依赖 TOPK.LIST 推断“谁刚刚退出”，因为列表是当前快照，无法告诉你是哪一次写入造成了变化。

应用侧记录事件时要守住两个边界

第一，Top-K 是概率数据结构，适合从流式数据里找高频候选，计数和排名存在近似性。返回非空值说明该次 sketch 更新报告了一个被挤出的候选，但不应据此声称完整流量中的精确排名已经确定。如果业务需要精确审计或可回放排行榜，应另外保存原始事件或使用精确数据结构。

第二，本文的“淘汰”只指候选离开 Top-K 列表，不是 Redis 的 maxmemory-policy 对 key 做的内存淘汰。两者的触发条件、对象和后续处理都不同：前者可以把返回值写入热点变化日志，后者要从 Redis 内存配置、命中率和 key 生命周期排查。

在 Go 客户端里可以把解析逻辑压缩成一个明确的循环，关键是保留输入顺序并跳过空槽位：

// RecordTopKChanges 将每个输入和对应的被挤出候选配对。
// dropped[i] 为空时表示该次更新没有候选退出，不是命令失败。
func RecordTopKChanges(items, dropped []string) []string {
	changes := make([]string, 0, len(items))
	for i := range items {
		if i >= len(dropped) || dropped[i] == "" {
			continue // 空槽位是正常结果，避免制造误报警
		}
		changes = append(changes, items[i]+" -> "+dropped[i])
	}
	return changes
}

真实客户端可能用 nil、空指针或专用空值类型表示 RESP 的空槽位，接入时要按客户端 API 处理，不要仅凭字符串比较。命令层的错误则应由调用返回的 error 单独处理。

常见问题

返回的字符串是新加入 Top-K 的 item 吗？

不是。非空字符串是被挤出列表的旧候选；新加入的 item 由你调用时传入的输入位置确定。

每次 TOPK.ADD 都会返回一个候选吗？

不会。只有发生候选退出的输入位置返回非空值，其余位置正常返回 nil/null。

能用 TOPK.LIST 找出刚刚退出的候选吗？

不能可靠地还原事件。应优先保存 TOPK.ADD 的返回数组，TOPK.LIST 只适合查看当前快照。

Top-K 候选退出是不是 Redis 删除了一个 key？

不是。它是 sketch 内部的候选替换；Redis 全局 key 淘汰属于内存策略问题，排查路径完全不同。

最稳妥的判断顺序就是：保留输入顺序，逐槽读取 TOPK.ADD 返回值；非空值记录为“输入 item 触发旧候选退出”，空值跳过；需要解释当前状态时，再用 TOPK.LIST、TOPK.QUERY 和 TOPK.COUNT 做辅助复查。