Lightdash项目中重复使用同一图表导致列缺失错误的分析与解决方案

问题背景

在Lightdash数据可视化平台中，当用户在同一个仪表板中多次使用同一个图表时，系统可能会出现列缺失的错误。这一问题的根源在于缓存机制的设计缺陷，导致多个图表实例无法独立加载数据结果。

技术原理分析

Lightdash的缓存系统采用基于查询哈希（query_hash）的唯一键机制来存储查询结果。当两个相同的图表同时加载时，它们会尝试向缓存表中插入或更新同一行数据，因为它们的缓存键是相同的。这种设计导致了以下问题：

1. 竞态条件：多个并发请求会竞争同一个缓存条目
2. 数据一致性风险：后完成的查询会覆盖先前的缓存结果
3. 依赖关系混乱：不同图表实例无法维护各自独立的数据状态

深入问题本质

问题的核心在于缓存表设计的局限性。当前系统使用cache_key作为唯一标识符，这导致：

• 无法区分同一查询的不同实例
• 缓存更新操作是破坏性的（upsert）
• 缺乏对查询状态的精细管理

解决方案设计

经过技术团队深入讨论，提出了以下架构改进方案：

1. 废弃现有缓存表：完全移除当前的缓存表结构
2. 强化查询历史表：将所有缓存信息迁移到query_history表中
3. 新的索引设计：
   • 使用query_hash作为非唯一索引字段
   • 新增file_name字段存储结果文件信息
4. 状态感知机制：
   • 通过state=ready和created_at时间戳判断缓存有效性
   • 自动处理过期缓存（基于stale time配置）

实施细节

新方案的工作流程如下：

1. 缓存查询阶段：

   • 系统首先通过query_hash+state条件查找可用缓存
   • 验证缓存未过期（created_at + stale time）
   • 将相同file_name应用于新查询

2. 并发处理场景：

   • 当多个相同查询同时触发且状态非ready时
   • 系统会创建多条query_history记录
   • 每个查询生成独立的结果文件
   • 避免缓存覆盖问题

技术优势

这一改进带来了多项好处：

1. 简化架构：减少了一个数据表，降低维护复杂度
2. 提高可靠性：彻底解决了竞态条件问题
3. 更好的可观测性：所有查询历史集中管理
4. 灵活的状态管理：支持更丰富的查询生命周期控制

总结

Lightdash团队通过重构缓存机制，从根本上解决了重复图表导致的列缺失问题。新设计不仅修复了现有缺陷，还为系统未来的扩展提供了更坚实的基础。这一改进体现了Lightdash对数据一致性和系统可靠性的高度重视，也是平台持续优化用户体验的重要里程碑。