GET /api/public/dataset-items/{id} can serve a permanently stale version while the list endpoint shows the current one

快速结论：这一报错通常出现在自托管 Langfuse 处理已经多次 upsert 的数据集条目（dataset item）时：按 ID 读取会返回某个较早的旧版本，而且该错误会一直存在，但列表接口和 UI 列表显示的是新值。优先排查 dataset_items 表中是否同一 (id, project_id) 存在多行 valid_to IS NULL 的“开放行”。

适用环境：自托管 Langfuse v4.32.0（Issue 报告版本），后端存储为 Postgres。Issue 未提供操作系统、Python、CUDA、显卡或依赖版本信息，不应据此推断。

最快修复方案：暂无确认的一步修复方案。Issue 讨论中给出的读侧修改（在按 ID 查询中加入 ORDER BY valid_from DESC，并把两个计数查询改为 COUNT(DISTINCT di.id)）属于“可优先尝试”的修复方向，Issue 中未记录该修改在报告者环境中的验证结果。

注意事项：只改读侧可让按 ID 读与列表一致，但不能防止复发，也不会清除已存在的孤儿开放行；并发创建仍可能留下永久开放行。为 (id, project_id) WHERE valid_to IS NULL 建部分唯一索引属于讨论中的建议，可让不变式由数据库强制约束，但可能让并发插入直接报约束冲突，需评估写入路径行为。清理数据前应先备份。

问题场景

用户在自托管 Langfuse 中通过 POST /api/public/dataset-items 对已有数据集条目执行 upsert（新增 metadata 字段后重新写入），随后用 GET /api/public/dataset-items/{id} 读取该条目，发现返回的是编辑前甚至更早的版本；而 GET /api/public/dataset-items?datasetName=... 列表接口返回当前版本。UI 的条目详情页使用的是按 ID 读取，因此详情页同样显示旧值。该现象不是缓存：读取直接查 Postgres，重启和后续 upsert 都不会让值收敛。

报错原文

GET /api/public/dataset-items/{id} can serve a permanently stale version while the list endpoint shows the current one

原因分析

数据库中缺少“每个 item id 只允许一行开放版本”的强制约束：主键是 (id, project_id, valid_from)，且没有 (id, project_id) WHERE valid_to IS NULL 的部分唯一索引。该不变式仅靠 upsertDatasetItem 的事务维护，而 backfillValidToForDatasetItems 异步关闭历史行，因此迁移不完整、被中断或尚未运行时会留下多行开放记录。

按评论中的复现证据，更具体的来源是创建时的并发竞争：两个并发的 upsertDatasetItem 对尚不存在的条目都读到 current = null，都没有可关闭的行，于是各自插入 valid_to = NULL。评论中受影响的条目第 1、2 行仅相隔 3 ms。此后每次 upsert 都会按 validFrom: "desc" 选中较新的开放行并关闭它，最早的那行再也未被选中，永久保持开放。

按 ID 的读取在 getDatasetItemById（Implementation.VERSIONED）中只有 AND valid_to IS NULL LIMIT 1，没有 ORDER BY；借助 (project_id, id, valid_from) 索引按升序扫描，LIMIT 1 会稳定返回最老的开放行。列表路径 getDatasetItemsInternal 则已在应用层按 id 去重（保留 ORDER BY valid_from DESC 后的第一条），所以两个接口结果不一致。

同类的可能问题还出现在计数查询：buildDatasetItemsCountQuery 和 buildDatasetItemsLatestCountGroupedQuery 使用 COUNT(*)，重复开放行会让总数大于去重后的列表条数，分页总数与可见表格发生漂移。

环境排查

确认 Langfuse 版本是否为 v4.32.0 或相近版本（Issue 在 v4.32.0 上报告）。
确认部署方式为自托管，后端为 Postgres，并确认按 ID 读取确实走数据库而非缓存层。
确认 dataset_items 表是否存在 valid_to IS NULL 的部分唯一索引（Issue 指出当前没有）。
确认 20251216_1001_backfill_dataset_items_valid_to 后台迁移是否已成功完成；评论中该迁移在受影响孤儿行创建前已完成，说明孤儿行不一定是迁移残留。
检查目标数据集条目是否在 dataset_items 中有多于一行 valid_to IS NULL 的记录，以及这些行的 valid_from 间隔是否极小（毫秒级）。
对比同一 id 的按 ID 接口与列表接口返回的 metadata，确认差异是否只出现在存在多个开放行的条目上。
Issue 未涉及 Python、CUDA、PyTorch、显卡或节点版本，无需作为排查项。

解决步骤

先定位受影响条目：查询 dataset_items 中同一 (id, project_id) 存在多行 valid_to IS NULL 的记录，并记录其 valid_from 与 valid_to 版本链。评论中的示例显示最早一行与第二行只差 3 ms，之后版本链正常闭合。
确认现象只出现在多开放行的条目上：对这些条目分别调用按 ID 接口与列表接口，比较 metadata；单开放行条目应表现正常。
可优先尝试读侧修复：在 getDatasetItemById 的查询中加入 ORDER BY valid_from DESC，使按 ID 读取与列表路径一致，即改为 AND valid_to IS NULL ORDER BY valid_from DESC LIMIT 1。
可优先尝试修正计数：将 buildDatasetItemsCountQuery 和 buildDatasetItemsLatestCountGroupedQuery 改为 COUNT(DISTINCT di.id)，避免重复开放行导致总数虚高。
评估存量数据：读侧修复不会清除已存在的孤儿开放行，这些条目会继续在库中保留。如需彻底恢复“每个 id 仅一行开放”的状态，需要人工或迁移方式关闭多余开放行（评论确认该状态不会自愈），操作前务必备份并核对版本链。
评估长期防复发：按讨论建议，考虑为 (id, project_id) WHERE valid_to IS NULL 建立部分唯一索引。该索引会让并发创建中的其中一个插入直接触发约束冲突，从而避免产生孤儿开放行；但因评论中未给出迁移与冲突处理细节，建议先在测试环境验证写入路径。
如需官方修复，可关注 Issue 中提到的修复提交 langfuse/langfuse#20060，该修复将包含在下一个 OSS 版本中；官方同时表示会研究如何防止并发创建。

验证方法

对存在多个开放行的条目再次执行 upsert 后，调用 GET /api/public/dataset-items/{id}，确认返回的 metadata 与 GET /api/public/dataset-items?datasetName=... 列表中该条目的 metadata 一致，且包含最近一次编辑新增的字段。若继续通过列表核对，确认分页总数不再明显大于去重后的实际条目数。若要验证防复发，需要构造两个并发创建同一新 id 的请求，确认只有一个 valid_to IS NULL 行产生（该验证方式属于排查建议，Issue 未记录官方验证过程）。