fetch-data

将用户的数据分析问题转为结构化意图，并补全取数所需完整语义上下文，生成 NL2SQL prompt 与 SQL，执行后返回查询结果供下游分析。

前置条件

1. 确认用户的数据分析问题明确（要分析什么、大致时间/范围）。
2. 检查 {workdir} 是否已包含全部所需分析数据：
   • 已全部存在 → 直接使用这些文件，结束取数，不执行取数流程。
   • 有缺失 → 继续。

---

取数流程

存储约定：落盘生成 NL2SQL prompt 所必需的产物，以及据此产出的 prompt / SQL 本身。文件命名由各步骤自行决定（建议语义清晰、便于追溯），但目录不能错位。

Step	产物	存储路径	性质
1	结构化问题（含 Step 3 改写后的版本）	{workdir}/steps/	prompt 输入
2.1	指标信息	{workdir}/data/raw/	prompt 输入（语义层 / 上下文）
2.2	数据表元数据	{workdir}/data/raw/	prompt 输入（语义层 / 数据湖仓元数据）
4	NL2SQL prompt	{workdir}/steps/	prompt 产出
5	生成的 SQL	{workdir}/steps/	prompt 下游代码

Step 1. 问题结构化

从用户的自然语言分析问题中抽取字段，结构化产物落盘到 {workdir}/steps/（属于步骤过程产物）。

Schema（缺失字段填 null，不要省略键）：

{
	"question": "<原始用户问题>"	# 用户原始问题
	"domain": "<业务域>",	# 用户问题面向的业务领域/数据来源，如 产品A、产品B 等
	"metrics": [								# 数据分析问题中涉及的关键指标
		"<关键指标1>",							# 如 DAU
		"<关键指标2>"							  # 如日均访问用户数
	],
	"intention": "<分析意图>",		# 用户想要完成的最终分析问题，如“数据在不同端的分布情况”
	"scope": [									# 数据的限定范围，如时间范围、维度等
		"<时间限定>",							# 数据分析针对的时间范畴，如上个月、近3个月等
		"<地域限定>"							  # 数据分析针对的地域范畴，如“中国以及俄罗斯用户”
	]
}

字段	含义	示例
question	原始问题	上个月，中国与俄罗斯用户对某产品的日均访问用户数在各个端的分布情况
domain	业务领域	产品A / 产品B / 产品C
metrics	关键指标	DAU、日均访问用户数、次日访问留存率
intention	最终分析问题	数据在不同端的分布情况
scope	数据限定范围（时间、地域等）	["上个月", "中国以及俄罗斯用户"]

• 用户未提及的字段 → null（scope 中未知项也用 null 占位或省略该元素，保持数组语义清晰）。
• metrics 写法：尽量使用数据分析问题中已存在的标准指标名（如 DAU / 对话用户数 / 次日访问留存率），不要用自由发挥的同义改写，以免造成歧义，导致后续步骤理解出错。

例如，对于用户输入问题「5月 app端某模型对话用户数，人均对话次数和点赞率分别是多少？」，可解析出如下信息：

{
  "question": "5月 app端某模型对话用户数，人均对话次数和点赞率分别是多少？",
  "domain": "产品A",
  "metrics": ["对话用户数", "人均对话次数", "点赞率"],
  "intention": "查询5月app端某模型的三个指标值：对话用户数、人均对话次数和点赞率",
  "scope": [
    "5月",
    "app端",
    "某模型"
  ]
}

Step 2. 业务数据信息补全

将 Step 1 的结构化问题作为输入，从可用知识源补全取数所需的业务语义。本步骤的产物全部落盘到 {workdir}/data/raw/。

知识源优先级（Step 2.1 和 Step 2.2 都遵循）：

1. 语义层——首选。语义层维护了被业务方校准过的指标 / 维度 / 表语义，结果可直接使用。
2. 数据湖仓元数据——语义层缺失或不可用时回退。数据湖仓元数据提供的是表 / 列级别的物理事实（表名、列名、dtype、注释），用它补全 Step 2.2 的字段；对于 Step 2.1 的指标语义，需自行结合列注释 / 命名推断。
3. 上下文信息（如对话历史、用户先前提供的口径说明等）——仅当上述两者都拿不到时才允许使用，并且必须满足下面两条硬约束：
   • 精确对应：上下文里出现的指标名 / 表名 / 列名必须与本次要探查的目标完全一致（同名同义、口径一致），不允许拿"看起来差不多"的旧上下文凑数；
   • 来源标注：在落盘的 JSON 中，每个来自上下文的字段都要在产物文件里以注释 / 同级 source: "context" 字段或同名旁注的方式显式标出，便于 Step 3 复核。

任一字段若三个来源都拿不到，按"留空"处理，不得用模型先验或想象填充。

Step 2.1. 指标信息补全

针对 Step 1 中的关键指标，按上述优先级查询其业务定义与计算口径。若 Step 1 中没有成功获取明确的意向指标，则将分析意图作为指标名进行查询。若分析意图也不存在，则回退使用原问题进行查询。

本步骤所需探查到的信息（每个关键指标至少应得到如下关键字段）：

{
	"metrics": [														# 查询中所需的指标
		{
			"metric_name": "<指标1名称>",				# 语义层中存储的标准指标名
      "synonyms": [									    # 指标的同义词
        "<同义词1>",
        "<同义词2>"
      ],
      "metric_type": "<指标类型>",					# 指标的类型，如 "quantity" / "ratio" / "percentage"
      "is_north_star": true,						# 是否是北极星指标
      "is_display": true,							# 是否在数据分析中展示
			"formulas": [
				{
					"dataset": "<数据表名1>",				# 能够支持指标计算的数据表
					"formula": "<指标计算方式>"				# 在该数据表中，该指标计算方式
				},
				{
					"dataset": "<数据表名2>",
					"formula": "<指标计算方式>"
				}
			]
		}
	]
}

把获取到的指标信息落盘到 {workdir}/data/raw/，不遗漏任何探查到的字段信息；若不存在的字段信息，则补充为空，不可捏造不存在的信息。

Step 2.2. 表元数据补全

针对 Step 2.1 中所有数据表，按上述优先级查询表与列级别的元信息。

本步骤所需探查到的信息（每张数据表至少应得到如下关键字段）：

[
	{
		"table_name": "<table name>",											# 查询相关的表名
		"description": "<description of the table>",			# 表的描述
		"columns": [																			# 表中列的元信息
			{
				"column_name": "<column name>",								# 列名
				"dtype": "<type of data>",										# 列中值的类型
				"description": "<description of the column>",	# 列的描述
        "topline_value": "<topline value for the volumn>",  # 列的 topline 值
        "sample_values": "<samples from the column>"  # 列中的采样数值
			}
		]
	}
]

注意：

• sample_values 仅提供部分采样数值，用于辅助理解列的含义，并非精确取值，请查看实际取值时以实际数据为准。
• 若返回的表元数据被截断，则需查看实际数据表的完整元数据，确保不遗漏任何字段信息。
• 对于不存在的字段信息，则补充为空，不可捏造不存在的信息。

把获取到的数据表的完整表元数据信息落盘到 {workdir}/data/raw/。

Step 2.3. domain 校验

完成指标 / 表元数据补全后，回头检查 Step 1 结构化问题产物中的 domain 字段。domain 必须唯一确定且非空才能进入后续步骤。

逐项核对：

1. 非空：domain 不是 null / 空串 / 占位符。
2. 唯一确定：domain 取值唯一，没有出现"多个业务域并存 / 取值含糊"的情况。可借助 Step 2 探查到的指标 / 表元数据（如表名前缀、schema.json 中各表的 domain 标注）反向印证结构化问题里的 domain 是否自洽。

按校验结果处理：

• 唯一且非空 → 继续 Step 3。若 Step 2 的元数据指向的业务域与结构化问题里的 domain 不一致，按"取值含糊"处理（见下）。
• 为空 / 缺失 → 停下并向用户提问，请其补充本次分析对应的业务域（可结合 Step 2 元数据给出候选域列表供选择），拿到答复后原地写回 Step 1 结构化问题产物的 domain 字段，并在回复正文中记录该补充。不要替用户臆测 domain。
• 取值含糊 / 多域并存 → 同样停下向用户确认唯一业务域，确认后写回 domain。

domain 校验通过是进入后续步骤的前置条件；domain 仍为空时不得继续往下走。

Step 3. 歧义消除

Step 2 完成后，先停下来对照原始问题与新得到的指标信息 / 表元数据核一遍：用户的指标 / 维度 / 时间口径在补全后的数据语义里是否还存在多解或其他理解偏差。有歧义就先消除，再进入 Step 4。本过程严格遵循搜索到的数据，不可捏造不存在的信息。

输入：Step 1 的结构化问题 + Step 2.1 的指标信息 + Step 2.2 的表元数据 + 原始问题 产物：

• 消歧结论在回复正文中说明（即便“无歧义”也要写），不落盘
• 必要时原地改写 Step 1 在 {workdir}/steps/ 下的结构化问题产物：把模糊词替换成确认后的标准 metric_name / <列名>=<值> 形式（改写的原值 / 新值在回复正文中说明）

Step 3.1. 分析意图歧义消除

常见分析意图歧义模式与解决方案：参见 references/intent_ambiguity.md。逐项检查：

1. 指标指向不明

用结构化问题中 metrics 里的每一项分析指标去和 Step 2.1 探查到的指标信息中的可用指标对比。若多条指标可对应同一分析指标（如“留存率”同时命中“访问留存率”、“使用留存率”）→ 有歧义。

• 若存在歧义，则抛出问题以及待确定的选项（即，所有可用指标），让用户确认。
• 若用户确认后，则将确认后的标准 metric_name 写回 Step 1 的结构化问题产物。
• 写回后检查该 metric_name 是否已存在于 Step 2.1 现有产物中；若不存在（改名 / 切换到新指标），则按 Step 2.1 的指标信息补全步骤重新执行指标信息补全（并按 Step 2.2 补齐新指标所需的表元数据），详见 Step 3.3 的联动说明。

2. 指标聚合粒度不明

对每个已能对齐到标准 metric_name 的指标，检查 Step 2.1 现有产物中是否存在某个 metric_name 所需聚合粒度不明（如“一段时间的对话用户数”同时命中“日均对话用户数”“时段总和对话用户数”），且原始问题未明确选择哪一种 → 有歧义。

• 参考 references/intent_ambiguity.md 章节 2 中的默认解决方案。
• 若问题不被覆盖，则抛出问题以及待确定的选项（即，所有可用聚合粒度），让用户确认。
• 若指标明确/用户确认后，查看指标信息是否已获取；若无，则按 Step 2.1 的指标信息补全步骤，重新执行指标信息补全。

Step 3.2. 数据来源歧义消除

常见数据来源歧义模式与解决方案：参见 references/data_source_ambiguity.md。逐项检查：

1. 数据表来源不明

数据中多个数据表在指标计算、数据维度选择等都满足数据分析需求。例如，分析“计算某产品不同端 dau 指标”，表 xxx_index 和 xxx_distribution 都包含可用于计算 dau 指标都数据，且包含指向不同端的字段，即两张表都可用于数据分析。

• 参考 references/data_source_ambiguity.md 章节 1 中的解决方法。
• 若问题不被覆盖，则抛出问题以及待确定的选项（即，所有可用数据表），让用户确认。
• 若数据表明确/用户确认后，查看数据表元数据是否已获取；若无，则按 Step 2.2 的表元数据补全步骤，重新执行表元数据补全。

2. 数据维度指向不明

数据中多个维度可用于数据筛选。例如，分析“文本对话的点赞率”，“对话模式”和“对话类型”两个维度都包含“文本对话”的维度取值。用结构化问题中 scope 里每一项数据维度去和 Step 2.2 探查到的表元数据中的可用维度对比。若多列都能取到该值（如“文本对话”既在 dialog_mode 也在 dialog_type 里出现）→ 有歧义。

• 若存在歧义，则抛出问题以及待确定的选项（即，所有可用维度），让用户确认。

上述只是最常见的情况，遇到其他模糊（如时间口径——“近 30 天”含不含今天、“上月”按自然月还是滚动 30 天；如统计口径——“用户数”是 visit_usercnt 还是 visit_login_usercnt）也要在本步骤一并提出。

Step 3.3. 消歧结论

无论是否触发消歧，都要在回复正文中说明以下内容：

• 检查结果
  • 指标歧义：<无 | 逐条列出每个模糊指标命中的候选清单>
  • 粒度歧义：<无 | 按默认（写明默认值与场景，如“统计值=日均”“环比基础数据=日均均值”“基于用户数的比例=每日比例的日均值”“基于次数/时长的比例=时段求和后相除”）| 逐条列出每个模糊指标命中的候选 metric_name / formula>
  • 维度歧义：<无 | 逐条列出每个模糊维度命中的候选清单>
  • 数据表来源：<单一可用表，无需选择 | 候选表清单 + 最终选定表（组合）+ 选定理由（满足需求 / 描述更贴合 / 最准确计算指标·非代理指标 / 概览表兜底）>
  • 其他：<无 | 描述时间口径 / 统计口径等其他模糊>
• 用户确认 / 默认：<原模糊项> → <最终选择>（例：留存率 → 访问留存率；对话用户数 → 日均对话用户数（按默认）；文本对话 → dialog_mode=文本对话）
• 对结构化问题的修改：<字段路径> 从 <旧值> 改为 <新值>；若无修改写“无”

联动：出现下列任一情况，都意味着 Step 2 的指标信息 / 表元数据可能缺失对应元数据 → 回到 Step 2 重新拉，再进入 Step 4：

• 消歧后写回的 metric_name 未出现在 Step 2.1 现有产物中（无论是改名、新增还是切换聚合粒度）；
• 消歧后选定的数据表（组合）未出现在 Step 2.2 现有产物中，或其在 Step 2.1 指标 formulas 里缺少对应 dataset 的计算口径（换表 / 新增表场景）。

若写回的 metric_name 已存在于 Step 2.1 现有产物中（包括 1.2 聚合粒度消歧切到同一指标的另一个聚合粒度版本），且选定数据表的元数据与指标口径均已齐备，则无需重跑 Step 2。

Step 4. NL2SQL Prompt 生成

使用 {skill-dir}/scripts/generate_nl2sql_prompt.py 将 Step 2 探查到的指标信息和表元数据信息渲染成 NL2SQL prompt，落盘到 {workdir}/steps/：

python {skill-dir}/scripts/generate_nl2sql_prompt.py \
  --problem <{workdir}/steps/ 下 Step 1 结构化问题产物路径> \
  --metrics <{workdir}/data/raw/ 下 Step 2.1 指标信息产物路径> \
  --schema  <{workdir}/data/raw/ 下 Step 2.2 表元数据产物路径> \
  --output  <{workdir}/steps/ 下的输出路径>

参数说明

参数	含义	默认值
--problem	问题结构化 JSON 路径（Step 1 的产物，位于 {workdir}/steps/；Step 3 可能就地改写过）	必填
--metrics	关键分析指标信息 JSON 路径（Step 2.1 的产物，位于 {workdir}/data/raw/）	必填
--schema	相关数据表元数据信息 JSON 路径（Step 2.2 的产物，位于 {workdir}/data/raw/）	必填
--output	NL2SQL prompt 输出路径（须位于 {workdir}/steps/ 下）	必填

• 产出的 NL2SQL prompt 供 Step 5 整段交给 LLM。

Step 5: SQL 生成

1. 读取 Step 4 在 {workdir}/steps/ 下产出的 NL2SQL prompt 的完整内容，不允许对其内容做更改。
2. 把它整段作为 prompt 交给当前模型（不要节选、不要总结、不要在前面加额外指令）。
3. 查看 references/partition-query.md 中的分区与查询策略，根据表后缀确定分区字段和 WHERE 写法，结合表类型确定查询范围。
4. 模型必须只输出一条可执行 SELECT。
5. 从模型回复中只截取 SQL 主体（去掉 sql 代码围栏、Markdown 注释、解释段），保存到 {workdir}/steps/ 下（以 ; 结尾）。
6. 不要二次改写 SQL；如果模型输出多条语句，回到 Step 4 检查 prompt，不要手工拼接。

Step 6: 执行 SQL 并返回结果

通过数据湖仓执行 Step 5 产出的 SQL。执行结果按下述规则处理：

1. 执行成功，拿到非空行 → 返回结果，保存至本地 CSV 文件；若返回结果被截断，则通过下载数据文件的方式保存到本地。
2. 执行成功，但返回空结果集 → 不要假装成功。按下列顺序排查：
   • 回到 Step 1，检查 scope（特别是日期）/ metrics 是否对齐；
   • 回到 Step 3，检查是否漏过歧义——例如指标 / 维度选错列；
   • 回到 Step 5，检查 SQL 的过滤条件；
   • 之后重跑 Step 2–6（若 Step 3 改写了 metrics 名单则必须重跑 Step 2，否则可从 Step 4 起跑）。
3. 执行错误，错误返回 → 把 error 信息透传回去做迭代：SQL 语法 / 列不存在 / 类型不匹配等 → 回到 Step 5；表 / 列名查不到 → 回到 Step 2 重新拉表元数据。不要绕过数据湖仓的标准执行通道（如改走 shell / psql 自行取数），那样拿到的结果既不可复现也无法被评测器审计。