语义视图使用指南

语义视图是云器 Lakehouse 中的一种逻辑数据模型对象，在物理表结构与业务分析需求之间建立一层语义抽象：你集中定义表关系、维度和指标，查询时引擎自动处理 JOIN 和聚合，业务用户无需编写复杂 SQL，全组织也能用统一的指标口径。

与相近对象的选型：如果只需透明加速已有查询，用动态表或者物化视图；如果只需逻辑封装、不改变查询方式，用普通视图；如果要把多表关系、维度和指标沉淀成面向业务和 AI 的语义层，用语义视图。

核心组件

逻辑表（TABLES）：映射物理表的业务实体，通过主键和外键声明表间关系，查询时自动 JOIN
维度（DIMENSIONS）：分类属性，支持直接映射物理列或表达式计算（如
```
YEAR(hire_date)
```
YEAR(hire_date)
）
指标（METRICS）：通过聚合函数（
```
COUNT
```
COUNT
、
```
SUM
```
SUM
、
```
AVG
```
AVG
、
```
MIN
```
MIN
、
```
MAX
```
MAX
）定义的量化度量

⚠️ 注意：

CREATE SEMANTIC VIEW

CREATE SEMANTIC VIEW

还有

FILTERS

FILTERS

子句，但目前在 SQL 链路中无可观测效果（不进

DESC EXTENDED

DESC EXTENDED

、不能传入

semantic_view()

semantic_view()

），过滤请用外层

WHERE

WHERE

。

语义视图的完整文档在「语义视图」专题章节，按使用阶段拆分如下：

文档	内容
语义视图概述	功能定位、核心组件、典型场景
设计方法：从业务问题到视图	何时该用、从业务问题倒推建模、口径一致
创建语义视图	`CREATE SEMANTIC VIEW` CREATE SEMANTIC VIEW 语法、参数说明、指标限制、完整示例
查询语义视图	`semantic_view()` semantic_view() 函数用法、过滤、排序、与传统 SQL 对比
高级查询用法	子查询、CTE、与普通表 JOIN、CTAS、INSERT INTO
关系建模与聚合粒度	外键关系如何决定 JOIN 和聚合粒度、扇出与 chasm trap
管理语义视图	DROP、ALTER、SHOW、DESC EXTENDED、权限控制
组织与发现	多视图如何组织、命名与注释规范、如何找指标
与 AI 功能集成	AI_COMPLETE 组合查询、CZ-CLI 接入
用 AI Agent 生成和维护语义视图	业务对齐、信息收集、设计判断、验证方法
最佳实践	命名规范、设计建议、常见问题
能力与限制参考	指标/元数据/DDL/权限的支持与限制汇总