最佳实践
设计建议
从业务场景出发定义语义视图
一个语义视图应对应一个清晰的分析域，如"员工薪资分析"或"订单收入分析"，而不是把所有表都塞进同一个视图。聚焦的视图更容易维护，查询性能也更好。建议从 3–5 张核心表开始，验证维度和指标的准确性后再逐步扩展。
使用业务术语命名
为逻辑表、维度、指标选择业务用户熟悉的名称，而不是物理列名的直接映射：
-- 推荐
emps.avg_salary AS AVG(emps.salary) -- 平均薪资
customers.customer_name AS c.c_name -- 客户名称
-- 不推荐
emps.avg_salary_col AS AVG(emps.salary) -- 带 _col 后缀，不自然
c.c_name_field AS c.c_name -- 保留了物理字段命名风格
善用
WITH SYNONYMS
WITH SYNONYMS
和
COMMENT
COMMENT
增强可发现性，尤其是面向 AI Agent 场景时，同义词有助于自然语言理解。
维度元数据（当前无 SQL 层效果）
is_unique
is_unique
、
is_time
is_time
、
enum_values
enum_values
是面向上层 AI/元数据工具的声明性标注，可按语义如实填写（如时间维度标
is_time = true
is_time = true
、有限取值维度列出
enum_values
enum_values
）。但要清楚：当前版本它们
在 SQL 链路中没有可观测效果——不参与查询优化、不约束/校验取值（实测设了
enum_values
enum_values
后越界值照常返回）、也不会出现在
DESC EXTENDED
DESC EXTENDED
中。不要依赖它们做数据校验或性能优化。详见
能力与限制参考。
注意外键类型匹配
外键列与被引用列的数据类型必须一致，否则创建时报错。如果两张表通过 string 列关联，被引用表的主键也应声明为该 string 列，而不是整数 ID：
-- 正确：dept（string）关联 dept_name（string）
FOREIGN KEY (dept) REFERENCES depts (dept_name)
-- 错误：dept（string）关联 dept_id（int），类型不匹配
FOREIGN KEY (dept) REFERENCES depts -- 默认引用主键 dept_id（int），报错
注意逻辑表定义顺序
TABLES
TABLES
子句中，被外键引用的表必须先定义：
TABLES (
depts AS ..., -- 先定义被引用表
emps AS ...
FOREIGN KEY (dept) REFERENCES depts (dept_name) -- 再定义引用方
)
维护建议
用 DROP IF EXISTS 确保脚本幂等
DROP SEMANTIC VIEW IF EXISTS my_view;
CREATE SEMANTIC VIEW my_view ...
修改结构需要重建
当前
ALTER SEMANTIC VIEW
ALTER SEMANTIC VIEW
支持
RENAME TO
RENAME TO
、
SET PROPERTIES
SET PROPERTIES
、
UNSET PROPERTIES
UNSET PROPERTIES
，但不支持增删维度或修改指标。修改视图结构的标准流程：
-- 1. 导出当前定义（可通过 DESC EXTENDED）
-- 2. 删除旧视图
DROP SEMANTIC VIEW IF EXISTS my_view;
-- 3. 用修改后的定义重建
CREATE SEMANTIC VIEW my_view ...
查看当前 schema 下的语义视图
SHOW SEMANTIC VIEWS IN doc_test;
⚠️ 注意：语义视图不在
information_schema.tables
information_schema.tables
中，使用
SHOW SEMANTIC VIEWS
SHOW SEMANTIC VIEWS
查看视图列表，使用
DESC EXTENDED <视图名>
DESC EXTENDED <视图名>
查看完整定义。
常见问题
Q：FOREIGN KEY 创建时报类型不匹配错误
检查外键列与引用列的数据类型是否一致。当引用列与主键列不同名时，需显式指定：
FOREIGN KEY (dept) REFERENCES depts (dept_name)
Q：DESC 视图返回空
语义视图没有普通列定义，
DESC
DESC
不带
EXTENDED
EXTENDED
返回空。需使用：
DESC EXTENDED my_view;
Q：semantic_view()
semantic_view()
报 function not found
需要至少指定一个
DIMENSIONS
DIMENSIONS
或
METRICS
METRICS
参数，不能只传视图名：
-- 错误
SELECT * FROM semantic_view(my_view);
-- 正确
SELECT * FROM semantic_view(my_view, DIMENSIONS dim1, METRICS metric1);
Q：FILTERS 子句定义的过滤器无法在查询中使用
FILTERS
FILTERS
子句目前在 SQL 链路中没有可观测效果：创建时虽然被接受，但不会出现在
DESC EXTENDED
DESC EXTENDED
输出中，也不能作为
semantic_view()
semantic_view()
的参数传入（传入会报语法错误）。不要依赖
FILTERS
FILTERS
做过滤，过滤统一通过外层
WHERE
WHERE
子句实现：
SELECT * FROM semantic_view(my_view, DIMENSIONS city, METRICS cnt)
WHERE city = 'New York';
Q：ALTER SEMANTIC VIEW RENAME TO 报语法错误
新名称不能带 schema 前缀：
-- 错误
ALTER SEMANTIC VIEW my_view RENAME TO doc_test.new_view;
-- 正确
ALTER SEMANTIC VIEW my_view RENAME TO new_view;
Q：指标定义了算术表达式（如 MAX - MIN），查询结果不对
算术表达式指标（
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 中完成：
-- 不要在 METRICS 里写：emps.salary_range AS MAX(salary) - MIN(salary)
-- 正确做法：在外层 SQL 计算
SELECT department, max_salary - min_salary AS salary_range
FROM semantic_view(
my_view,
DIMENSIONS department,
METRICS max_salary,
METRICS min_salary
);
Q：指标定义中引用其他指标（派生指标）报 cannot resolve column
不支持在指标定义中引用其他指标名称。
emps.avg AS emps.total / emps.count
emps.avg AS emps.total / emps.count
这类写法会在创建时报错。同样需要在外层 SQL 中计算。
Q：窗口函数指标查询时报 Compiler internal error
RANK() OVER (...)
RANK() OVER (...)
、
ROW_NUMBER() OVER (...)
ROW_NUMBER() OVER (...)
等窗口函数不能用于指标定义，创建不报错但查询时行为异常。请勿使用。
相关文档
