最佳实践

设计建议

从业务场景出发定义语义视图

一个语义视图应对应一个清晰的分析域，如"员工薪资分析"或"订单收入分析"，而不是把所有表都塞进同一个视图。聚焦的视图更容易维护，查询性能也更好。建议从 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
子句中，外键引用不要求被引用表先定义——引用方写在前、被引用表写在后，视图同样能创建并正常查询（内联 
FOREIGN KEY
FOREIGN KEY
和顶层 
RELATIONSHIPS
RELATIONSHIPS
两种写法都一样）。不过按"父表在前"的顺序写可读性更好，建议保持：

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;

常见问题

Q：FOREIGN KEY 创建时报类型不匹配错误

检查外键列与引用列的数据类型是否一致。当引用列与主键列不同名时，需显式指定：

FOREIGN KEY (dept) REFERENCES depts (dept_name)

Q：DESC 看不到 workspace、creator、properties 这些信息

DESC <视图名>
DESC <视图名>
会返回逻辑表、关系、维度、指标各节，但开头那段 
# detailed table information
# detailed table information
（workspace / schema / creator / created_time / properties / version / type）只有 
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, -- 表级派生指标：引用同表命名指标 -- 视图级派生指标（不带表前缀）：跨表相除，两腿各自粒度聚合再对齐 return_rate AS returns.total_returns / sales.total_sales )

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
中。完整示例见创建语义视图的"带窗口函数指标的语义视图"。跨表、跨粒度的相除用不带表前缀的视图级派生指标实现，示例见创建语义视图的"带视图级派生指标的语义视图"。

相关文档

用 AI Agent 生成和维护语义视图
能力与限制参考
Yunqi © 2024 Yunqi, Inc. All Rights Reserved.
联系我们
预约咨询
微信咨询
电话咨询
邮件咨询