141 lines
3.7 KiB
Markdown
141 lines
3.7 KiB
Markdown
---
|
||
name: sql-context-builder
|
||
description: 当逻辑计划已经完成，需要固定 SQL 生成和 SQL review 共同依赖的 alias、字段来源、join key、指标、维度、过滤、时间窗口、事实表/维表上下文时使用。消费 logic_plan 和 validation_result，不写 SQL，不调用 MCP。
|
||
---
|
||
|
||
# SQL Context Builder（SQL 上下文构建）
|
||
|
||
## 目标
|
||
|
||
把 SQL 生成时可能被临时猜测的内容提前固定下来。下游只能使用本 skill 输出的 alias、字段、join、指标、过滤、时间窗口和输出列。
|
||
|
||
## 输入
|
||
|
||
```yaml
|
||
logic_plan:
|
||
status: PLANNED
|
||
validation_result:
|
||
status: VALIDATED
|
||
field_mapping: {}
|
||
joins: []
|
||
```
|
||
|
||
## 工作顺序
|
||
|
||
1. 给每张表分配唯一、稳定、短小的 alias。
|
||
2. 标记事实表、维表、码表和目标表。
|
||
3. 把每个业务字段解析成 `alias.column`。
|
||
4. 固定 join 谓词、join 类型和基数假设。
|
||
5. 固定指标表达式、维度字段、时间字段、分区字段和过滤字段。
|
||
6. 固定时间窗口 SQL 片段，尤其是 T-1 完整日边界。
|
||
7. 固定输出列顺序和别名。
|
||
8. 检查 logic plan 中引用的字段都能在 context 中找到。
|
||
9. 对派生字段记录来源步骤和依赖字段。
|
||
|
||
## 时间窗口上下文
|
||
|
||
当存在时间过滤时，必须输出 `time_windows`。对“近 N 天按 T-1 完整日”：
|
||
|
||
```yaml
|
||
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`。
|
||
|
||
## 转化指标上下文
|
||
|
||
转化率必须固定分母、分子和顺序约束：
|
||
|
||
```yaml
|
||
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
|
||
```
|
||
|
||
## 输出格式
|
||
|
||
```yaml
|
||
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，必须输出：
|
||
|
||
```markdown
|
||
## SQL 上下文
|
||
### 表别名
|
||
| Alias | 表名 | 角色 |
|
||
|---|---|---|
|
||
|
||
### 字段来源
|
||
| 字段 | 来源 | 用途 |
|
||
|---|---|---|
|
||
|
||
### Join 关系
|
||
| 左字段 | 右字段 | 类型 | 基数风险 |
|
||
|---|---|---|---|
|
||
|
||
### 指标公式
|
||
| 指标 | 分子 | 分母 | 空值策略 |
|
||
|---|---|---|---|
|
||
|
||
### 时间窗口
|
||
| 字段 | 下界 | 上界 | 边界 |
|
||
|---|---|---|---|
|
||
```
|
||
|
||
## 规则
|
||
|
||
- alias 一旦生成，下游不能重新命名。
|
||
- context 中不存在的字段，下游视为不存在。
|
||
- join key 只能来自元数据校验和逻辑计划。
|
||
- 指标表达式必须能追溯到 logic plan 的 aggregate 步骤。
|
||
- 输出列必须来自 `fields`、`metrics` 或明确派生字段。
|
||
- 如果 SQL 生成需要新字段，回到 metadata-validator 或 logic-planner。
|
||
|
||
## 停止条件
|
||
|
||
只在 alias、字段、join、指标、时间字段、过滤字段、输出列和写入意图都完整时输出 `CONTEXT_READY`。
|