ktx语义层如何把Agent意图编译成安全SQL:实现原理完全解析

原创2026-10-11 18:39:031,339 阅读

ktx语义层如何把Agent意图编译成安全SQL:实现原理完全解析

ktx 是一个面向数据分析 Agent 的可执行上下文层。它的语义层把 Agent 的自然意图("各客户分段的净收入")编译成安全、符合方言的 SQL:Agent 只提交度量、维度、过滤条件,ktx 负责选表、走连接路径、定聚合粒度、防数字膨胀,最终只读执行并返回答案。本文完整解析这条"意图 → SQL"编译链路背后的实现原理。

ktx MCP运行时流程:Agent提问,ktx检索wiki与语义层、把指标编译成SQL并在只读仓库上执行

核心思路:谁维护"怎么算",谁声明"要什么"

让 Agent 直接写分析 SQL,每个问题都要同时操心两件事:要什么(度量、切面、过滤)和怎么算(连哪些表、按哪个键连、在哪个粒度聚合、方言怎么写)。ktx 语义层把两者彻底分离:

  • 你和 ktx 维护"怎么算":数据源、连接关系、粒度(grain)、度量(measures)、过滤片段都写在可版本管理的 YAML 里,见 orders.yaml:
name: orders
table: public.orders
grain: [id]
measures:
  - name: total_revenue
    expr: sum(amount)
joins: []
  • Agent 声明"要什么":它发送一个语义查询,然后信任编译器产出安全 SQL。

一个典型的语义查询长这样——注意里面没有 FROM、JOIN、GROUP BY:

{
  "measures": ["orders.revenue", "tickets.ticket_count"],
  "dimensions": ["customers.segment"],
  "filters": ["orders.created_at >= '2025-01-01'"],
  "limit": 1000
}

所有列引用都写成 source.column 全限定形式,编译器永远不需要猜名字来自哪张表。

一次查询的8步编译流水线:planner 做了什么

入口在 SemanticEngine:装载 YAML → 构建连接图 → 交给 QueryPlanner.plan() 做确定性规划 → 由 SqlGenerator.generate() 产出 SQL。规划是一条固定的有序流水线,同一条查询每次都走同样的步骤:

阶段 做什么 源码位置
0 校验可见性 拒绝不可查询的列 planner.py
1 解析维度 把裸列名补全为 source.column,有歧义直接报错 planner.py
2 解析度量 查预定义度量、拒绝窗口函数与嵌套聚合、展开度量依赖链 planner.py
3 选锚点 以第一个原始度量的来源表作为连接树根 planner.py
4 建连接树 在连接图上求最短路径,连出所有需要的表 planner.py
5 检测 fanout 度量分属多个来源表时标记 chasm trap planner.py
6 分类过滤 行级条件进 WHERE,度量条件进 HAVING planner.py
7 生成 SQL 安全查询走单聚合,fanout 查询走 CTE 局部聚合 generator.py
8 转译方言 经 sqlglot 归一化到目标数仓语法 generator.py

规划输出的是一个 ResolvedPlan:用了哪些表、走了哪些连接路径、锚点粒度、WHERE/HAVING 分类、是否触发 fanout 处理。SQL 只是这个计划的一份"渲染结果"。

连接图:表是节点,join 是带类型的边

连接图由 JoinGraph.build() 从 YAML 构建:每条正向连接都自动补一条关系反转的逆向边(many_to_one ↔ one_to_many),因此 planner 可以从任意锚点出发遍历。

求路用 Dijkstra 最短路径,且安全路径权重 1、one_to_many 边权重 10(graph.py)——同样多跳时优先走不会放大数字的方向。多条等成本路径会被标记为 is_ambiguous 并告警,提示用连接别名消除歧义。多表查询则做 Steiner 树近似:从锚点向每个目标求最短路径再合并(resolve_join_tree),找不到路径直接拒绝查询,而不是拼出一条瞎猜的 JOIN。

不同关系类型对规划的影响:

关系 规划影响
many_to_one 添加维度的安全方向
one_to_many 会放大度量,触发 fanout 处理
one_to_one 键匹配时双向安全
等成本路径 视为歧义,需别名或显式连接消解

防止数字翻倍:fanout 检测与 aggregate locality

**Fanout(扇出)**是经典分析陷阱:两张事实表都连到同一维表时,简单地把它们全 join 在一起,一张事实表的每一行都会被另一张的匹配行成倍放大——度量翻倍,数字错了,Agent 还浑然不觉。

planner 的检测方式很直接:把原始度量按所属来源表分组(_detect_fan_out)。只要超过一个来源表贡献原始度量,就判定为 chasm trap,SQL 生成器切换到"聚合局部性"路径(_generate_with_locality):

朴素 SQL ktx 语义层 SQL
先 join 事实和维表,再聚合 每张事实表先在自己的粒度上预聚合(CTE),最后再 join 回维表
所有过滤塞进一个外层 WHERE 度量过滤跟随其所属来源表
相信文本上最短的 join 路径 偏好类型化安全路径,拒绝不相连的来源
容忍维表粒度不一致 非对称维表会放大其他度量时报错

结果与分析师手写 SQL 的答案一致,只是 join 形状由编译器保证安全。官方演示用例 complex_cte_join.yaml 完整展示了"两张 SQL 源表 + 维度表 → 触发 chasm trap → 走 aggregate locality"的场景。

方言安全:Postgres 骨架 + sqlglot 转译

编译器刻意把 SQL 分两层:

  • 外层骨架(SELECT / JOIN / GROUP BY / CTE 结构)用 Postgres 风格生成;
  • 用户写的表达式片段(度量 expr、过滤、join on 条件)按连接的原生方言解析,方言特有函数(如 BigQuery 的 TIMESTAMP_SUB、Snowflake 的 DATEADD)原样保留。

最后 _transpile() 用 sqlglot 按目标方言读一遍、写一遍,把骨架翻译成数仓认识的语法,同时给保留字标识符加引号(例如 Snowflake 的 SAMPLE、QUALIFY)。用户片段因为本来就是目标方言,往返转译后完好无损。

上下文从哪来:证据驱动 + 分析师审查

ktx ingestion流程:从数据库、BI工具、建模代码、文档收集证据,经上下文构建、合并、校验,产出语义层YAML与wiki

planner 的质量取决于它读的 YAML,而 ktx 会用证据帮你构建和维护这些 YAML(JoinGraph 构建 只是消费端):

证据 贡献
声明的主键 初始行粒度
声明的外键 正式连接候选
推断关系 数仓缺少约束时的边
dbt / MetricFlow / LookML 导入 现成的指标、维度、连接
查询历史 分析师 SQL 中真实的 join 与过滤模式
分析师审查 合并前的最终权威

目录分工:raw-sources/<connection>/ 存扫描证据,semantic-layer/<connection>/ 存 planner 真正编译的结构化来源,wiki/ 存业务语言与口径定义(供 Agent 检索,不进入编译期)。每次被接受的修正都会回流到下一次 ingest,图因此随数仓变化保持最新。更多细节见 语义层工作原理文档、ktx sl 命令参考 和 示例项目。

安全边界:Agent 能做什么,不能做什么

  • 只读执行:编译出的 SQL 以 read-only 方式发给仓库,没有写路径;
  • 命名约束:query_policy: semantic-layer-only 的连接上,只允许查询预定义度量,运行时拼聚合表达式会被 _reject_composed_measures 拒绝;
  • 表达式白名单:窗口函数、嵌套聚合(avg(sum(x)))、不相连来源、歧义列名,都在规划期抛出明确的 ValueError,而不是交给数据库试错;
  • 可审计:ResolvedPlan 完整记录了连接路径、锚点粒度和 fanout 决策,出了问题可以解释"为什么编译出的 SQL 长这样"。

总结

ktx 语义层的本质是一个把意图编译成 SQL 的确定性编译器:YAML 连接图提供事实,planner 提供路径规划与 fanout 防护,generator 提供双路径 SQL 形状,sqlglot 提供方言安全,证据循环让上下文持续保鲜。Agent 因此可以"声明意图"而不必"推理管道",数字的正确性由可审查的编译器契约来保证——这也是 ktx-sl 整套引擎(planner.py、graph.py、generator.py)值得逐行阅读的原因。

登录后查看全文
ktx-ai-data-agents-context