语义视图能力与限制参考

本文集中说明语义视图当前版本支持的能力和已知限制，供你在设计视图或排查报错时查阅。每条限制都附最小复现 SQL 和真实报错。

功能概述

语义视图通过声明式定义把多表关系、维度和指标沉淀为业务语义层。但当前版本在指标定义、元数据回读、DDL 管理等方面存在一些边界。设计前先了解这些限制，可以避免"创建成功但查询出错"或"定义无法回读"这类问题。需要完整查询语法见查询语义视图，跨表关系的聚合粒度见语义视图关系建模与聚合粒度。

指标定义限制

指标只支持基础聚合函数（

COUNT

COUNT

、

SUM

SUM

、

AVG

AVG

、

MIN

MIN

、

MAX

MAX

）和条件聚合（

COUNT(CASE WHEN ...)

COUNT(CASE WHEN ...)

）。以下三类指标定义不受支持。

派生指标（指标引用指标） —— 创建时即失败。

METRICS ( orders.cnt AS COUNT(orders.o_orderkey), orders.ratio AS orders.cnt / orders.cnt -- 引用了另一个指标 )

创建报错：

CZLH-42000: cannot resolve column 'orders.cnt'

窗口函数指标 —— 创建不报错，但查询时失败。

METRICS ( orders.rnk AS RANK() OVER (ORDER BY orders.o_totalprice) )

视图能创建成功，但查询该指标时报：

CZLH-65000: Compiler internal error - generating logical plan failed

算术表达式指标 —— 创建不报错，但结果错误。

MAX(col) - MIN(col)

MAX(col) - MIN(col)

、

SUM(col) / COUNT(col)

SUM(col) / COUNT(col)

这类，单独查询时只返回第一个操作数的值（如

MAX-MIN

MAX-MIN

MAX

MAX

），运算不执行；与其他指标一起查询时直接报

CZLH-65000: Compiler internal error

CZLH-65000: Compiler internal error

。

⚠️ 注意：以上三类复合计算都应放到

semantic_view()

semantic_view()

查询的外层 SQL 中完成，例如

SELECT max_salary - min_salary FROM semantic_view(...)

SELECT max_salary - min_salary FROM semantic_view(...)

。

元数据子句限制

CREATE SEMANTIC VIEW

CREATE SEMANTIC VIEW

接受

FILTERS

FILTERS

、

WITH SYNONYMS

WITH SYNONYMS

、

is_unique

is_unique

、

is_time

is_time

、

enum_values

enum_values

这些子句，但它们在当前 SQL 链路中没有可观测效果：

创建时被接受，不报错
但都不会出现在
```
DESC EXTENDED
```
DESC EXTENDED
输出中，创建后无法回读
```
FILTERS
```
FILTERS
还不能作为
```
semantic_view()
```
semantic_view()
的参数传入（传入报语法错误）

过滤请统一用

semantic_view()

semantic_view()

外层的

WHERE

WHERE

子句实现。这些子句更多是面向上层 AI/元数据工具的声明。

关系与查询限制

查询必须至少指定一个
```
DIMENSIONS
```
DIMENSIONS
或
```
METRICS
```
METRICS
，否则报
```
table or view not found - semantic_view
```
table or view not found - semantic_view
。
不能在同一次查询中组合来自两个无直接关系路径的分支的指标（chasm trap），会报
```
No relationship found for table <表名>
```
No relationship found for table <表名>
。
跨表查询的连接和聚合粒度由指标所在表驱动，关系建模直接影响结果正确性。详见语义视图关系建模与聚合粒度。

DDL 与管理限制

不支持
CREATE OR REPLACE SEMANTIC VIEW
CREATE OR REPLACE SEMANTIC VIEW
，报
```
only view/stream/materialized view support replace
```
only view/stream/materialized view support replace
。修改结构必须
```
DROP
```
DROP
后重建。
```
ALTER SEMANTIC VIEW
```
ALTER SEMANTIC VIEW
只支持
```
RENAME TO
```
RENAME TO
，且新名称不能带 schema 前缀（带前缀报语法错误）。
没有
```
GET_DDL
```
GET_DDL
、
```
SHOW CREATE SEMANTIC VIEW
```
SHOW CREATE SEMANTIC VIEW
、YAML 导出等回读完整定义的手段；
```
DESC SEMANTIC VIEW
```
DESC SEMANTIC VIEW
/
```
DESCRIBE SEMANTIC VIEW
```
DESCRIBE SEMANTIC VIEW
命令存在但返回空，
```
DESC
```
DESC
（不加
```
EXTENDED
```
EXTENDED
）也返回空。能读回结构的只有
```
DESC EXTENDED
```
DESC EXTENDED
，且它不含上面的元数据子句。

创建行为

```
TABLES
```
TABLES
子句必填，
```
DIMENSIONS
```
DIMENSIONS
和
```
METRICS
```
METRICS
均可选（仅
```
TABLES
```
TABLES
也能创建成功）。
视图已存在时
```
CREATE SEMANTIC VIEW
```
CREATE SEMANTIC VIEW
报
```
already exists
```
already exists
；用
```
IF NOT EXISTS
```
IF NOT EXISTS
跳过，或先执行
```
DROP SEMANTIC VIEW IF EXISTS
```
DROP SEMANTIC VIEW IF EXISTS
保证脚本幂等。
外键列与被引用列数据类型必须一致，否则报错，例如：

CZLH-42000: type int of foreign key column o_custkey does not match type string of referenced column c_name

权限模型

语义视图只支持只读权限。

```
GRANT SELECT
```
GRANT SELECT
（或
```
ALL
```
ALL
，等同于 SELECT）可授予角色查询权限；创建者自动拥有
```
ALL
```
ALL
。
不支持
```
INSERT
```
INSERT
/
```
UPDATE
```
UPDATE
/
```
DELETE
```
DELETE
，
```
GRANT INSERT ON SEMANTIC VIEW ...
```
GRANT INSERT ON SEMANTIC VIEW ...
报
```
invalid action type INSERT
```
invalid action type INSERT
。
```
SHOW GRANTS ON SEMANTIC VIEW <名称>
```
SHOW GRANTS ON SEMANTIC VIEW <名称>
查看授权，返回列：
```
granted_type
```
granted_type
、
```
privilege
```
privilege
、
```
conditions
```
conditions
、
```
granted_on
```
granted_on
（值为
```
SEMANTIC_VIEW
```
SEMANTIC_VIEW
）、
```
object_name
```
object_name
、
```
granted_to
```
granted_to
、
```
grantee_name
```
grantee_name
、
```
grantor_name
```
grantor_name
、
```
grant_option
```
grant_option
、
```
granted_time
```
granted_time
。

GRANT SELECT ON SEMANTIC VIEW doc_test.emp_dept_analysis TO ROLE workspace_analyst; REVOKE SELECT ON SEMANTIC VIEW doc_test.emp_dept_analysis FROM ROLE workspace_analyst;

限制速查表

能力	状态	说明 / 报错
派生指标（指标引用指标）	不支持	创建报 cannot resolve column
窗口函数指标	不支持	创建成功、查询报 Compiler error
算术表达式指标	不支持	单独查返回第一个操作数、混查报错
FILTERS / SYNONYMS / is_unique / is_time / enum_values	无可观测效果	创建接受、不进 DESC、不可回读
chasm trap（兄弟分支指标组合）	拦截报错	No relationship found for table …
CREATE OR REPLACE	不支持	须 DROP 后重建
ALTER	仅 RENAME TO	不能带 schema 前缀
回读完整定义（YAML/DDL）	无手段	DESC SEMANTIC VIEW 返回空
仅 TABLES 创建	支持	DIMENSIONS / METRICS 可选
权限	只读	SELECT / ALL；无 INSERT / UPDATE / DELETE

排错速查（按症状）

遇到报错或结果不对时，按下面的症状定位原因。

症状 / 报错	原因	对策
创建报 `cannot resolve column` cannot resolve column	指标引用了另一个指标（派生指标）	复合计算放到外层 SQL
查询报 `Compiler internal error` Compiler internal error	用了窗口函数指标，或算术指标与其他指标混查	改用基础聚合，复合计算放外层 SQL
创建报 `type ... does not match` type ... does not match	外键列与被引用列类型不一致	改用类型一致的列，或显式指定引用列
查询报 `No relationship found for table` No relationship found for table	组合了两个无直接关系路径的分支指标（chasm trap）	拆成多次查询，每次只取一条关系链上的指标
查询报 `table or view not found - semantic_view` table or view not found - semantic_view	`semantic_view()` semantic_view() 没传任何 DIMENSIONS/METRICS	至少指定一个维度或指标
创建报 `already exists` already exists	视图已存在	加 `IF NOT EXISTS` IF NOT EXISTS ，或先 `DROP ... IF EXISTS` DROP ... IF EXISTS
创建报 `only view/stream/materialized view support replace` only view/stream/materialized view support replace	用了 `CREATE OR REPLACE` CREATE OR REPLACE	不支持，改为 `DROP` DROP 后重建
`DESC` DESC 返回空	没加 `EXTENDED` EXTENDED ，或用了 `DESC SEMANTIC VIEW` DESC SEMANTIC VIEW	用 `DESC EXTENDED <视图名>` DESC EXTENDED <视图名>
`SHOW SEMANTIC VIEWS LIKE` SHOW SEMANTIC VIEWS LIKE 返回空	`SHOW` SHOW 不支持 `LIKE` LIKE 过滤	去掉 LIKE，全列后自行筛选
设的 `enum_values` enum_values / `SYNONYMS` SYNONYMS 读不回	元数据子句无可观测效果	当前预期行为，以创建脚本为定义来源
跨表指标数值偏大/重复	手写 JOIN 导致扇出双重计算	用语义视图自动按指标粒度聚合，不要手写 JOIN
维度成员缺失（如某客户不出现）	该成员在指标表里没有事实行	需要全集时直接查维度表，详见关系建模与聚合粒度