管理语义视图
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
（会报
only view/stream/materialized view support replaceonly view/stream/materialized view support replace
）——如需修改维度/指标/逻辑表结构，仍需
DROPDROP
后重建。
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+/=]
，可字节级精确往返。
修改语义视图结构
语义视图不支持直接修改结构（无
ALTER ... ADD DIMENSIONALTER ... ADD DIMENSION
、
ALTER ... ADD METRICALTER ... ADD METRIC
等命令）。修改维度、指标、逻辑表或注释，需要 DROP 后重建。
重建的基础是原始创建脚本 。语义视图没有
SHOW CREATESHOW CREATE
或 YAML 导出功能，
DESC EXTENDEDDESC EXTENDED
只返回结构描述，不是可执行的 SQL。因此建议在首次创建时就把脚本保存到 Studio 任务或版本控制中，作为后续修改的起点。
推荐流程：
取出原始创建脚本
在脚本上编辑，加入需要新增或修改的部分
执行 DROP SEMANTIC VIEW IF EXISTSDROP SEMANTIC VIEW IF EXISTS
+ CREATE SEMANTIC VIEWCREATE SEMANTIC VIEW
示例：在已有视图上增加一个新指标
max_salarymax_salary
：
-- 在原始创建脚本基础上，加入 emps.max_salary 后重建
DROP SEMANTIC VIEW IF EXISTS doc_test.emp_dept_analysis;
CREATE 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 = '员工部门分析语义视图';
如果原始脚本已丢失，可以用
DESC EXTENDED <视图名>DESC EXTENDED <视图名>
读回当前结构作为参考，再手动重写创建脚本。
DESC EXTENDEDDESC EXTENDED
会列出逻辑表、主外键关系、维度和指标，但格式是描述性输出，不能直接执行，且不包含
is_uniqueis_unique
、
is_timeis_time
、
WITH SYNONYMSWITH SYNONYMS
等元数据属性。
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
。对标 Snowflake 的
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
、
#dimensions#dimensions
、
#metrics#metrics
四段组织，每行三列（
column_namecolumn_name
、
data_typedata_type
、
commentcomment
）：
+----------------------+-------------------------------------------+--------------+
| column_name | data_type | comment |
+----------------------+-------------------------------------------+--------------+
| # detailed table information |
| workspace | <workspace> | |
| schema | doc_test | |
| name | emp_dept_analysis | |
| creator | <用户名> | |
| created_time | 2026-06-12 22:56:13.413 | |
| last_modified_time | 2026-06-12 22:56:13.425 | |
| comment | 员工部门分析语义视图 | |
| type | SEMANTIC VIEW | |
| #logical tables |
| depts | doc_test.departments | |
| primary key | dept_name | |
| emps | doc_test.employees | |
| primary key | id | |
| foreign key | dept REFERENCE depts(dept_name) | |
| #dimensions |
| emps.department | emps.dept | 所在部门 |
| emps.hire_year | `year`(emps.hire_date) | 入职年份 |
| depts.manager_name | depts.manager | 部门经理 |
| #metrics |
| emps.total_employees | `count`(emps.id) | 员工总数 |
| emps.avg_salary | `avg`(emps.salary) | 平均薪资 |
| emps.max_salary | `max`(emps.salary) | 最高薪资 |
+----------------------+-------------------------------------------+--------------+
⚠️ 注意 ：
DESC EXTENDEDDESC EXTENDED
的维度段只返回维度名、表达式和注释三列，
不显示 is_uniqueis_unique
、
is_timeis_time
、
enum_valuesenum_values
这些元数据属性。创建时设置的这些属性目前无法通过
DESC EXTENDEDDESC EXTENDED
读回，定义自身请以创建脚本为准来源。
权限控制
语义视图支持标准的 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
。
命令速查
命令 说明 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
查看权限
相关文档
