作者:董颖婷 镜舟科技产品负责人

经营周报对“收入”有明确定义,提问时却常常只说“看一下收入”。同一笔订单,周报记为 80 元,Data Agent 却算出 100 元,可能是选成了订单金额,也可能是选对净收入却漏扣了 20 元退款。前者需要重新确认语义对象,后者需要修正计算定义。两类问题都不会触发 SQL 语法或字段检查:SQL 合法、列名存在,但结果不是周报采用的数。

让大模型直接生成 SQL 时,这两类问题混在同一段文本里。将查询拆成编译链后,概率只出现在“选择”一步:模型产出只包含已注册对象名的语义查询;后续的绑定、展开、授权和执行都有确定的输入与产物。三个月后复核时,团队可以据此重现当时的计算。

MirrorMind 维护语义目录,并为每次查询装配 Context;MirrorPilot 与用户对话,生成语义查询;MirrorData 保存 Semantic View(语义视图,简称 SV)并执行查询。

1. 模型负责选择,数据库负责执行

连用户问“华东最近的收入走势怎么样?”时,订单金额、净收入和财务确认收入都可能是候选。MirrorMind 将当前用户可用的指标、定义和报表约定交给 MirrorPilot,形成 Context。它从完整语义目录中选出与问题相关、对当前用户可见、仍在有效期内的对象(图 1),并记录这次查询可选的范围。

从 Context 到可检查 SQL:Data Agent 的语义编译链-zh

图 1|Runtime Context 从语义目录中选出本次查询所需的对象。

三个候选都符合当前信息,模型需要先澄清:

Agent:您说的“收入”是订单金额、扣除退款后的净收入,还是财务确认收入?周期和区域应与哪份报表一致?

用户:按经营周报的口径看净收入,华东按客户当前区域统计。列出最近 16 个已结束的结算周;没有订单的周记为 0。

对话的产物是一条语义查询。里面没有表名、连接和聚合表达式,只有视图里已注册的指标、维度和过滤条件。

sql
-- 模型的产出物:只引用已注册对象,不含计算定义
SELECT * FROM SEMANTIC_VIEW(
    sales.order_semantics
    METRICS    orders.net_revenue
    DIMENSIONS customers.sales_region, orders.settlement_week
    WHERE customers.sales_region = '华东'
      AND orders.settlement_week >= DAYS_SUB(DATE_TRUNC('week', CURRENT_DATE()), 112)
      AND orders.settlement_week <  DATE_TRUNC('week', CURRENT_DATE())
)

模型在这里完成对象选择。所选指标是否为 orders.net_revenue 可以直接复核;net_revenue 的计算由 Semantic View 定义。目录中没有可用定义时,系统应明确说明当前视图无法回答,而不是临时编造列名。

2. 把口径写成可执行定义

即使选中净收入,计算口径仍要明确:退款归入哪一周,客户变更区域后订单归属哪一边。经营周报将累计退款归回原订单的结算周,并按客户当前区域统计;如果问题是“成交时属于哪个区域”,则按结算时间匹配归属历史中有效的记录。MirrorData 将这些约定写入 Semantic View:

sql
CREATE OR REPLACE SEMANTIC VIEW sales.order_semantics
TABLES (
    orders AS sales.fact_orders PRIMARY KEY (order_id)
        WITH SYNONYMS = ('订单', '交易')
        COMMENT = '每行一笔已结算订单,实付金额非空',
    customers AS sales.dim_customer PRIMARY KEY (customer_id)
        WITH SYNONYMS = ('客户', '买方')
        COMMENT = '客户主数据,一客户一行,region 为当前区域',
    customer_history AS sales.dim_customer_history
        PRIMARY KEY (customer_id, valid_from)
        CONSTRAINT DISTINCT RANGE BETWEEN valid_from AND valid_to EXCLUSIVE
        WITH SYNONYMS = ('客户归属历史')
        COMMENT = '客户区域归属的有效期 [valid_from, valid_to),同一客户的区间不重叠'
)
RELATIONSHIPS (
    order_to_customer AS orders (customer_id)
        INNER REFERENCES customers (customer_id),
    order_to_region_at_settlement AS orders (customer_id, settled_at)
        LEFT REFERENCES customer_history
            (customer_id, BETWEEN valid_from AND valid_to EXCLUSIVE)
)
DIMENSIONS (
    orders.settlement_week AS DATE_TRUNC('week', orders.settled_at)
        WITH SYNONYMS = ('结算周', '周')
        COMMENT = '按 settled_at 归集,业务时区 Asia/Shanghai,周一起始',
    customers.sales_region AS customers.region
        WITH SYNONYMS = ('区域', '当前区域')
        COMMENT = '客户当前销售区域,经营周报口径',
    customer_history.region_at_settlement AS customer_history.region
        WITH SYNONYMS = ('成交时区域', '历史区域')
        COMMENT = '订单结算时客户所属的区域'
)
METRICS (
    orders.net_revenue AS
        SUM(orders.paid_amount - COALESCE(orders.refund_amount, 0))
        WITH SYNONYMS = ('净收入', '净销售额')
        COMMENT = '实付扣除快照内累计退款,按原订单结算周归属'
)
COMMENT = '订单收入分析Semantic View'
AI_SQL_GENERATION =
    '问净收入用 orders.net_revenue,结算周用 orders.settlement_week。区域默认取 customers.sales_region,问到成交时归属才用 customer_history.region_at_settlement。含义不明确时先澄清。只查询已声明的指标和维度。'
AI_QUESTION_CATEGORIZATION =
    '订单净收入及结算周趋势归入本视图。退款现金流、确认收入和总账问题不属于本视图。';

这些子句分为两类。COMMENT、SYNONYMS、AI_SQL_GENERATION 和 AI_QUESTION_CATEGORIZATION 用于帮助模型选择对象,不会进入展开后的 SQL;它们写错时,风险在于对象选择偏离预期。其余子句决定查询执行。

  • METRICS 的表达式就是展开后的聚合表达式,退款怎么扣、空值怎么处理由它决定。
  • RELATIONSHIPS 决定连接图,每条关系自带连接类型:order_to_customer 固定为 INNER(每单必有客户),order_to_region_at_settlement 固定为 LEFT(归属历史缺失的订单保留)。在定义里固定了连接类型,就不再受会话变量影响。
  • BETWEEN … EXCLUSIVE 声明时态匹配;展开后对应 o.settled_at >= h.valid_from AND o.settled_at < h.valid_to。“成交时属于哪个区域”因此成为可选维度,无需每次手写历史表查询。
  • PRIMARY KEY 和 DISTINCT RANGE 是连接基数的前提:当前区域一单恰匹配一行,历史区域至多一行。两者都只是声明,引擎不会扫描底表去证明;数据是否满足,要靠第 5 节的匹配数检查。

图 1A 展示同一笔订单如何按这套定义进入结果:实付 100、累计退款 20,计入第 2 个结算周和客户当前区域“华东”,金额为 80。

从 Context 到可检查 SQL:Data Agent 的语义编译链-zh

图 1A|同一笔订单如何按周报口径计入结果。

后续复用不需要改动定义:查询华南时只替换过滤值;按成交时区域统计时只替换维度。

3. 从语义查询到结果的四步执行

模型提交语义查询后,后续步骤由引擎处理。图 2 左侧是概率映射;从 SEMANTIC_VIEW() 开始,右侧各步骤按已声明的对象执行。

从 Context 到可检查 SQL:Data Agent 的语义编译链-zh

图 2|模型选择语义对象,数据库完成绑定、展开与执行。

3.1 对象绑定

每个名称都解析到视图中已声明的对象;无法解析时,查询报错并停止执行。生成的 SQL 可能使用一个确实存在的列名,却得到错误的业务结果;语义查询则将风险收敛在“选了哪个对象”这一层。

3.2 SQL 展开

引擎将 SEMANTIC_VIEW() 内联为基表 SQL:指标表达式成为聚合列,维度表达式成为分组键,关系成为连接条件。EXPLAIN INLINE 输出的就是这一步的产物,标识符带引号,可直接执行:

sql
-- EXPLAIN INLINE 输出形态(示意,按文档格式手推)
SELECT `order_semantics`.`sales_region`,
       `order_semantics`.`settlement_week`,
       `order_semantics`.`net_revenue`
FROM (
    SELECT `customers`.`region`                                         AS `sales_region`,
           DATE_TRUNC('week', `orders`.`settled_at`)                    AS `settlement_week`,
           SUM(`orders`.`paid_amount` - COALESCE(`orders`.`refund_amount`, 0)) AS `net_revenue`
    FROM `sales`.`fact_orders` AS `orders`
    INNER JOIN `sales`.`dim_customer` AS `customers`
        ON `orders`.`customer_id` = `customers`.`customer_id`
    WHERE `customers`.`region` = '华东'
      AND DATE_TRUNC('week', `orders`.`settled_at`) >= DAYS_SUB(DATE_TRUNC('week', CURRENT_DATE()), 112)
      AND DATE_TRUNC('week', `orders`.`settled_at`) <  DATE_TRUNC('week', CURRENT_DATE())
    GROUP BY 1, 2
) `order_semantics`;

拿到展开 SQL 后,可核对四项:聚合表达式是否扣除退款;分组键使用 settled_at 还是 created_at;连接类型与条件是否符合定义;以及未引用历史维度时,customer_history 是否已被 enable_semantic_view_table_pruning 裁掉。裁掉 LEFT JOIN 不改变结果;INNER JOIN 可能丢行,因此由 enable_semantic_view_table_pruning_on_inner_join 单独控制。

展开的输入包括语义查询、视图定义和会话变量(enable_semantic_view_inner_join 决定未声明连接类型的关系使用 INNER 还是 LEFT、pruning 变量、time_zone),输出为 SQL。本例中的关系已声明连接类型,因此第一个变量不会改变结果。展开 SQL 也可经 inline REST 接口取得,并在出报表时一并留存。

3.3 权限控制

区域经理只获准查看华东数据,改写查询也不能访问华南。Context 限制模型可见的对象,PRIVATE 声明记录可见性意图;接入执行路径的授权负责限制实际查询。行级策略可以挂在基表上,也可以挂在 Semantic View 暴露的列上;经 SEMANTIC_VIEW() 查询时,两处策略都会生效:

sql
-- 策略挂在Semantic View暴露的区域列上(示意)
CREATE ROW ACCESS POLICY region_scope AS (r STRING) RETURNS BOOLEAN
    -> is_role_in_session('hq_analyst')
       OR (is_role_in_session('east_manager') AND r = '华东');
ALTER TABLE sales.order_semantics
    ADD ROW ACCESS POLICY region_scope ON (customers__sales_region);
从 Context 到可检查 SQL:Data Agent 的语义编译链-zh

图 3|接入查询路径的规则会参与执行;仅保存的声明暂不约束查询。

引擎的结果缓存将用户和角色写入缓存键,命中时重新检查权限,因此引擎层不会读取他人的结果。图 3 底部的提醒针对引擎之外的报表层缓存,这一层需要以不同账号进行实际验证。

3.4 优化与执行

CBO 决定连接顺序和物理算子,影响执行耗时,不改变语义。回溯时保存展开 SQL 即可,无需保存执行计划。


4. 交付:引擎之外的两步

引擎返回的只有有订单的那些周。用户要的是最近 16 个结算周连续排列、无订单的周记 0,这由 MirrorPilot 在语义查询外面再套一层查询完成:

先生成 16 个周一的日期序列,再把语义查询结果左连上去,没匹配的周填 0。补 0 不进指标定义,否则会影响所有复用它的查询。外层查询不经过语义视图,引擎也不检查它:指标名写错,绑定会报错;行数不是 16,引擎不会有任何提示。所以行数检查要作为交付前的固定步骤,由流程保证。

补 0 还有前提:调用者有权限看这个区域,且订单和退款数据都已到齐。没有权限应答不可访问,数据未齐应答待更新,不能也显示为 0。

第二步是存档。回溯要用的材料大多只在交付那一刻拿得到:会话变量会改,视图会被 REPLACE,快照会滚动,策略会调整。事后再凑,只能重新算一遍,算不出当时是怎么算的。

所以交付时要打包:语义查询和 Context 切片、视图定义版本(CREATE OR REPLACE 会覆盖,历史版本靠语义目录的 revision)、展开 SQL 原文、会话变量、数据快照标识、用户角色与生效策略、分项查询及结果。

5. 回溯:三个月后的复核

财务拿着周报来问:2025-12-22 那周,周报记 80,Agent 当时答 100,哪个对?

复核分三步。先读记录里的语义查询,选的是 orders.net_revenue,选择层无误。再用记录里的视图版本和会话变量重新 EXPLAIN INLINE,与留存的展开 SQL 逐字比对,一致,定义层无误;不一致则问题在定义层,到此为止。最后在记录里的快照上重跑展开 SQL 得 100,换周报出具时的快照得 80。那 20 元退款是 Agent 交付后才入账的,两个数在各自的数据上都对。处理是和财务约定对账用同一个快照,回答里带上快照标识。

其他差异也按这条路径找。总额对但错了一周,看展开 SQL 的分组键是 settled_at 还是 created_at,以及 time_zone 是否一致;趋势中间断了一周,看外层查询的周序列。

还有一种情况:定义和展开 SQL 都没变,一笔 80 元却算成了 160 元。这是数据违反了定义里声明的前提:PRIMARY KEY 说一个 customer_id 只对应一条客户记录,实际有两条,INNER JOIN 把这笔订单算了两遍。查法是从订单表左连客户表,数每笔订单匹配到几条客户记录,不等于 1 的就是问题订单:大于 1 重复计数,等于 0 会被 INNER JOIN 丢掉。

sql
-- COUNT(c.customer_id) 只数真正匹配上的客户行;COUNT(*) 会把没匹配上的订单也算成 1
SELECT o.order_id, o.customer_id, COUNT(c.customer_id) AS customer_matches
FROM sales.fact_orders AS o
LEFT JOIN sales.dim_customer AS c ON o.customer_id = c.customer_id
GROUP BY o.order_id, o.customer_id
HAVING COUNT(c.customer_id) <> 1;

修正重复的客户记录后回到 80 元。customer_history 同法检查,连接条件换成时间区间。这类检查验证的是定义成立的前提,应当定期跑,不该等出了差异才跑。

归因同理。Agent 当时说“收入下降源于退款增加”,回溯时用相同区域、结算周和快照分别汇总实付和累计退款,两周实付相同、本周退款多 20 元,这句话才成立。所以记录里要留分项查询和结果,归因才能重跑。

6. 查询链路中每一层的产物

层级

确定性产物

出错方式

检查方式

回溯留存内容

选择(模型)

语义查询文本

选错已注册对象

逐字复核

Context 切片、澄清记录、语义查询

定义(Semantic View)

指标、维度、关系、连接类型

表达式或关系写错

对照展开 SQL

视图定义版本

绑定

通过 / 报错

名称不存在

引擎强制

—

展开

可执行的基表 SQL

会话变量改变连接或裁剪

EXPLAIN INLINE 比对

展开 SQL、会话变量

授权

过滤后的行集

策略未接入执行路径

换身份实际查询

用户、角色、策略版本

补全(外层 SQL)

16 行连续周

空周缺行

行数检查(流程约束)

外层 SQL

数据

满足声明前提的底表

退款后补、重复或缺失匹配

同快照重跑;匹配数检查

快照标识

Semantic View 不能替代定义维护、数据质量检查或业务复核;它将选择、定义、绑定、展开、授权和数据问题分别留下可检查的产物,便于定位差异的来源。