> For the complete documentation index, see [llms.txt](https://docs.reorc.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reorc.com/cn-reorc-help-center/semantics_modeling/yu-yi-ceng-mo-xing-cube.md).
# 语义层模型 (Cube)
## 概述
Recurve 的语义层（Semantic Layers）中的 **Cube** 是一种结构化数据模型，旨在实现高效的数据查询与分析。它将数据字段划分为 **指标（Measures）** 和 **维度（Dimensions）**，帮助用户轻松获取洞察。\
Cube 能够抽象复杂查询，提升数据性能和易用性，广泛应用于 BI 分析和报表展示。
## Cube 概念
**Cube** 是一种虚拟的数据模型，代表一个多维数据集，主要由以下部分组成：
* **指标（Measures）：**可进行聚合的数值型字段，例如：收入（Revenue）、销售数量（Sales Count）。
* **维度（Dimensions）：**用于分组和筛选的分类字段，例如：产品类别（Product Category）、地区（Region）、日期（Date）。
* **主键（Primary Key, PK）：**用于唯一标识 Cube 中每条数据记录，确保数据完整性。
* **外键 / 唯一键（Foreign / Unique Keys）：**每个 Cube 可以包含 0 个、1 个或多个外键或唯一键，用于关联其他数据模型或数据表。
Cube 的特点：
* **数据模型（Data Model Representation）：**每个数据模型或数据表都会被创建为一个独立的 Cube。
* **可复用性（Reusability）：**每个 Cube 可以被重复使用，用于构建语义层视图。
* **与 BI 工具集成（Integration with BI Tools）**Cube 中定义的维度和指标可以为 BI 工具提供数据，支持报表分析和可视化展示。
## Cube 支持的数据类型
从模型或数据仓库表中生成的字段类型会统一转为 **通用数据类型（Generic Data Type）**，包括以下类型：
* 字符串（String）
* 布尔值（Boolean）
* 日期（Date）
* 时间（Time）
* 整数（Integer）
* 小数（Decimal）
## 指标与维度（Measures and Dimensions）
如前所述，Cube 通过数据语义建模，帮助你实现更清晰的数据结构设计。在创建 Cube 时，首先需要指定目标数据表。接着，从表中的字段提取 **维度**，并基于这些维度进一步定义 **指标**。
* **维度（Dimensions）**维度是数据集中不参与聚合的字段，主要用于数据的细分和筛选。\
它们是指标的描述性属性。例如：`order_status`（订单状态），`payment_method`（支付方式）等，这些维度字段可以用来过滤或分类订单数据。
* **指标（Measures）**指标是在模型字段基础上进行聚合计算的结果，通常用于展示关键业务指标或计算分析。例如：`order_count`（订单总数），`average_order_value`（平均订单金额，计算公式为：销售总额 ÷ 订单总数）。指标既可以作为最终的度量指标。
#### 使用示例
定义好 Cube 之后，终端用户可以基于 Cube 灵活构建数据查询。例如，当用户提出问题：“今年每个月的收入是多少？” 可以通过以下方式查询数据：
* **指标（Measures）**：`revenue`（通过对订单金额求和聚合得出）
* **维度（Dimensions）**：`order_date`（按月份粒度分组）
## 创建 Cube
### **方式一：基于当前项目的数据模型（Model）创建**
要创建一个语义层模型（Cube），请按照以下步骤操作：
{% hint style="warning" %}
请先确认引用的数据模型已完成以下操作：
* 已定义字段列表，参考文档详见 [字段列表](/cn-reorc-help-center/shu-ju-jian-mo/zi-duan-lie-biao.md)。
* 已在生产环境对数据模型进行物化，参考文档详见 [建模管道](/cn-reorc-help-center/shu-ju-guan-dao/jian-mo-guan-dao.md)。
{% endhint %}
1. 进入“语义层”标签页，点击 **+** 按钮，选择 **创建语义模型**。
2. 在弹出的窗口中：
* 选择数据源（默认当前项目）。
* 选择你希望创建为 Cube 的数据模型。
* 点击 **创建** 按钮。
3. 语义模型创建成功后，将显示在 “语义模型” 文件夹下。
4. 在 **字段** 面板中，点击主键字段右侧的“**...**”，然后选择 **设置为主键**。
***
### **方式二：通过数据仓库连接创建**
{% hint style="warning" %}
请确保分析数据库的 **生产环境数据连接** 已完成设置，参考文档详见 [项目连接管理](/cn-reorc-help-center/lian-jie/xiang-mu-lian-jie-guan-li.md#she-zhi-fen-xi-shu-ju-ku)。
{% endhint %}
1. 进入 **Cube** 标签页，点击 **+** 按钮，选择 **新建 Cube**。
2. 在弹出的窗口中：
* 选择 **数据仓库**。
* 选择你希望创建为 Cube 的数据表。
点击 **创建** 按钮。
3. Cube 创建成功后，将显示在 **Cube** 文件夹下。
4. 在 **字段** 面板中，鼠标悬停在可以唯一标识 Cube 记录的维度字段上，点击 **...**，然后选择 **设置为主键**。
## 预览 Cube 结果
* 在 **显示设置** 面板中，可以通过点击 **+ 添加**（位于字段区域下方），选择你希望在语义模型中预览的维度和指标。
* 你可以进一步在 **筛选** 区域中添加维度或指标作为过滤条件，并在 **排序** 区域选择需要排序的字段。
* 点击 **预览** 按钮，即可查看已选字段与筛选条件下的 Cube 数据结果。
* 根据已选择的字段和条件，对应的 SQL 语句会在 **生成 SQL** 标签页自动展示。
***
## 管理 Cube
你可以根据分析主题将 Cube 分类存放在不同的文件夹中，以保持项目结构清晰有序。
创建新文件夹的方法如下：
点击现有文件夹右侧的操作按钮，选择 **添加子文件夹**。
点击模型右侧的操作按钮，选择 **移动**，然后从列表中选择目标文件夹，将模型移动到其他文件夹
