语义视图的组织与发现
建了很多语义视图之后，真正要的是让它们能被复用、能被信任：别人（包括未来的你）想要一个指标时，能找到已有的、不必重复造一个，而且看一眼就知道口径、敢直接用。组织和发现就是为这两件事服务的——组织决定指标好不好找（复用的前提），注释决定指标敢不敢用（信任的前提）。本文讲在当前产品能力下怎么做到。
复用与信任不会自动发生
语义视图目前没有内建的指标目录或跨视图搜索，能用的只有两个命令：
SHOW SEMANTIC VIEWS
SHOW SEMANTIC VIEWS
（只列视图名）和
DESC EXTENDED
DESC EXTENDED
（看单个视图的指标）。这意味着复用和信任
得靠你建视图时的命名和注释挣来，不会自动有：
- 命名规范让指标在
SHOW
SHOW
的列表里能被定位——这是别人发现并复用它的前提。
- COMMENT 让指标在
DESC EXTENDED
DESC EXTENDED
里能被读懂口径——这是别人敢用它的前提。
下面用一个销售域示例演示怎么落地。视图怎么从业务问题设计出来见设计方法，本文只讲建好之后如何组织和暴露。
前置准备
CREATE TABLE doc_org_cust (cust_id INT, cust_name STRING, region STRING);
CREATE TABLE doc_org_ord (order_id INT, cust_id INT, amount DECIMAL(12,2), status STRING, order_date DATE);
INSERT INTO doc_org_cust VALUES (1,'Alice','华东'),(2,'Bob','华北'),(3,'Carol','华东');
INSERT INTO doc_org_ord VALUES
(101,1,250.00,'已完成',DATE'2025-01-01'),
(102,1,150.00,'已退款',DATE'2025-02-01'),
(103,2,300.00,'已完成',DATE'2025-01-15');
按"一个分析主题一个视图"建三个视图，命名统一用
<业务域>_<主题>
<业务域>_<主题>
前缀，每个视图、维度、指标都写 COMMENT：
CREATE SEMANTIC VIEW sales_revenue
TABLES (
customers AS doc_org_cust PRIMARY KEY (cust_id) COMMENT '客户表',
orders AS doc_org_ord
PRIMARY KEY (order_id)
FOREIGN KEY (cust_id) REFERENCES customers
COMMENT '订单表'
)
DIMENSIONS (
customers.region AS customers.region COMMENT '客户所在地区',
customers.customer_name AS customers.cust_name COMMENT '客户名称'
)
METRICS (
orders.total_revenue AS SUM(orders.amount) COMMENT '销售总额（含退款订单）',
orders.avg_order_value AS AVG(orders.amount) COMMENT '平均订单金额'
)
COMMENT = '销售收入分析：按地区/客户看销售额，含退款口径';
CREATE SEMANTIC VIEW sales_fulfillment
TABLES ( orders AS doc_org_ord PRIMARY KEY (order_id) COMMENT '订单表' )
DIMENSIONS ( orders.status AS orders.status COMMENT '订单状态（已完成/已退款）' )
METRICS ( orders.order_count AS COUNT(orders.order_id) COMMENT '订单数' )
COMMENT = '订单履约分析：按状态统计订单数';
CREATE SEMANTIC VIEW cust_overview
TABLES ( customers AS doc_org_cust PRIMARY KEY (cust_id) COMMENT '客户表' )
DIMENSIONS ( customers.region AS customers.region COMMENT '客户所在地区' )
METRICS ( customers.customer_count AS COUNT(customers.cust_id) COMMENT '客户数' )
COMMENT = '客户概览：按地区统计客户数';
组织：一个分析主题一个视图
不要把所有表和指标塞进一个巨型视图。一个语义视图应对应一个清晰的分析主题（如"销售收入""订单履约""客户概览"），聚焦的视图更好维护、查询粒度也更可控。
拆分时遵循三条原则：
- 一个主题一个视图：上面把收入、履约、客户拆成了三个独立视图，而不是一个大视图。
- 会冲突的分支拆开：如果两组指标分属同一父表的不同一对多分支（如订单和地址），放进同一视图查询时会触发 chasm trap 报错。把它们拆到不同视图各自分析。详见关系建模与聚合粒度。
- 控制单视图的表数量：建议从 3-5 张核心表起步，验证准确后再扩展。
命名规范：让指标能被找到（复用）
复用的第一步是"别人能找到你建过的视图"。但
SHOW SEMANTIC VIEWS IN <架构名>
SHOW SEMANTIC VIEWS IN <架构名>
只给视图名：
SHOW SEMANTIC VIEWS IN public;
+-------------+-------------------+
| schema_name | table_name |
+-------------+-------------------+
| public | cust_overview |
| public | sales_fulfillment |
| public | sales_revenue |
+-------------+-------------------+
注意这个输出只有视图名，没有注释、没有指标列表，而且按名字字母序排列。这意味着视图名本身是你扫一眼能用上的唯一信息。统一的
<业务域>_<主题>
<业务域>_<主题>
前缀让同域视图在列表里自然聚在一起——上面
sales_revenue
sales_revenue
和
sales_fulfillment
sales_fulfillment
相邻，一眼能看出都是销售域。
⚠️ 注意：
SHOW SEMANTIC VIEWS
SHOW SEMANTIC VIEWS
不支持
LIKE
LIKE
过滤（加
LIKE 'sales%'
LIKE 'sales%'
会返回空），也没有跨 schema 的全局列表。视图分布在多个 schema 时，需要逐个 schema 执行
SHOW
SHOW
。
注释：让指标敢被使用（信任）
找到视图后，使用者要判断"这个指标算的是不是我要的、敢不敢用"。能回答这个问题的只有
DESC EXTENDED
DESC EXTENDED
：
DESC EXTENDED sales_revenue;
+----------------------+----------------------------+----------------------------+
| column_name | data_type | comment |
+----------------------+----------------------------+----------------------------+
| # detailed table information |
| name | sales_revenue | |
| comment | 销售收入分析：按地区/客户看销售额，含退款口径 | |
| type | SEMANTIC VIEW | |
| #logical tables |
| customers | public.doc_org_cust | 客户表 |
| primary key | cust_id | |
| orders | public.doc_org_ord | 订单表 |
| primary key | order_id | |
| foreign key | cust_id REFERENCE customers(cust_id) | |
| #dimensions |
| customers.region | customers.region | 客户所在地区 |
| customers.customer_name | customers.cust_name | 客户名称 |
| #metrics |
| orders.total_revenue | `sum`(orders.amount) | 销售总额（含退款订单） |
| orders.avg_order_value | `avg`(orders.amount) | 平均订单金额 |
+----------------------+----------------------------+----------------------------+
DESC EXTENDED
DESC EXTENDED
是唯一能看到指标和注释的命令。
comment
comment
列让每个指标自描述——比如
total_revenue
total_revenue
的注释写明了"含退款订单"，使用者无需追代码就知道口径。所以建视图时：
- 每个视图、维度、指标都写 COMMENT，指标的注释尤其要写清口径（包含/排除什么、按什么时间点）。没有注释的指标，事后基本无法辨识。
- 维度和指标用业务术语命名，而不是物理列名缩写。
⚠️ 注意：
WITH SYNONYMS
WITH SYNONYMS
、
is_unique
is_unique
、
is_time
is_time
、
enum_values
enum_values
这些子句不会出现在
DESC EXTENDED
DESC EXTENDED
输出里，无法用于发现，别指望它们帮助检索。详见
能力与限制参考。
发现工作流：建新指标前先查有没有现成的
避免重复造轮子的关键动作，是在建一个新指标前先查一遍是不是已经有人建过。在现有能力下，这个流程是两步：
SHOW SEMANTIC VIEWS IN <架构名>
SHOW SEMANTIC VIEWS IN <架构名>
列出视图，借命名前缀缩小到目标业务域。- 对候选视图执行
DESC EXTENDED
DESC EXTENDED
，在 #metrics
#metrics
段按注释确认是不是你要的指标和口径——若已有且口径一致，直接复用，不要再建一个。
这个流程在视图数量可控、命名和注释规范的前提下够用。但要清楚它的边界：没有"搜索指标名"的能力，视图很多时只能逐个
DESC
DESC
。
用治理弥补产品缺口
当语义视图增长到几十上百个，仅靠
SHOW
SHOW
+
DESC
DESC
翻找会变得低效。当前产品没有指标目录，建议用外部治理手段补齐：
- 维护一份指标登记表（团队 wiki 或表格）：记录每个指标名、所属视图、口径定义、负责人。新建视图时同步登记。
- 配合统一的命名规范和COMMENT 规范，让登记表、视图名、注释三者口径一致。
命名规范让
SHOW
SHOW
的结果可读，COMMENT 让
DESC
DESC
的结果可懂，外部登记表补上跨视图检索——三者配合是当前规模化使用语义视图的可行方式。
相关文档
