• 即使在原始过滤中未选中该列。只要它是某个已选指标所必需，也会自动加入，并记录来源为 “selected_metric”。这确保计算聚合时不会遗漏关键列。

推断表关系 & 自动补齐桥接事实表...

• 如果两张维度没有直接关系。但存在事实桥接，则自动插入桥接事实并仅携带所需 join 字段，如 fact_order.region_id & fact_order.customer_id。这样既完成连接，又避免无关字段被注入 Prompt。

BFS 寻找最短方法...

• 利用广度优先搜索确定最短 join 数目；若无方法则报错 “无法根据现有主外键元数据连接表”。这样能预防笛卡尔积产生的数据爆炸。

补全 JOIN 键但不扩大业务字段...

* 使用者痛点四：过多无关列会让 LLM 难以判断真正 join 条件，从而误生成跨越多张无关表的大型查询。* 本实现仅加入真正 join 字段，并标记来源 'join_relation'。*

添加日期与时区...

* 使用者痛点五：默认服务器时区可能与业务所在地区不同，导致 “今天”“本月”等时间表达式错误。* 本方案显式传递 current_datetime、timezone 等信息，让模型能够准确处理相对时间。*

SSE事件监控 …

json { 说到"type"，"context","table_count":"..."。... }

1. 通过此事件可实时检查哪些列是因指标被补入、哪些是 join 桥接等。* **运行测试** – `uv run python -m unittest discover -s tests -p 'test_*.py' -v`

   至于第二部分。SQL 上下文科普

   什么是 Context Engineering

   Context Engineering 是为模型准备足够且但是量的信息，以完成特定任务。 说起来，

   什么是 Schema Linking

   Schema Linking 将自然语言中的概念映射到数据库 Schema 元素。例如： 销售额 → fact_order.order_amount 北京 → dim_region.province = '北京市' GMV → metric GMV

   主键 / 外键 / JOIN

   概念	示例	用途
   主键	dimregion.regionid	唯一标识行
   外键	factorder.regionid	引用主键
   JOIN 示例	JOIN dim_region ON fact_order.region_id = dim_region.region_id	联合两张表

   桥接表

   当两张维度没有直接关联，需要通过第三张事实表连接。按理说，例如的观点是，dim_customer ↑ fact_order ↓ dim_region 桥接事实仅携带必要 join 字段，不引入所有业务列。话说回来，

   BFS 是否能找到正确 JOIN？

   BFS 能找到边数最少方法，但不能自动判断业务语义。若同两张间存在多条方法，需要显式关系元数据或业务描述来决定优先级。

   数据库的关键性

   不同数据库支持不同函数/语法。例如： - 日期函数差异 - JSON 函数差异 - 分页语法差异 必须把真实 dialect 和 version 提供给模型，否则生成语句会报错。

   时区显式传递的关键性

   相对时间如 “今天”“本月”“今年”等依赖时区。在 UTC 同一刻上海可能已过午夜，而洛杉矶仍是前一天。显式传递 `current_datetime` 与 `timezone` 能保证语义一致。老实说，

   N+ 查询问题

   单独查询每个对象会导致 `N+` 次访问。当元数据规模扩大，这会极大增加延迟与压力。说到方法包括，1. 批量查询 `)；2. 一次性读取整个快照；3. 对低频变更元数据做缓存。

   无法连接时应立即失败

   如果两张未关联的数据无法通过已有主外键连通。应在上下文阶段报错，而不是让 LLM 猜测，从而避免产生 CROSS JOIN 或笛卡尔积。

   这篇文章小结

   1. 从 meta MySQL 批量读取所有相关对象；
   2. 用 meta 库校验并补全过滤结果；
   3. 自动注入指标所需列；
   4. 推断主外键关系并寻找最短 join 方法；
   5. 必要时插入桥接事实仅携带所需 key；
   6. 补全当前日期、时区及数据库信息；
   7. 输出可直接供下一节点消费的 sql_context。

   下一篇将把 sql_context 注入 SQL 生成功能，符合 MySQL 的查询语句。