管理语义视图
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
），不写则不出现该行。因此这两个属性的真实取值应以创建脚本为准。
权限控制
语义视图支持标准的 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） 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
查看权限
相关文档
