语义模型生成指南¶

概览¶

语义模型生成功能帮助你通过 AI 助手从数据库表创建 MetricFlow 语义模型。助手分析你的表结构并生成全面的 YAML 配置文件，定义指标、维度和关系。

什么是语义模型？¶

语义模型是定义以下内容的 YAML 配置：

度量（Measures）：指标和聚合（SUM、COUNT、AVERAGE 等）
维度（Dimensions）：分类和时间属性
标识符（Identifiers）：用于关系的主键和外键
数据源（Data Source）：与数据库表的连接

工作原理¶

使用 datus --datasource <datasource> 启动 Datus CLI，然后使用子代理命令：

  /gen_semantic_model generate a semantic model for table <table_name>

交互式生成¶

当你请求语义模型时，AI 助手会：

检索你的表的 DDL（结构）
检查是否已存在语义模型
生成全面的 YAML 文件
使用 MetricFlow 验证配置
验证通过后同步到知识库

生成工作流¶

用户请求 → DDL 分析 → YAML 生成 → 验证 → 存储

验证和同步¶

发布前，agent 会调用 validate_semantic()。如果验证失败，会修改 YAML 并重试；验证通过后，end_semantic_model_generation 会自动把语义模型同步到知识库。

配置¶

大部分配置是内置的。在 agent.yml 中，最小化设置即可：

agent:
  services:
    semantic_layer:
      metricflow: {}     # key 必须等于 adapter type（例如 `metricflow`）。
                         # 如果同时写了 `type:` 字段，必须与 key 一致，否则 Datus 会在启动时抛出配置错误。

  agentic_nodes:
    gen_semantic_model:
      model: claude      # 可选：默认使用已配置的模型
      max_turns: 30      # 可选：默认为 30
      semantic_adapter: metricflow   # 当仅配置了一个 semantic layer 时可省略

完整配置项见语义层配置。

内置配置（自动启用）： - 工具：数据库工具、生成工具和文件系统工具 - Hooks：验证证据记录和知识库同步 - MCP 服务器：MetricFlow 验证服务器 - 系统提示：内置模板；未显式设置 prompt_version 时使用最新可用版本 - 工作空间：~/.datus/data/{datasource}/semantic_models

语义模型结构¶

基本模板¶

data_source:
  name: table_name                    # 必需：小写加下划线
  description: "Table description"

  sql_table: schema.table_name        # 对于有 schema 的数据库
  # OR
  sql_query: |                        # 对于自定义查询
    SELECT * FROM table_name

  measures:
    - name: total_amount              # 必需
      agg: SUM                        # 必需：SUM|COUNT|AVERAGE|etc.
      expr: amount_column             # 列或 SQL 表达式
      create_metric: true             # 自动创建可查询指标
      description: "Total transaction amount"

  dimensions:
    - name: created_date
      type: TIME                      # 必需：TIME|CATEGORICAL
      type_params:
        is_primary: true              # 需要一个主时间维度
        time_granularity: DAY         # TIME 必需：DAY|WEEK|MONTH|etc.

    - name: status
      type: CATEGORICAL
      description: "Order status"

  identifiers:
    - name: order_id
      type: PRIMARY                   # PRIMARY|FOREIGN|UNIQUE|NATURAL
      expr: order_id

    - name: customer
      type: FOREIGN
      expr: customer_id

总结¶

语义模型生成功能提供：

✓ 从表 DDL 自动生成 YAML
✓ 交互式验证和错误修复
✓ 验证通过后自动同步
✓ 知识库集成
✓ 防止重复
✓ MetricFlow 兼容性