MCP Server 使用说明

步骤 1：编写 YAML 文件

每个 YAML 文件描述一张表，放到 models/ 目录下：

# models/orders.yaml
---
semantic_model:
  name: orders
  db_table: dw.orders
  defaults:
    agg_time_dimension: order_date

  entities:
    - name: order_id
      type: primary
      expr: order_id

  dimensions:
    - name: order_date
      type: time
      type_params:
        time_granularity: day
    - name: channel
      type: categorical

  measures:
    - name: total_amount
      agg: sum
      expr: amount
    - name: order_count
      agg: count
      expr: order_id

步骤 2：定义时间配置

创建 project.yaml 指定日历表，用于计算同比、环比等时间指标：

# models/project.yaml
---
time_config:
  calendar:
    - table: dw.dim_date
      column: date_id
      grain: day

步骤 3：验证并提交

1. 在 WebUI 中单击验证，检查模型是否正确。系统自动检查表是否存在、列名是否正确、实体和维度是否完整。

2. 确认无误后单击提交使模型生效。

3. 使用 list_metrics 查看可用指标，使用 query_metric 查询数据。

时间粒度

示例

dimensions:
  - name: order_date               # 时间维度（按天）
    type: time
    type_params:
      time_granularity: day

  - name: order_month              # 同一列，按月粒度
    type: time
    type_params:
      time_granularity: month
    expr: order_date

  - name: channel                  # 分类维度
    type: categorical
    expr: channel

  - name: status_label             # 带 SQL 表达式
    type: categorical
    expr: concat(status, '_', channel)

维度支持使用 substring、concat、coalesce、cast 等标准 SQL 函数作为表达式。

同一列作为不同粒度的维度

一张日期列可以同时定义 day、week、month 三个维度，只需为每个粒度创建一个时间维度并指向同一列：

dimensions:
  - name: order_date
    type: time
    type_params:
      time_granularity: day
    expr: order_date

  - name: order_week
    type: time
    type_params:
      time_granularity: week
    expr: order_date        # 同一列

  - name: order_month
    type: time
    type_params:
      time_granularity: month
    expr: order_date        # 同一列

使用 SQL 表达式

当列名不够直观或需要计算字段时，可以使用 SQL 表达式。支持 substring、concat、coalesce、cast 等标准 SQL 函数。这些表达式在物理校验时会被自动识别并跳过列名校验。

dimensions:
  - name: user_label
    type: categorical
    expr: concat(level, '_', city)  # 拼接字段

entities:
  - name: user_short_id
    type: foreign
    expr: substring(trace_id FROM 1 FOR 8)  # 截取

measures:
  - name: net_amount
    agg: sum
    expr: coalesce(amount, 0) - coalesce(discount, 0)  # 计算字段

分区表

如果表有分区列，可以通过 is_partition: true 标记分区维度：

dimensions:
  - name: ds
    type: time
    type_params:
      time_granularity: day
    is_partition: true              # 标记为分区列
    expr: ds

隐藏内部度量

有些度量只想作为中间计算使用，不想对终端用户暴露。设置 create_metric: false 即可隐藏：

measures:
  - name: total_amount            # 公开指标
    agg: sum
    expr: amount

  - name: _raw_count              # 不暴露为指标
    agg: count
    expr: order_id
    create_metric: false

比率指标

# models/conversion_rate.yaml
---
metric:
  name: order_conversion_rate
  description: "订单转化率：下单数 / 访问数"
  type: ratio
  type_params:
    numerator: order_count
    denominator: visit_count

派生指标

# models/revenue_growth.yaml
---
metric:
  name: revenue_growth
  description: "收入环比增长率"
  type: derived
  type_params:
    expr: (current_revenue - prev_revenue) / prev_revenue
    metrics:
      - name: total_amount
        alias: current_revenue
      - name: total_amount
        alias: prev_revenue
        offset_window: 1 month

累积指标

# models/weekly_sales.yaml
---
metric:
  name: weekly_sales
  description: "近 7 天销售额"
  type: cumulative
  type_params:
    measure:
      name: total_amount
    window: 7 days

转化指标

# models/order_conversion.yaml
---
metric:
  name: visit_to_order_conversion
  description: "从访问到下单的转化率"
  type: conversion
  type_params:
    conversion_type_params:
      base_measure:
        name: visit_count
      conversion_measure:
        name: order_count
      entity: user
      calculation: conversion_rate

过滤器

可以在度量或指标定义中添加 SQL 过滤条件，在聚合计算前应用。

# 度量级过滤：只计算已完成状态的订单总额
measures:
  - name: completed_amount
    agg: sum
    expr: amount
    filter: {{ render_dimension_template('status') }} = 'completed'

过滤器语法：使用 {{ Dimension('name') }} 引用维度，使用 {{ Entity('name') }} 引用实体，后跟 SQL 条件。

预定义查询

将常用的指标、分组和筛选组合保存为查询模板，用户可直接调用。

# models/weekly_report.yaml
---
saved_query:
  name: weekly_revenue_report
  description: "周度收入报告"
  query_params:
    metrics:
      - total_amount
      - order_count
    group_by:
      - order_id__order_week
      - order_id__channel
    order_by:
      - "-order_id__order_week"
    limit: 52

维度引用格式为 实体名__维度名（双下划线连接）。

空值填充与时间轴对齐

metric:
  name: daily_orders
  type: simple
  type_params:
    measure:
      name: order_count
    fill_nulls_with: 0          # 无数据日期显示 0
    join_to_timespine: true    # 对齐到时间轴，补全无数据日期

非加性度量与缓慢变化维度

有些度量不能简单求和（如库存量、账户余额），需要在特定维度下取快照值。通过 non_additive_dimension 指定非加性维度和窗口选择方式：

# 非加性度量：库存量（取月末快照）
measures:
  - name: monthly_inventory
    description: "月末库存量"
    agg: sum
    expr: inventory_count
    non_additive_dimension:
      name: snapshot_date       # 非加性维度
      window_choice: max        # 取时间窗口内的最大值
      window_groupings:
        - product                # 按产品分组取快照

缓慢变化维度（SCD Type II）：当维度表有生效时间范围时，可以标记开始和结束时间维度：

# 维度表中标记 SCD Type II
dimensions:
  - name: valid_from
    description: "生效开始时间"
    type: time
    type_params:
      time_granularity: day
      validity_params:
        is_start: true              # 标记为开始时间

  - name: valid_to
    description: "生效结束时间"
    type: time
    type_params:
      time_granularity: day
      validity_params:
        is_end: true                # 标记为结束时间

原生表引用格式

除了 db_table 简写，也支持 MetricFlow 原生的 node_relation 格式，支持三段式目录引用：

# 两段式：库名.表名
node_relation:
  schema_name: dw
  alias: orders

# 三段式：目录.库名.表名
node_relation:
  database: catalog
  schema_name: dw
  alias: orders

# db_table 同样支持三段式
db_table: catalog.dw.orders

累积指标聚合方式

累积指标支持三种 period_agg 模式，控制在时间窗口内的聚合行为：

metric:
  name: end_of_week_inventory
  type: cumulative
  type_params:
    cumulative_type_params:
      measure:
        name: inventory_count
      window: 7 days
      period_agg: last       # 取窗口内最后一天的值（默认）

      # period_agg: average  # 窗口内每日均值
      # period_agg: first    # 窗口内第一天的值

转化指标固定属性

在转化指标中，可以用 constant_properties 指定在不同事件间保持不变的属性：

# 按"渠道"维度分析转化，要求渠道在两次事件间不变
metric:
  name: visit_to_order_by_source
  type: conversion
  type_params:
    conversion_type_params:
      base_measure:
        name: visit_count
      conversion_measure:
        name: order_count
      entity: user
      constant_properties:
        - base_property: order_id__channel    # 基础事件的属性
          conversion_property: order_id__channel # 转化事件的属性（必须相同）

指标时间粒度与偏移粒度

指标级 time_granularity：可以在指标定义中直接指定时间粒度，覆盖查询时的默认行为：

metric:
  name: monthly_revenue
  type: simple
  time_granularity: month     # 指定此指标默认按月聚合
  type_params:
    measure:
      name: total_amount

offset_to_grain：在派生指标中，将偏移对齐到指定粒度（而非默认的天级别）：

metric:
  name: yoy_growth
  type: derived
  type_params:
    expr: (current - prev) / prev
    metrics:
      - name: total_amount
        alias: current
      - name: total_amount
        alias: prev
        offset_window: 1 year
        offset_to_grain: month    # 偏移到月粒度（而非天）

实体角色

同一个实体在表中可能有多个角色。例如订单表里的 user_id 既是"买家"也是"推荐人"。通过 role 区分：

entities:
  - name: user
    type: foreign
    expr: buyer_id
    role: buyer              # 此 user 实体的角色是"买家"

  - name: user
    type: foreign
    expr: referrer_id
    role: referrer           # 此 user 实体的角色是"推荐人"

不指定 role 时，默认角色等同于实体名。

工作空间概述

工作空间是语义模型的隔离容器。每个工作空间拥有独立的模型文件、指标列表、查询引擎实例和数据库连接池。工作空间 A 的指标对工作空间 B 完全不可见。

工作空间有三种运行状态：

Active Store 与 Staging Store

每个工作空间内部有两层存储：

• Active Store（已生效）：已提交并加载的模型，查询引擎使用此版本，文件只读。

• Staging Store（待提交）：用户上传或编辑的待定变更，验证通过后提交进入 Active Store。

更新流程

1. 上传或编辑 YAML：文件进入 Staging Store，不影响正在运行的查询。

2. 验证：系统自动检查表存在性、列名正确性、YAML 语法、命名规范和跨模型重复名。

3. 提交：将 Staging 内容移至 Active Store，系统自动触发引擎重载。

4. 自动重载：后台线程解析新模型、编译清单、更新路由，通常 2~5 秒完成。

权限模型

默认示例工作区

首次启动时，系统会自动创建 example 工作区，包含完整的种子数据：

示例指标包括：total_amount（订单总额）、order_count（订单数）、avg_amount（客单价）、unique_users（独立用户数）来自 orders 模型；user_count（用户数）来自 users 模型。

可在配置中设置 seed_example: false 禁用自动种子。