查询语义视图
使用
semantic_view()semantic_view()
表函数查询语义视图，引擎自动根据外键定义处理表连接和聚合，无需手写 JOIN 和 GROUP BY。
语法
semantic_view( <视图名称>
[ DIMENSIONS <项> [ , <项> ... ] ]
[ METRICS <项> [ , <项> ... ] ]
[ FACTS <项> [ , <项> ... ] ]
[ WHERE <谓词> ]
[ VARIABLES <名> => <值> [ , ... ] ]
)
⚠️ 注意 ：视图名后没有逗号 ，直接跟第一个子句关键字。
DIMENSIONSDIMENSIONS
、
METRICSMETRICS
、
FACTSFACTS
每个关键字
最多出现一次 ，同一关键字下的多个项用逗号分隔（
DIMENSIONS a, bDIMENSIONS a, b
而非
DIMENSIONS a DIMENSIONS bDIMENSIONS a DIMENSIONS b
）。视图名后加逗号、或重复关键字都会报语法错误。
维度、指标、事实名称支持两种形式：
限定名称 ：<逻辑表别名>.<名称><逻辑表别名>.<名称>
，如 emps.departmentemps.department
短名称 ：直接使用名称，如 departmentdepartment
（名称在视图内唯一时可用）
DIMENSIONSDIMENSIONS
、
METRICSMETRICS
、
FACTSFACTS
三个子句
与顺序无关 （
METRICS ... DIMENSIONS ...METRICS ... DIMENSIONS ...
与
DIMENSIONS ... METRICS ...DIMENSIONS ... METRICS ...
效果相同），输出列按项书写的顺序排列。
WHEREWHERE
与
VARIABLESVARIABLES
是
结尾子句 ，必须排在三个子句关键字之后，且
WHEREWHERE
在
VARIABLESVARIABLES
之前。
FACTSFACTS
用于选取视图
FACTSFACTS
子句里直接定义的组合聚合事实；如果事实只是把子表列透传给某个
METRICSMETRICS
指标引用，则查询该指标时用
METRICSMETRICS
（见下方"查询 FACTS 事实"）。
使用说明
必须至少指定一个 DIMENSIONSDIMENSIONS
、METRICSMETRICS
或 FACTSFACTS
参数，否则报错。
只传 DIMENSIONSDIMENSIONS
不传 METRICSMETRICS
：返回去重后的维度值列表。
只传 METRICSMETRICS
不传 DIMENSIONSDIMENSIONS
：返回全局聚合结果（一行）。
查询结果按指定维度自动分组，维度顺序与查询中指定的顺序一致。
过滤维度可用内部 WHEREWHERE
（结尾子句），也可在 semantic_view()semantic_view()
外层用 WHEREWHERE
；ORDER BYORDER BY
、LIMITLIMIT
只能放外层。
支持 SELECT col1, col2 FROM semantic_view(...)SELECT col1, col2 FROM semantic_view(...)
选取部分列，不必用 SELECT *SELECT *
。
示例
以下示例基于
doc_test.emp_dept_analysisdoc_test.emp_dept_analysis
语义视图（定义见
创建语义视图 ）。
按维度分组统计指标
SELECT * FROM semantic_view(
doc_test.emp_dept_analysis
DIMENSIONS emps.department
METRICS emps.total_employees, emps.avg_salary
) ORDER BY department;
+-------------+-----------------+----------------+
| department | total_employees | avg_salary |
+-------------+-----------------+----------------+
| Engineering | 2 | 115000.000000 |
| HR | 1 | 80000.000000 |
| Marketing | 2 | 92500.000000 |
+-------------+-----------------+----------------+
跨表维度（自动 JOIN）
外键关联的维度可以直接使用，引擎自动处理 JOIN：
SELECT * FROM semantic_view(
doc_test.emp_dept_analysis
DIMENSIONS depts.manager_name
METRICS emps.total_employees, emps.avg_salary
) ORDER BY manager_name;
+--------------+-----------------+----------------+
| manager_name | total_employees | avg_salary |
+--------------+-----------------+----------------+
| Alice | 2 | 115000.000000 |
| Bob | 2 | 92500.000000 |
| Carol | 1 | 80000.000000 |
+--------------+-----------------+----------------+
使用短名称
名称在视图内唯一时，可省略逻辑表别名前缀：
SELECT * FROM semantic_view(
doc_test.emp_dept_analysis
DIMENSIONS department
METRICS total_employees
) ORDER BY department;
+-------------+-----------------+
| department | total_employees |
+-------------+-----------------+
| Engineering | 2 |
| HR | 1 |
| Marketing | 2 |
+-------------+-----------------+
WHERE 过滤
将需要过滤的列定义为维度后，用
WHEREWHERE
过滤。
WHEREWHERE
可以写在
semantic_view()semantic_view()
内部 （作为结尾子句，排在
DIMENSIONSDIMENSIONS
/
METRICSMETRICS
/
FACTSFACTS
之后），此处维度
限定名或短名均可 ：
SELECT * FROM semantic_view(
doc_test.emp_dept_analysis
DIMENSIONS emps.department
METRICS emps.avg_salary
WHERE emps.department = 'Engineering'
);
+-------------+--------------+
| department | avg_salary |
+-------------+--------------+
| Engineering | 115000.000000 |
+-------------+--------------+
也可以写在
semantic_view()semantic_view()
外层 ，结果相同。但外层
WHEREWHERE
引用的是
semantic_view()semantic_view()
输出列，
只能用维度短名 （写
emps.departmentemps.department
会报
cannot resolve column 'emps.department'cannot resolve column 'emps.department'
）：
SELECT * FROM semantic_view(
doc_test.emp_dept_analysis
DIMENSIONS emps.department
METRICS emps.avg_salary
) WHERE department = 'Engineering';
⚠️ 注意 ：内部
WHEREWHERE
只能过滤
维度 ，不能引用指标——
WHEREWHERE
在指标聚合之前执行。按聚合结果过滤（如
total_employees > 1total_employees > 1
）时内部
WHEREWHERE
会报
a METRIC '<名>' is not allowed in the semantic_view() WHERE clausea METRIC '<名>' is not allowed in the semantic_view() WHERE clause
，必须用外层 SQL 包裹：
SELECT * FROM (SELECT * FROM semantic_view(...)) t WHERE t.total_employees > 1SELECT * FROM (SELECT * FROM semantic_view(...)) t WHERE t.total_employees > 1
。
只传 METRICS，返回全局聚合
SELECT * FROM semantic_view(
doc_test.emp_dept_analysis
METRICS emps.total_employees, emps.avg_salary
);
+-----------------+---------------+
| total_employees | avg_salary |
+-----------------+---------------+
| 5 | 99000.000000 |
+-----------------+---------------+
计算维度查询
计算维度（如
YEARYEAR
表达式）返回整数类型：
SELECT * FROM semantic_view(
doc_test.emp_dept_analysis
DIMENSIONS emps.hire_year
METRICS emps.total_employees
) ORDER BY hire_year;
+-----------+-----------------+
| hire_year | total_employees |
+-----------+-----------------+
| 2019 | 1 |
| 2020 | 1 |
| 2021 | 1 |
| 2022 | 1 |
| 2023 | 1 |
+-----------+-----------------+
多维度组合
SELECT * FROM semantic_view(
doc_test.emp_dept_analysis
DIMENSIONS emps.department, emps.hire_year
METRICS emps.total_employees
) ORDER BY department, hire_year;
+-------------+-----------+-----------------+
| department | hire_year | total_employees |
+-------------+-----------+-----------------+
| Engineering | 2019 | 1 |
| Engineering | 2020 | 1 |
| HR | 2023 | 1 |
| Marketing | 2021 | 1 |
| Marketing | 2022 | 1 |
+-------------+-----------+-----------------+
查询 FACTS 事实
当视图定义了
FACTSFACTS
子句时，指标可以引用透传的事实。以下基于
doc_test.sv_factsdoc_test.sv_facts
（定义见
创建语义视图 的"带 FACTS 的语义视图"），
order_countorder_count
是引用了透传事实
orders.order_idorders.order_id
的指标，查询时按普通指标用
METRICSMETRICS
选取：
SELECT * FROM semantic_view(
doc_test.sv_facts
DIMENSIONS customer.cust_name
METRICS customer.order_count
) ORDER BY cust_name;
+-----------+-------------+
| cust_name | order_count |
+-----------+-------------+
| Alice | 2 |
| Bob | 1 |
+-----------+-------------+
查询时绑定 VARIABLES
如果视图声明了
VARIABLESVARIABLES
（查询参数，定义见
创建语义视图 的"带查询参数的语义视图"），可以在查询末尾用
VARIABLESVARIABLES
子句为本次查询绑定值，覆盖声明时的默认值。以下基于
doc_test.sv_variablesdoc_test.sv_variables
，它有一个阈值参数
min_amountmin_amount
（默认 1000）用于把销售额划分成 HIGH / LOW。
不绑定，使用默认值
min_amount = 1000min_amount = 1000
：
SELECT * FROM semantic_view(
doc_test.sv_variables
DIMENSIONS sale_category
METRICS total_sales
) ORDER BY sale_category;
+---------------+-------------+
| sale_category | total_sales |
+---------------+-------------+
| HIGH | 4000.00 |
| LOW | 500.00 |
+---------------+-------------+
只为本次查询覆盖阈值为 2000（
=>=>
或
==
均可）：
SELECT * FROM semantic_view(
doc_test.sv_variables
DIMENSIONS sale_category
METRICS total_sales
VARIABLES min_amount => 2000.00
) ORDER BY sale_category;
+---------------+-------------+
| sale_category | total_sales |
+---------------+-------------+
| HIGH | 2500.00 |
| LOW | 2000.00 |
+---------------+-------------+
绑定值必须是常量。
VARIABLESVARIABLES
是查询里的最后一个子句，排在
WHEREWHERE
之后。声明时没有默认值的变量，只要被维度/指标引用就必须在查询时绑定，否则报错。
与传统 SQL 对比
同一分析需求，传统 SQL 与语义视图的写法对比：
传统 SQL （需手写 JOIN 和 GROUP BY）：
SELECT
e.dept,
d.manager AS manager_name,
COUNT(e.id) AS total_employees,
AVG(e.salary) AS avg_salary
FROM doc_test.employees e
JOIN doc_test.departments d ON e.dept = d.dept_name
GROUP BY e.dept, d.manager;
语义视图 （自动处理 JOIN 和聚合）：
SELECT * FROM semantic_view(
doc_test.emp_dept_analysis
DIMENSIONS emps.department, depts.manager_name
METRICS emps.total_employees, emps.avg_salary
);
相关文档
