最佳实践
设计建议
从业务场景出发定义语义视图
一个语义视图应对应一个清晰的分析域，如"员工薪资分析"或"订单收入分析"，而不是把所有表都塞进同一个视图。聚焦的视图更容易维护，查询性能也更好。建议从 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 场景时，同义词有助于自然语言理解。
合理设置维度元数据
is_unique = true
is_unique = true
：用于唯一标识类维度（如客户 ID、员工姓名），帮助查询引擎优化is_time = true
is_time = true
：用于日期/时间类维度，支持时序分析工具正确识别enum_values
enum_values
：用于取值有限的维度（如状态、分类），可约束取值范围并提升 AI 理解准确性
注意外键类型匹配
外键列与被引用列的数据类型必须一致，否则创建时报错。如果两张表通过 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
，不支持增删维度或修改指标。修改视图结构的标准流程：
-- 1. 导出当前定义（可通过 DESC EXTENDED 或 MCP 工具 LH-desc-semantic-view）
-- 2. 删除旧视图
DROP SEMANTIC VIEW IF EXISTS my_view;
-- 3. 用修改后的定义重建
CREATE SEMANTIC VIEW my_view ...
通过 information_schema 监控视图状态
SELECT table_name, comment, create_time, last_modify_time
FROM information_schema.tables
WHERE table_schema = 'doc_test'
AND table_type = 'SEMANTIC_VIEW'
ORDER BY create_time DESC;
常见问题
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
中的命名过滤器是面向 AI/元数据层的语义注解，不能作为
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;
Q：指标定义了算术表达式（如 MAX - MIN），查询结果不对
算术表达式指标（
MAX(col) - MIN(col)
MAX(col) - MIN(col)
、
SUM(col) / COUNT(col)
SUM(col) / COUNT(col)
等）在创建时不报错，但查询时只返回第一个操作数的值，运算未被执行。这是当前版本的限制，请勿使用。
复合计算应在
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 (...)
等窗口函数不能用于指标定义，创建不报错但查询时行为异常。请勿使用。
相关文档
