SEMANTIC VIEW（Beta）

背景信息

开关与可观测性

SEMANTIC VIEW的查询能力与调试输出由以下GUC参数控制。

更多GUC参数的说明，请参见GUC参数。

您可以通过如下命令开启或关闭调试输出。

SET hg_semantic_view_rewrite_debug = on;   -- 排查时开启
RESET hg_semantic_view_rewrite_debug;

创建Semantic View

CREATE SEMANTIC VIEW [IF NOT EXISTS] [schema.]view_name
  TABLES ( alias AS [schema.]table_name [PRIMARY KEY (col1[, ...])] , ... )
  [RELATIONSHIPS ( [rel_name AS] from_alias(col[, ...]) REFERENCES to_alias[(col[, ...])] , ... )]
  [DIMENSIONS ( owner_alias.dim_name AS <expression> [COMMENT = '说明'] , ... )]
  [METRICS ( owner_alias.metric_name AS <aggregate_expression> [COMMENT = '说明'] , ... )]
  [COMMENT = '视图说明'];

DROP SEMANTIC VIEW [IF EXISTS] [schema.]view_name;

CREATE SEMANTIC VIEW sales_sv
  TABLES (
    o AS public.orders    PRIMARY KEY (order_id),
    c AS public.customers PRIMARY KEY (customer_id)
  )
  RELATIONSHIPS ( rel_oc AS o(customer_id) REFERENCES c(customer_id) )
  DIMENSIONS (
    o.status_dim AS o.status,
    c.city_dim   AS c.city COMMENT = '客户城市'
  )
  METRICS (
    o.total       AS sum(o.amount) COMMENT = '订单金额',
    o.order_count AS count(*),
    c.credit      AS sum(c.credit_limit)
  )
  COMMENT = '销售分析语义视图';

查询Semantic View

查询语义视图时，指标必须使用AGG(指标名)包裹，维度可直接引用并写入GROUP BY。查询示例如下。

-- 分组聚合
SELECT city_dim, AGG(total), AGG(credit) FROM sales_sv GROUP BY city_dim;

-- 全局聚合（无需 GROUP BY）
SELECT AGG(total), AGG(order_count) FROM sales_sv;

-- WHERE 过滤维度（只作过滤、不进入输出粒度）
SELECT city_dim, AGG(total) FROM sales_sv WHERE status_dim = 'completed' GROUP BY city_dim;

-- HAVING / ORDER BY / LIMIT
SELECT city_dim, AGG(total) AS revenue FROM sales_sv
GROUP BY city_dim HAVING AGG(total) > 100 ORDER BY revenue DESC LIMIT 10;

-- SELECT 支持标量表达式组合
SELECT upper(city_dim) AS city,
       AGG(total) / NULLIF(AGG(order_count), 0) AS avg_order_value,
       CASE WHEN AGG(total) > 1000 THEN 'high' ELSE 'normal' END AS lvl
FROM sales_sv GROUP BY city_dim;

查询时需注意以下要点。

• GROUP BY必须与SELECT输出的维度完全一致，不能多写，也不能漏写。

• 维度嵌套在表达式中时，GROUP BY仍写维度名。

• WHERE中不能使用指标，按聚合结果过滤请使用HAVING AGG(指标名)。

内省与YAML模型

Semantic View的定义持久化在系统表hologres.hg_semantic_view_properties中，该系统表包含schema_name、view_name、property_key和property_value四列，提供以下三类property_key。

您可以通过如下SQL列出当前Schema下的语义视图，或查看指定语义视图的YAML模型。

-- 列出当前 schema 下所有 Semantic View 及 owner
SELECT view_name, max(property_value) FILTER (WHERE property_key = 'owner') AS owner
FROM hologres.hg_semantic_view_properties
WHERE schema_name = current_schema() GROUP BY view_name;

-- 查看 YAML 语义模型
SELECT property_value AS model_yaml
FROM hologres.hg_semantic_view_properties
WHERE schema_name = current_schema()
  AND view_name = 'sales_sv' AND property_key = 'model_yaml';

model_yaml的结构示例如下，与DDL逐项对应，COMMENT的内容落为description字段。

name: sales_sv
description: 销售分析语义视图
tables:
- name: o
  base_table: {database: mydb, schema: public, table: orders}
  primary_key: {columns: [order_id]}
  dimensions:
  - {name: status_dim, expr: o.status}
  metrics:
  - {name: total, expr: sum(o.amount), description: 订单金额}
relationships:
- name: rel_oc
  left_table: o
  right_table: c
  relationship_columns: [{left_column: customer_id, right_column: customer_id}]
  relationship_type: many_to_one

如何确认生效与排查

您可以通过以下三步确认Semantic View已生效，并排查查询结果。

1. 确认对象存在：查询系统表hologres.hg_semantic_view_properties，确认其中存在该view_name对应的ddl_text。

2. 查看实际执行的SQL：执行SET hg_semantic_view_rewrite_debug = on;后再执行查询，NOTICE会输出改写后的物理SQL。多指标组场景下，可以看到多个WITH __hg_sv_xxx CTE，以及外层的LEFT JOIN ... ON NOT (q_0.dim IS DISTINCT FROM q_1.dim)（NULL-safe拼接）。

3. 校验指标未被放大：使用“先对明细去重、再聚合”的手写SQL作为基线，与语义视图的查询结果进行比对。

使用限制

SEMANTIC VIEW在建模和查询时存在以下限制。

建模建议

• 为每张表声明PRIMARY KEY：这是保证多表聚合正确性（去重保护）的基础。

• 关系方向要写对：from_alias必须是many侧，to_alias必须是one侧；写反会让引擎误判为一对多关系，导致重复聚合。

• 避免为同一对表定义多条关系：例如“出发机场”和“到达机场”两条flights → airports关系，会导致查询因路径歧义被拒绝；如确需区分，建议拆分为不同的Semantic View。

• 避免在一个查询中跨sibling分支：例如同时统计orders与addresses两条分支的指标，当前会被拒绝，可拆分为两个查询。

• 定义表达式时使用明确的对象名与无歧义的字面量：查询时会重新解析ddl_text，应避免依赖会话的search_path、时区等设置。

• 为维度和指标添加COMMENT：COMMENT的内容会写入model_yaml的description字段，可显著提升AI Agent与NL2SQL的理解准确率。

常见错误与替代写法

查询Semantic View时的常见错误写法、对应报错与正确写法如下。