编写第一个模型：从原始表到业务语义

这篇的目标，是把“我有一张表”变成“我有一个可查询、可复用的业务模型”。

1. 建模不是字段映射，而是业务表达

很多人第一次写 Cube 模型时，会把它写成“字段别名表”：

• 数据库叫啥，我就照抄啥；
• 表里有什么字段，我就全部暴露；
• 有个金额字段就直接 sum；
• 有个状态字段就当维度。

这样能跑，但还不是真正的语义层。

Cube 建模更推荐的思路是：

1. 先识别业务实体；
2. 再识别关键指标；
3. 再确定常用维度；
4. 最后定义 join、view、权限和预聚合。

2. 一个最小订单模型

假设底层表是 public.orders，有这些字段：

• id
• customer_id
• amount
• status
• created_at

可以先写成这样：

cubes:
  - name: orders
    sql_table: public.orders

    measures:
      - name: count
        type: count

      - name: total_amount
        sql: amount
        type: sum

    dimensions:
      - name: id
        sql: id
        type: number
        primary_key: true

      - name: customer_id
        sql: customer_id
        type: number

      - name: status
        sql: status
        type: string

      - name: created_at
        sql: created_at
        type: time

3. 这个模型已经解决了什么

它已经把原始表转换成了四类语义：

1）实体

orders

2）指标

• orders.count
• orders.total_amount

3）维度

• orders.status
• orders.created_at

4）键

• orders.id
• orders.customer_id

这样 REST / GraphQL / SQL API 就可以围绕“业务对象”而不是原始表写查询。

4. 第二步：加一个 segment

如果你经常只分析“已完成订单”，可以把过滤逻辑收进模型：

segments:
  - name: completed
    sql: "{CUBE}.status = 'completed'"

它的意义在于：

• 让高频条件有统一定义；
• 减少每个客户端重复写条件；
• 给后续 AI 消费端提供更稳定的语义对象。

5. 第三步：加一个关联实体

例如客户表：

cubes:
  - name: customers
    sql_table: public.customers

    dimensions:
      - name: id
        sql: id
        type: number
        primary_key: true

      - name: country
        sql: country
        type: string

      - name: city
        sql: city
        type: string

然后在 orders 中声明 join：

joins:
  - name: customers
    sql: "{CUBE}.customer_id = {customers.id}"
    relationship: many_to_one

这样你就能在同一查询里分析：

• 按国家看销售额；
• 按城市看订单数；
• 按客户属性切分订单指标。

6. 第四步：何时引入 view

当底层 cubes 变多时，不建议直接把所有成员裸暴露给终端消费者。

更合理的做法是加 view，例如：

• sales_overview
• finance_revenue
• customer_analysis

view 的作用是把一部分经过筛选的语义成员打包成真正给用户使用的数据产品。

7. 中文教程里最值得强调的两个建模原则

原则 1：先实体，再指标

先决定业务对象是什么，再决定指标怎么算，而不是先堆一堆公式。

原则 2：底层 cube 与消费 view 分层

• cube 负责底层语义与关系；
• view 负责消费端暴露、治理和语义门面。

8. 常见错误

错误 1：没标主键

没有主键会影响 join 去重与后续语义正确性。

错误 2：把所有字段都暴露出去

这会让语义层退化成“字段目录”。

错误 3：把底层技术字段直接当业务指标

比如直接把 gross_amount 暴露成“收入”，但业务上其实应该先扣退款。

错误 4：不区分底层模型和消费模型

会导致 BI、应用、Agent 全都直接接触过于底层的结构。

9. 一个更接近生产的建模顺序

1. 建 orders 基础 cube；
2. 建 customers、products、payments 等维度或关联 cube；
3. 配 joins；
4. 提炼 measure；
5. 定义 segments；
6. 构建 views；
7. 再补 pre-aggregations。

一句话总结

Cube 建模的真正目标不是“把表注册进去”，而是把业务对象、指标、维度、关系与常用过滤条件组织成一套可执行的语义资产。