最佳实践
设计建议
从业务场景出发定义语义视图
一个语义视图应对应一个清晰的分析域，如"员工薪资分析"或"订单收入分析"，而不是把所有表都塞进同一个视图。聚焦的视图更容易维护，查询性能也更好。建议从 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
）。它们会持久化并可通过
DESC EXTENDED
DESC EXTENDED
回读（
enum_values
enum_values
值保真；
is_unique
is_unique
/
is_time
is_time
只反映是否声明过，写了即回读
true
true
），但在 SQL 查询链路中
不影响结果——不参与查询优化、不约束/校验取值（设了
enum_values
enum_values
后越界值照常返回）。不要依赖它们做数据校验或性能优化。详见
能力与限制参考。
注意外键类型匹配
外键列与被引用列的数据类型必须一致，否则创建时报错。如果两张表通过 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 ...
修改结构用 CREATE OR REPLACE
ALTER SEMANTIC VIEW
ALTER SEMANTIC VIEW
支持
RENAME TO
RENAME TO
、
SET PROPERTIES
SET PROPERTIES
、
UNSET PROPERTIES
UNSET PROPERTIES
，但不支持增删维度或修改指标。要改结构，用
CREATE OR REPLACE SEMANTIC VIEW
CREATE OR REPLACE SEMANTIC VIEW
重放完整定义，无需先
DROP
DROP
：
-- 1. 用 SHOW CREATE SEMANTIC VIEW my_view 取回当前 DDL
-- 2. 编辑后原子替换
CREATE OR REPLACE 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：如何在语义视图查询中做过滤
semantic_view()
semantic_view()
括号内只接受
DIMENSIONS
DIMENSIONS
/
METRICS
METRICS
/
FACTS
FACTS
，不能直接传过滤条件。两种做法：用
FILTER (WHERE ...)
FILTER (WHERE ...)
定义条件聚合指标，或在
semantic_view()
semantic_view()
外层用
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;
算术表达式指标与派生指标都可直接写在 METRICS 里
算术表达式指标（
MAX(col) - MIN(col)
MAX(col) - MIN(col)
、
SUM(col) / COUNT(col)
SUM(col) / COUNT(col)
等）单独查询和与其他指标混查都返回正确结果。同一逻辑表内还可引用其他已命名指标做运算：
METRICS (
emps.salary_range AS MAX(salary) - MIN(salary), -- 算术表达式指标
emps.total AS SUM(salary),
emps.cnt AS COUNT(id),
emps.avg_calc AS emps.total / emps.cnt -- 派生指标：引用命名指标
)
Q：如何在指标里使用窗口函数（占比、累计、排名）
窗口函数可以用于指标定义（
RANK()
RANK()
/
ROW_NUMBER()
ROW_NUMBER()
排名，或
SUM(SUM(...)) OVER (...)
SUM(SUM(...)) OVER (...)
做占比、累计）。要点：
PARTITION BY
PARTITION BY
/
ORDER BY
ORDER BY
必须引用维度的
限定别名（如
orders.region
orders.region
），不能用物理列名或裸别名；只能引用指标同表的维度；查询时该维度须一并出现在
DIMENSIONS
DIMENSIONS
中。完整示例见
创建语义视图的"带窗口函数指标的语义视图"。跨表的复合计算仍需放到
semantic_view()
semantic_view()
外层 SQL 完成。
相关文档
