创建语义视图

语法

CREATE SEMANTIC VIEW <视图名称> TABLES ( <逻辑表定义> [ , ... ] ) [ FILTERS ( <过滤器定义> [ , ... ] ) ] [ DIMENSIONS ( <维度定义> [ , ... ] ) ] [ METRICS ( <指标定义> [ , ... ] ) ] [ COMMENT = '<视图说明>' ] ;

各子句的定义语法如下：

逻辑表定义

<表别名> AS <架构名>.<物理表名> PRIMARY KEY ( <列名> [ , ... ] ) [ FOREIGN KEY ( <列名> ) REFERENCES <其他逻辑表别名> [ ( <引用列名> ) ] ] [ WITH SYNONYMS ( '<同义词>' [ , ... ] ) ] [ COMMENT = '<说明>' ]

过滤器定义

<逻辑表别名>.<过滤器名> AS <布尔表达式>

维度定义

{ <逻辑表别名>.<维度名> | <维度名> } AS <表达式> [ WITH SYNONYMS = ( '<同义词>' [ , ... ] ) ] [ is_unique = { true | false } ] [ is_time = { true | false } ] [ enum_values = [ <值1>, <值2>, ... ] ] [ COMMENT = '<说明>' ]

指标定义

<逻辑表别名>.<指标名> AS <聚合表达式> [ COMMENT = '<说明>' ]

参数说明

逻辑表参数

参数	说明
`<表别名> AS <架构名>.<物理表名>` <表别名> AS <架构名>.<物理表名>	为物理表指定逻辑别名，后续维度、指标、外键定义均使用此别名
`PRIMARY KEY ( <列名> )` PRIMARY KEY ( <列名> )	指定主键列，用于确定表间关系类型
`FOREIGN KEY ( <列名> ) REFERENCES <别名> [ ( <引用列名> ) ]` FOREIGN KEY ( <列名> ) REFERENCES <别名> [ ( <引用列名> ) ]	定义外键关系。当外键列与被引用表主键列名不同时，需显式指定引用列名。外键列与引用列数据类型必须一致，否则创建报错
`WITH SYNONYMS ( '<同义词>' )` WITH SYNONYMS ( '<同义词>' )	为逻辑表定义同义词，增强可发现性
`COMMENT = '<说明>'` COMMENT = '<说明>'	逻辑表描述

维度参数

参数	说明
`is_unique = true` is_unique = true	标识该维度值唯一，如客户名称
`is_time = true` is_time = true	标识该维度为时间类型，如订单日期
`enum_values = [...]` enum_values = [...]	限定维度的允许取值范围
`WITH SYNONYMS = (...)` WITH SYNONYMS = (...)	为维度定义同义词，支持多种业务术语引用同一维度

指标聚合函数

支持：

COUNT

COUNT

、

AVG

AVG

、

SUM

SUM

、

MIN

MIN

、

MAX

MAX

，以及条件聚合，如

COUNT(CASE WHEN col = value THEN 1 END)

COUNT(CASE WHEN col = value THEN 1 END)

不支持（创建不报错，但查询结果错误或报 compiler error，请勿使用）：

算术表达式指标：
```
MAX(col) - MIN(col)
```
MAX(col) - MIN(col)
、
```
SUM(col) / COUNT(col)
```
SUM(col) / COUNT(col)
等，查询时只返回第一个操作数的值
窗口函数指标：
```
RANK() OVER (...)
```
RANK() OVER (...)
，查询时行为异常
派生指标（指标引用指标）：
```
metric_a / metric_b
```
metric_a / metric_b
，创建时报
```
cannot resolve column
```
cannot resolve column

如需计算人均值、占比等复合指标，建议在

semantic_view()

semantic_view()

查询的外层 SQL 中计算：

SELECT department, total_salary / total_employees AS avg_salary_calc FROM semantic_view( my_view, DIMENSIONS department, METRICS total_salary, METRICS total_employees );

使用说明

```
TABLES
```
TABLES
子句是必须的，不可省略。
```
DIMENSIONS
```
DIMENSIONS
和
```
METRICS
```
METRICS
均为可选。
被外键引用的逻辑表必须在
```
TABLES
```
TABLES
子句中先于引用方定义。
视图已存在时
```
CREATE SEMANTIC VIEW
```
CREATE SEMANTIC VIEW
报错，建议先执行
```
DROP SEMANTIC VIEW IF EXISTS
```
DROP SEMANTIC VIEW IF EXISTS
。
维度支持表达式（计算维度），如
```
YEAR(hire_date)
```
YEAR(hire_date)
，查询结果返回整数类型。
维度和指标命名支持限定名称（
```
alias.name
```
alias.name
）和短名称（
```
name
```
name
）两种形式，名称唯一时两者等效。
```
FILTERS
```
FILTERS
子句中的命名过滤器是面向 AI/元数据层的语义注解，不能直接传入
```
semantic_view()
```
semantic_view()
函数，需通过外层
```
WHERE
```
WHERE
子句实现过滤。

示例

基础示例：单表语义视图

DROP SEMANTIC VIEW IF EXISTS doc_test.emp_dept_analysis; CREATE SEMANTIC VIEW doc_test.emp_dept_analysis TABLES ( depts AS doc_test.departments PRIMARY KEY (dept_name), emps AS doc_test.employees PRIMARY KEY (id) FOREIGN KEY (dept) REFERENCES depts (dept_name) ) DIMENSIONS ( emps.employee_name AS emps.name WITH SYNONYMS = ('员工姓名', 'staff name') is_unique = true COMMENT = '员工姓名', emps.department AS emps.dept COMMENT = '所在部门', emps.hire_year AS YEAR(emps.hire_date) is_time = true COMMENT = '入职年份', depts.manager_name AS depts.manager COMMENT = '部门经理' ) METRICS ( emps.total_employees AS COUNT(emps.id) COMMENT = '员工总数', emps.avg_salary AS AVG(emps.salary) COMMENT = '平均薪资', emps.max_salary AS MAX(emps.salary) COMMENT = '最高薪资' ) COMMENT = '员工部门分析语义视图';

说明：

```
depts
```
depts
和
```
emps
```
emps
是逻辑表别名，物理表分别是
```
doc_test.departments
```
doc_test.departments
和
```
doc_test.employees
```
doc_test.employees
```
FOREIGN KEY (dept) REFERENCES depts (dept_name)
```
FOREIGN KEY (dept) REFERENCES depts (dept_name)
：
```
emps.dept
```
emps.dept
（string）关联
```
depts.dept_name
```
depts.dept_name
（string），类型一致
```
hire_year
```
hire_year
是计算维度，通过
```
YEAR()
```
YEAR()
表达式从日期列派生

带过滤器和维度元数据的语义视图

以下示例展示了

FILTERS

FILTERS

、

is_unique

is_unique

、

is_time

is_time

、

enum_values

enum_values

的完整用法：

DROP SEMANTIC VIEW IF EXISTS tpch_rev_analysis; CREATE SEMANTIC VIEW tpch_rev_analysis TABLES ( customers AS TPCH_AI.CUSTOMER PRIMARY KEY (c_custkey) COMMENT = 'Main table for customer data', orders AS TPCH_AI.ORDERS PRIMARY KEY (o_orderkey) FOREIGN KEY (o_custkey) REFERENCES customers WITH SYNONYMS ('sales orders') COMMENT = 'All orders table for the sales domain', line_items AS TPCH_AI.LINEITEM PRIMARY KEY (l_orderkey, l_linenumber) FOREIGN KEY (l_orderkey) REFERENCES orders COMMENT = 'Line items in orders' ) FILTERS ( customers.is_ny AS customers.c_city = 'New York' ) DIMENSIONS ( customers.customer_name AS customers.c_name WITH SYNONYMS = ('customer name') is_unique = true COMMENT = 'Name of the customer', orders.order_date AS o_orderdate is_time = true enum_values = [date'2025-01-01', date'2025-06-01', date'2025-12-01'] COMMENT = 'Date when the order was placed', orders.order_year AS YEAR(o_orderdate) COMMENT = 'Year when the order was placed' ) METRICS ( customers.customer_count AS COUNT(c_custkey) COMMENT = 'Count of number of customers', orders.order_average_value AS AVG(orders.o_totalprice) COMMENT = 'Average order value across all orders' ) COMMENT = 'Semantic view for revenue analysis';