管理语义视图
DROP SEMANTIC VIEW
删除指定的语义视图。
语法 ：
DROP SEMANTIC VIEW [ IF EXISTS ] <视图名称>;
IF EXISTSIF EXISTS
可防止视图不存在时报错，建议在脚本中始终加上。
示例 ：
DROP SEMANTIC VIEW IF EXISTS doc_test.emp_dept_analysis;
ALTER SEMANTIC VIEW
ALTER SEMANTIC VIEWALTER SEMANTIC VIEW
支持三类操作：
RENAME TORENAME TO
重命名、
SET PROPERTIESSET PROPERTIES
设置属性、
UNSET PROPERTIESUNSET PROPERTIES
删除属性。它
不支持 通过 SQL 动态增减维度、指标或修改注释——需要修改维度/指标/逻辑表结构时，用
CREATE OR REPLACE SEMANTIC VIEWCREATE OR REPLACE SEMANTIC VIEW
重放完整定义（见"修改语义视图结构"）。
RENAME TO
语法 ：
ALTER SEMANTIC VIEW <视图名称> RENAME TO <新名称>;
新名称不能带 schema 前缀，重命名后视图仍在原 schema 下。
示例 ：
ALTER SEMANTIC VIEW emp_dept_analysis RENAME TO emp_dept_v2;
SET / UNSET PROPERTIES
为语义视图设置或删除自定义属性（key-value）。属性可通过
DESC EXTENDEDDESC EXTENDED
的
propertiesproperties
行读回，常用于把视图的元数据或权威定义存放在视图对象自身。
语法 ：
ALTER SEMANTIC VIEW <视图名称> SET PROPERTIES ( '<键>' = '<值>' [ , ... ] );
ALTER SEMANTIC VIEW <视图名称> UNSET PROPERTIES ( '<键>' [ , ... ] );
SET PROPERTIESSET PROPERTIES
是合并（upsert）语义，只更新指定的键，不影响其他已有键；删除某个键需用
UNSET PROPERTIESUNSET PROPERTIES
。
CREATE SEMANTIC VIEWCREATE SEMANTIC VIEW
不支持
PROPERTIESPROPERTIES
子句，属性只能在视图创建后通过
ALTER ... SET PROPERTIESALTER ... SET PROPERTIES
设置。
示例 ：
ALTER SEMANTIC VIEW emp_dept_analysis SET PROPERTIES ('owner' = 'analytics_team', 'spec_version' = '2');
ALTER SEMANTIC VIEW emp_dept_analysis UNSET PROPERTIES ('spec_version');
⚠️ 注意 ：
DESC EXTENDEDDESC EXTENDED
的
propertiesproperties
展示是描述性输出，会
丢失属性值中的单引号 （例如存入
COMMENT = 'x'COMMENT = 'x'
读回会变成
COMMENT = xCOMMENT = x
），换行也会转为字面
\n\n
。如果属性里要存放完整 DDL、JSON 等含引号或换行的内容，应先做
base64 编码 再存入——base64 只含
[A-Za-z0-9+/=][A-Za-z0-9+/=]
，可字节级精确往返。
修改语义视图结构
语义视图不支持通过
ALTERALTER
增删维度/指标（无
ALTER ... ADD DIMENSIONALTER ... ADD DIMENSION
、
ALTER ... ADD METRICALTER ... ADD METRIC
等命令）。修改维度、指标、逻辑表或注释，用
CREATE OR REPLACE SEMANTIC VIEWCREATE OR REPLACE SEMANTIC VIEW
重放完整定义即可，无需先
DROPDROP
，替换是原子操作、脚本天然幂等。
推荐流程：
用 SHOW CREATE SEMANTIC VIEW <视图名>SHOW CREATE SEMANTIC VIEW <视图名>
取回当前完整 DDL（见下文）
在 DDL 上编辑，加入需要新增或修改的部分
执行 CREATE OR REPLACE SEMANTIC VIEWCREATE OR REPLACE SEMANTIC VIEW
示例：在已有视图上增加一个新指标
max_salarymax_salary
：
-- 直接 CREATE OR REPLACE，加入 emps.max_salary
CREATE OR REPLACE SEMANTIC VIEW doc_test.emp_dept_analysis
TABLES (
depts AS doc_test.departments PRIMARY KEY (dept_name),
emps AS doc_test.employees
PRIMARY KEY (id)
FOREIGN KEY (dept) REFERENCES depts (dept_name)
)
DIMENSIONS (
emps.department AS emps.dept COMMENT = '所在部门',
emps.employee_name AS emps.name COMMENT = '员工姓名'
)
METRICS (
emps.total_employees AS COUNT(emps.id) COMMENT = '员工总数',
emps.avg_salary AS AVG(emps.salary) COMMENT = '平均薪资',
emps.max_salary AS MAX(emps.salary) COMMENT = '最高薪资' -- 新增
)
COMMENT = '员工部门分析语义视图';
SHOW CREATE SEMANTIC VIEW
回读语义视图的完整、可重放
CREATECREATE
DDL，是修改结构前取回定义的首选方式。
语法 ：
SHOW CREATE SEMANTIC VIEW <视图名称>;
示例 ：
SHOW CREATE SEMANTIC VIEW doc_test.emp_dept_analysis;
返回单列
sqlsql
，内容是可直接执行的
CREATE SEMANTIC VIEWCREATE SEMANTIC VIEW
语句：
CREATE SEMANTIC VIEW quick_start.doc_test.emp_dept_analysis
TABLES (
depts AS quick_start.doc_test.departments
PRIMARY KEY (dept_name),
emps AS quick_start.doc_test.employees
PRIMARY KEY (id)
)
RELATIONSHIPS (
emps (dept) REFERENCES depts (dept_name)
)
DIMENSIONS (
emps.employee_name AS emps.name WITH SYNONYMS('员工姓名','staff name') COMMENT '员工姓名',
emps.department AS emps.dept COMMENT '所在部门',
emps.hire_year AS `year`(emps.hire_date) COMMENT '入职年份',
depts.manager_name AS depts.manager COMMENT '部门经理'
)
METRICS (
emps.total_employees AS `count`(emps.id) COMMENT '员工总数',
emps.avg_salary AS `avg`(emps.salary) COMMENT '平均薪资',
emps.max_salary AS `max`(emps.salary) COMMENT '最高薪资'
)
COMMENT '员工部门分析语义视图';
⚠️ 注意 ：创建时写在逻辑表内的内联
FOREIGN KEY (...) REFERENCES ...FOREIGN KEY (...) REFERENCES ...
，回读时会被规范化为独立的
RELATIONSHIPS (...)RELATIONSHIPS (...)
子句（语法为
<引用表> (<外键列>) REFERENCES <被引用表> (<列>)<引用表> (<外键列>) REFERENCES <被引用表> (<列>)
）。两种写法等价，
CREATE OR REPLACECREATE OR REPLACE
时两种都能接受。
⚠️ 注意 ：
SHOW CREATESHOW CREATE
回读的 DDL 不含
is_uniqueis_unique
、
is_timeis_time
、
enum_valuesenum_values
这几个维度元数据子句；需要查看它们用
DESC EXTENDEDDESC EXTENDED
（但其
is_uniqueis_unique
/
is_timeis_time
回读值不保真，见"DESC EXTENDED"）。
SHOW SEMANTIC VIEWS
列出指定 schema 下所有语义视图，返回
schema_nameschema_name
和
table_nametable_name
两列。
语法 ：
SHOW SEMANTIC VIEWS [ IN <架构名> ];
建议始终加
IN <架构名>IN <架构名>
，不加时返回当前默认 schema 下的视图。
⚠️ 注意 ：
SHOW SEMANTIC VIEWSSHOW SEMANTIC VIEWS
不支持
LIKELIKE
过滤（加
LIKE 'x%'LIKE 'x%'
会返回空），也没有跨 schema 的全局列表，视图分布在多个 schema 时需逐个 schema 执行。
示例 ：
SHOW SEMANTIC VIEWS IN doc_test;
+-------------+-------------------+
| schema_name | table_name |
+-------------+-------------------+
| doc_test | emp_dept_analysis |
+-------------+-------------------+
也可以通过
information_schema.tablesinformation_schema.tables
查询普通表的元数据，但语义视图对象不在该视图中——语义视图的元数据通过
SHOW SEMANTIC VIEWSSHOW SEMANTIC VIEWS
和
DESC EXTENDEDDESC EXTENDED
获取。
DESC EXTENDED
查看语义视图的完整定义，包括逻辑表结构、主外键关系、维度元数据和指标定义。
注意 ：
DESC <视图名称>DESC <视图名称>
（不加
EXTENDEDEXTENDED
）返回空结果，必须加
EXTENDEDEXTENDED
。
DESC SEMANTIC VIEWDESC SEMANTIC VIEW
/
DESCRIBE SEMANTIC VIEWDESCRIBE SEMANTIC VIEW
命令虽然存在但目前也返回空，同样要用
DESC EXTENDEDDESC EXTENDED
。
语法 ：
DESC EXTENDED <视图名称>;
示例 ：
DESC EXTENDED doc_test.emp_dept_analysis;
输出按
# detailed table information# detailed table information
、
#logical tables#logical tables
、
#relationships#relationships
、
#dimensions#dimensions
、
#metrics#metrics
五段组织，每行三列（
column_namecolumn_name
、
data_typedata_type
、
commentcomment
）。主键在逻辑表行下方以
primary keyprimary key
附加行列出，外键关系单独归入
#relationships#relationships
段：
+------------------------------+----------------------------------+---------------------------------+
| column_name | data_type | comment |
+------------------------------+----------------------------------+---------------------------------+
| # detailed table information | | |
| workspace | <workspace> | |
| schema | doc_test | |
| name | emp_dept_analysis | |
| creator | <用户名> | |
| created_time | 2026-08-10 16:13:40.584 | |
| last_modified_time | 2026-08-10 16:13:40.591 | |
| comment | 员工部门分析语义视图 | |
| properties | () | |
| version | -1 | |
| type | SEMANTIC VIEW | |
| #logical tables | | |
| depts | doc_test.departments | |
| | primary key | dept_name |
| emps | doc_test.employees | |
| | primary key | id |
| #relationships | | |
| | emps | dept REFERENCE depts(dept_name) |
| #dimensions | | |
| emps.employee_name | emps.name | 员工姓名 |
| | synonyms | 员工姓名,staff name |
| | is_unique | true |
| emps.department | emps.dept | 所在部门 |
| emps.hire_year | `year`(emps.hire_date) | 入职年份 |
| | is_time | true |
| depts.manager_name | depts.manager | 部门经理 |
| #metrics | | |
| emps.total_employees | `count`(emps.id) | 员工总数 |
| emps.avg_salary | `avg`(emps.salary) | 平均薪资 |
| emps.max_salary | `max`(emps.salary) | 最高薪资 |
+------------------------------+----------------------------------+---------------------------------+
外键关系归入独立的
#relationships#relationships
段，每行列出引用方逻辑表名和
<外键列> REFERENCE <被引用表>(<列>)<外键列> REFERENCE <被引用表>(<列>)
的关系描述。
versionversion
行是内部版本标识，
CREATE OR REPLACECREATE OR REPLACE
覆盖后仍显示
-1-1
，不用于追踪修改次数。
⚠️ 注意 ：
DESC EXTENDEDDESC EXTENDED
的维度段会在维度行下方以附加行列出
synonymssynonyms
、
is_uniqueis_unique
、
is_timeis_time
、
enum_valuesenum_values
等元数据。其中
synonymssynonyms
、
enum_valuesenum_values
回读值与创建一致；但
is_uniqueis_unique
、
is_timeis_time
只反映"是否声明过"——只要创建时写了该子句就回读为
truetrue
（即使写的是
= false= false
），不写则不出现该行。因此这两个属性的真实取值应以创建脚本为准。
查看视图结构（内省命令）
DESC EXTENDEDDESC EXTENDED
/
SHOW CREATESHOW CREATE
返回的是一整段文本，适合人读。要
按对象逐行 取回视图结构（有哪些维度、能聚合什么、表怎么关联），用下面五条内省命令，它们返回结构化、每对象一行的元数据，便于程序或 AI Agent 精确发现视图结构，无需解析 DDL 文本：
SHOW SEMANTIC DIMENSIONS IN <视图> [ FOR METRIC <指标> ]
SHOW SEMANTIC METRICS IN <视图>
SHOW SEMANTIC FACTS IN <视图>
SHOW SEMANTIC RELATIONSHIPS IN <视图>
SHOW SEMANTIC TABLES IN <视图>
DIMENSIONSDIMENSIONS
、
METRICSMETRICS
、
FACTSFACTS
三者返回相同的 9 列：
workspace_nameworkspace_name
、
schema_nameschema_name
、
semantic_view_namesemantic_view_name
、
table_nametable_name
、
namename
、
data_typedata_type
、
synonymssynonyms
、
commentcomment
、
accessaccess
（
PUBLICPUBLIC
/
PRIVATEPRIVATE
）。
RELATIONSHIPSRELATIONSHIPS
和
TABLESTABLES
的列不同（见下）。
⚠️ 注意 ：返回的
table_nametable_name
、
namename
均为
大写 （如
EMPSEMPS
、
EMPLOYEE_NAMEEMPLOYEE_NAME
），是逻辑表别名/对象名的规范化形式；查询
semantic_view()semantic_view()
时用小写或原始大小写都可以。
以
doc_test.emp_dept_analysisdoc_test.emp_dept_analysis
为例，
SHOW SEMANTIC DIMENSIONSSHOW SEMANTIC DIMENSIONS
返回：
+----------------+-------------+--------------------+------------+---------------+-----------+----------------------+----------+--------+
| workspace_name | schema_name | semantic_view_name | table_name | name | data_type | synonyms | comment | access |
+----------------+-------------+--------------------+------------+---------------+-----------+----------------------+----------+--------+
| quick_start | doc_test | emp_dept_analysis | DEPTS | MANAGER_NAME | string | | 部门经理 | PUBLIC |
| quick_start | doc_test | emp_dept_analysis | EMPS | DEPARTMENT | string | | 所在部门 | PUBLIC |
| quick_start | doc_test | emp_dept_analysis | EMPS | EMPLOYEE_NAME | string | 员工姓名, staff name | 员工姓名 | PUBLIC |
| quick_start | doc_test | emp_dept_analysis | EMPS | HIRE_YEAR | int | | 入职年份 | PUBLIC |
+----------------+-------------+--------------------+------------+---------------+-----------+----------------------+----------+--------+
SHOW SEMANTIC RELATIONSHIPSSHOW SEMANTIC RELATIONSHIPS
返回外键关系，列为
workspace_nameworkspace_name
、
schema_nameschema_name
、
semantic_view_namesemantic_view_name
、
relationship_namerelationship_name
、
table_nametable_name
、
columnscolumns
、
ref_table_nameref_table_name
、
ref_columnsref_columns
、
relationship_typerelationship_type
：
+----------------+-------------+--------------------+-------------------+------------+---------+----------------+-------------+-------------------+
| workspace_name | schema_name | semantic_view_name | relationship_name | table_name | columns | ref_table_name | ref_columns | relationship_type |
+----------------+-------------+--------------------+-------------------+------------+---------+----------------+-------------+-------------------+
| quick_start | doc_test | emp_dept_analysis | | EMPS | dept | DEPTS | dept_name | MANY_TO_ONE |
+----------------+-------------+--------------------+-------------------+------------+---------+----------------+-------------+-------------------+
relationship_typerelationship_type
反映外键推断出的关系基数（一对多外键为
MANY_TO_ONEMANY_TO_ONE
，从子表看向父表）。
SHOW SEMANTIC TABLESSHOW SEMANTIC TABLES
返回逻辑表到物理表的映射，列为
workspace_nameworkspace_name
、
schema_nameschema_name
、
semantic_view_namesemantic_view_name
、
table_nametable_name
、
base_tablebase_table
、
primary_keyprimary_key
、
synonymssynonyms
、
commentcomment
：
+----------------+-------------+--------------------+------------+-------------+-------------+----------+---------+
| workspace_name | schema_name | semantic_view_name | table_name | base_table | primary_key | synonyms | comment |
+----------------+-------------+--------------------+------------+-------------+-------------+----------+---------+
| quick_start | doc_test | emp_dept_analysis | DEPTS | departments | dept_name | | NULL |
| quick_start | doc_test | emp_dept_analysis | EMPS | employees | id | | NULL |
+----------------+-------------+--------------------+------------+-------------+-------------+----------+---------+
FOR METRICFOR METRIC
粒度安全过滤
SHOW SEMANTIC DIMENSIONS ... FOR METRIC <指标>SHOW SEMANTIC DIMENSIONS ... FOR METRIC <指标>
只返回可
合法用于分组该指标 的维度（与指标同粒度或更粗），据此可直接构造不会触发下钻报错的查询。以粒度阶梯视图
sv_grainsv_grain
（region→customer→orders→lineitem）为例，
order_amountorder_amount
是 orders 粒度的指标：
SHOW SEMANTIC DIMENSIONS IN doc_test.sv_grain FOR METRIC order_amount;
返回 region、customer、orderkey 三个维度（等于或更粗），过滤掉了更细的 lineitem 维度 ——因为用 lineitem 粒度分组 orders 指标会触发扇出下钻，属非法。换成最细的
line_revenueline_revenue
（lineitem 粒度）指标，则四个维度全部返回。粒度规则的完整说明见
能力与限制参考 的"跨表指标与粒度"。
💡 提示 ：视图未定义某类对象时返回空行（如没有
FACTSFACTS
时
SHOW SEMANTIC FACTSSHOW SEMANTIC FACTS
返回 0 行），属正常。
权限控制
语义视图支持标准的 GRANT/REVOKE 权限管理，但只支持只读权限（
SELECTSELECT
、
ALLALL
），不支持
INSERTINSERT
、
UPDATEUPDATE
、
DELETEDELETE
。
GRANT
-- 授予角色查询权限
GRANT SELECT ON SEMANTIC VIEW doc_test.emp_dept_analysis TO ROLE test_readonly_role;
-- 授予所有权限（等同于 SELECT）
GRANT ALL ON SEMANTIC VIEW doc_test.emp_dept_analysis TO ROLE workspace_dev;
REVOKE
REVOKE SELECT ON SEMANTIC VIEW doc_test.emp_dept_analysis FROM ROLE test_readonly_role;
SHOW GRANTS
查看语义视图上的权限授予情况：
SHOW GRANTS ON SEMANTIC VIEW doc_test.emp_dept_analysis;
返回列：
granted_typegranted_type
、
privilegeprivilege
、
conditionsconditions
、
granted_ongranted_on
（值为
SEMANTIC_VIEWSEMANTIC_VIEW
）、
object_nameobject_name
、
granted_togranted_to
、
grantee_namegrantee_name
、
grantor_namegrantor_name
、
grant_optiongrant_option
、
granted_timegranted_time
。
命令速查
命令 说明 CREATE OR REPLACE SEMANTIC VIEWCREATE OR REPLACE SEMANTIC VIEW
原子替换视图定义（改结构用它） SHOW CREATE SEMANTIC VIEWSHOW CREATE SEMANTIC VIEW
回读完整可重放 DDL DROP SEMANTIC VIEW IF EXISTSDROP SEMANTIC VIEW IF EXISTS
删除语义视图 ALTER SEMANTIC VIEW ... RENAME TOALTER SEMANTIC VIEW ... RENAME TO
重命名 ALTER SEMANTIC VIEW ... SET PROPERTIESALTER SEMANTIC VIEW ... SET PROPERTIES
设置属性（合并语义） ALTER SEMANTIC VIEW ... UNSET PROPERTIESALTER SEMANTIC VIEW ... UNSET PROPERTIES
删除属性 SHOW SEMANTIC VIEWS [ IN schema ]SHOW SEMANTIC VIEWS [ IN schema ]
列出语义视图 DESC EXTENDEDDESC EXTENDED
查看完整结构（必须加 EXTENDED） SHOW SEMANTIC DIMENSIONS IN <视图> [ FOR METRIC <指标> ]SHOW SEMANTIC DIMENSIONS IN <视图> [ FOR METRIC <指标> ]
逐行列出维度，FOR METRIC 只返回粒度安全维度 SHOW SEMANTIC METRICS IN <视图>SHOW SEMANTIC METRICS IN <视图>
逐行列出指标 SHOW SEMANTIC FACTS IN <视图>SHOW SEMANTIC FACTS IN <视图>
逐行列出事实 SHOW SEMANTIC RELATIONSHIPS IN <视图>SHOW SEMANTIC RELATIONSHIPS IN <视图>
逐行列出外键关系 SHOW SEMANTIC TABLES IN <视图>SHOW SEMANTIC TABLES IN <视图>
逐行列出逻辑表到物理表的映射 GRANT SELECT ON SEMANTIC VIEWGRANT SELECT ON SEMANTIC VIEW
授予查询权限 REVOKE SELECT ON SEMANTIC VIEWREVOKE SELECT ON SEMANTIC VIEW
撤销查询权限 SHOW GRANTS ON SEMANTIC VIEWSHOW GRANTS ON SEMANTIC VIEW
查看权限
相关文档
