Files

T

tao.chen 2f406bd64d update by wensicheng on 0629

2026-07-01 17:46:08 +08:00

3.7 KiB

Raw Blame History

name, description

name	description
sql-context-builder	当逻辑计划已经完成，需要固定 SQL 生成和 SQL review 共同依赖的 alias、字段来源、join key、指标、维度、过滤、时间窗口、事实表/维表上下文时使用。消费 logic_plan 和 validation_result，不写 SQL，不调用 MCP。

SQL Context Builder（SQL 上下文构建）

目标

把 SQL 生成时可能被临时猜测的内容提前固定下来。下游只能使用本 skill 输出的 alias、字段、join、指标、过滤、时间窗口和输出列。

输入

logic_plan:
  status: PLANNED
validation_result:
  status: VALIDATED
  field_mapping: {}
  joins: []

工作顺序

给每张表分配唯一、稳定、短小的 alias。
标记事实表、维表、码表和目标表。
把每个业务字段解析成 alias.column。
固定 join 谓词、join 类型和基数假设。
固定指标表达式、维度字段、时间字段、分区字段和过滤字段。
固定时间窗口 SQL 片段，尤其是 T-1 完整日边界。
固定输出列顺序和别名。
检查 logic plan 中引用的字段都能在 context 中找到。
对派生字段记录来源步骤和依赖字段。

时间窗口上下文

当存在时间过滤时，必须输出 time_windows。对“近 N 天按 T-1 完整日”：

time_windows:
  - name: t_minus_1_complete_days
    event_field: fl.login_time
    lower_bound_sql: date_sub(current_date(), N)
    upper_bound_sql: current_date()
    predicate_sql: fl.login_time >= date_sub(current_date(), N) AND fl.login_time < current_date()
    boundary: left_closed_right_open

下游 SQL 必须复用 predicate_sql，不得临时改成 BETWEEN。

转化指标上下文

转化率必须固定分母、分子和顺序约束：

metrics:
  - name: conversion_rate
    numerator: converted_user_cnt
    denominator: new_user_cnt
    order_constraint: pay_time >= register_time
    null_policy: denominator_zero_returns_0
    exists_after_anchor_event: true

输出格式

sql_context:
  status: CONTEXT_READY | NEED_USER_CONFIRMATION
  aliases:
    - alias: fl
      table: user_login
      role: fact | dimension | lookup | target
      source_file: "元数据来源"
  fields:
    - id: fl.user_id
      alias: fl
      table: user_login
      column: user_id
      type: bigint
      role: [join_key, metric]
      nullable: false
      source_file: "元数据来源"
  joins:
    - left: fl.user_id
      right: ur.user_id
      type: left
      cardinality: "N:1"
      source_step: S3
  time_windows: []
  metrics: []
  dimensions: []
  filters: []
  outputs: []
  write_intent:
    mode: query_only | insert_into | insert_overwrite
    target_table: "可为空"
    overwrite_confirmed: false
  unresolved: []

用户可见摘要

除了 YAML，必须输出：

## SQL 上下文
### 表别名
| Alias | 表名 | 角色 |
|---|---|---|

### 字段来源
| 字段 | 来源 | 用途 |
|---|---|---|

### Join 关系
| 左字段 | 右字段 | 类型 | 基数风险 |
|---|---|---|---|

### 指标公式
| 指标 | 分子 | 分母 | 空值策略 |
|---|---|---|---|

### 时间窗口
| 字段 | 下界 | 上界 | 边界 |
|---|---|---|---|

规则

alias 一旦生成，下游不能重新命名。
context 中不存在的字段，下游视为不存在。
join key 只能来自元数据校验和逻辑计划。
指标表达式必须能追溯到 logic plan 的 aggregate 步骤。
输出列必须来自 fields、metrics 或明确派生字段。
如果 SQL 生成需要新字段，回到 metadata-validator 或 logic-planner。

停止条件

只在 alias、字段、join、指标、时间字段、过滤字段、输出列和写入意图都完整时输出 CONTEXT_READY。

3.7 KiB Raw Blame History Unescape Escape