Cube 核心概念

这一篇聚焦最重要的建模对象。只要把这些概念理解透，Cube 就不难了。

1. Cube：最基础的建模单元

官方文档把 cube 描述为：

• 代表一个数据集；
• 在概念上类似 SQL 中的视图；
• 通常一个文件定义一个 cube；
• cube 内部包含 measures、dimensions、segments、joins、pre-aggregations、access policies 等。

怎么理解最合适

你可以把 cube 理解为：

一个带有业务语义元数据的分析实体。

它通常对应：

• 事实表；
• 维表；
• 某个实体主题；
• 甚至一段 SQL 查询结果。

例子

cubes:
  - name: orders
    sql_table: orders

这个 orders 不只是表别名，而是后续定义指标、维度、关系和缓存策略的承载对象。

2. Measure：指标

measure 表示一个可以聚合、或经过计算后得到的分析指标。

常见例子：

• 订单数
• 销售额
• 退款金额
• 客单价
• 去重用户数
• 转化率

一个简单例子

measures:
  - name: count
    type: count

  - name: total_amount
    sql: amount
    type: sum

在业务语境里，measure 基本就对应用户说的“指标”。

3. Dimension：维度

dimension 表示分析时用来切分数据的属性。

例如：

• 时间
• 状态
• 渠道
• 城市
• 区域
• 产品分类
• 客户类型

例子

dimensions:
  - name: status
    sql: status
    type: string

  - name: created_at
    sql: created_at
    type: time

当用户问“按城市看销售额”，这里“销售额”是 measure，“城市”就是 dimension。

4. Segment：预定义过滤条件

segment 是固化在模型中的常用过滤逻辑。

例子

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

它的价值在于：

• 复用常见业务过滤规则；
• 避免每个查询都手写重复条件；
• 让 AI 或 BI 工具少猜一步。

5. Join：定义 cube 之间的关系

官方文档中，joins 用于定义 cubes 之间的关系。

常见关系：

• one_to_one
• one_to_many
• many_to_one

例子

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

为什么这对 AI 特别关键

因为 Agent 如果自己猜 join，很容易：

• 连错字段；
• 走错路径；
• 重复聚合；
• 产生维度爆炸。

而 Cube 的 join 定义，把这些路径显式固定了下来。

6. View：面向消费端的语义门面

官方文档对 view 的定义非常重要：

• views sit on top of the data graph of cubes；
• create a facade of your whole data model；
• useful for defining metrics、managing governance and data access、controlling ambiguous join paths；
• views do not define their own members，而是引用 cubes 的 members；
• views do not define pre-aggregations，而是复用底层 cubes 的预聚合。

最直观的理解

• cube 更偏底层建模对象；
• view 更偏面向用户的消费模型。

什么时候应该用 view

• 你希望只暴露一部分成员；
• 你需要为不同业务线做不同消费视图；
• 你想屏蔽底层复杂 join 图；
• 你要为 BI、应用、Agent 提供更稳定的数据产品入口。

7. Pre-aggregations：预聚合

pre-aggregations 是 Cube 中极其关键的性能能力。

文档中把它描述为：

• aggregate awareness 的实现；
• materialized query results；
• Cube 会分析查询并匹配可用的预聚合；
• 如果匹配成功，优先查询预聚合而不是原始数据。

一个简单例子

pre_aggregations:
  - name: main
    measures:
      - count
    dimensions:
      - status
    time_dimension: created_at
    granularity: day

它本质上像“针对常用分析问题预先建好的 rollup 表”。

8. Access Policy：访问控制策略

Cube 不只是建模工具，也承载数据治理。

官方文档说明：

• row-level security 可以通过 access policies 管理；
• 可以基于 groups 与 user attributes 控制数据行级访问；
• 还可以配合 member-level security 控制成员暴露。

行级过滤例子

access_policy:
  - group: manager
    row_level:
      filters:
        - member: country
          operator: equals
          values: ["{ userAttributes.country }"]

9. Primary Key、Additivity 这些“容易被忽略”的概念

Primary Key

文档中特别强调，某些维度需要显式标记 primary_key: true，尤其在 join 场景下，这对结果去重和正确聚合很关键。

Additivity

measure 是否可加性，会影响预聚合匹配。

官方文档指出，通常以下类型被视为 additive：

• count
• sum
• min
• max
• count_distinct_approx

而像 avg 这类指标，通常是非可加性的，需要更谨慎设计预聚合。

10. 推荐给中文读者的概念分层

讲解时建议按这三层来组织：

层 1：底层建模对象

• cube
• dimension
• measure
• segment
• join

层 2：消费与治理对象

• view
• folders
• access policy

层 3：性能对象

• pre-aggregations
• refresh key
• cache

这样读者会更容易把“是什么”和“为什么”连起来。

一句话总结

Cube 用 cube 表达底层业务实体，用 view 暴露消费语义，用 measure / dimension / join 描述分析逻辑，用 access policy 做治理，用 pre-aggregations 解决性能。