语义YAML内容规范-云原生数据仓库AnalyticDB(AnalyticDB)-阿里云帮助中心

语义视图支持通过YAML规范定义业务概念。您可以编写YAML文件，使用CREATE OR REPLACE SEMANTIC VIEW语句从YAML规范创建语义视图，在数据之上建立业务语义层，使用户能够以业务术语更轻松地查询和分析数据。

YAML格式总览

语义视图的YAML规范包含以下顶层字段：

name：语义视图的名称。
description：语义视图的描述。
synonyms：同义词数组。
tables：逻辑表数组，可包含一个或多个逻辑表定义。
relationships：视图级关系数组，定义逻辑表之间的关系。
metrics：视图级派生指标数组，组合来自多个表的指标。

完整的YAML语法模板如下：

# 语义视图的名称和描述
name: <name>
description: <string>
synonyms: <array of strings>
# 逻辑表级概念
# 语义视图可包含一个或多个逻辑表
tables:
  - name: <name>
    description: <string>
    synonyms: <array of strings>
    # 基表的完全限定名
    base_table:
      schema: <schema>
      table: <base table name>
    # 逻辑表中的维度列
    dimensions:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        expr: <SQL expression>
        data_type: <data type>
        is_enum: <boolean>
    # 逻辑表中的事实列
    facts:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        expr: <SQL expression>
        data_type: <data type>
    # 限定于逻辑表的常规指标
    metrics:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        expr: <SQL expression>
        using_relationships:
        - <relationship_name>
# 视图级概念
# 逻辑表之间的关系
relationships:
  - name: <string>
    synonyms: <array of strings>
    left_table: <table>
    right_table: <table>
    relationship_columns:
      - left_column: <column>
        right_column: <column>
# 限定于语义视图的派生指标
# 派生指标组合来自多个表的指标
metrics:
  - name: <name>
    synonyms: <array of strings>
    description: <string>
    expr: <SQL expression>

关键概念详解

同义词/别名（synonyms）

synonyms是所有语义对象的公共属性，用于定义语义对象的同义词、别名或替代名称，类型为字符串数组。该属性可作用于语义视图、逻辑表、维度、事实、指标、关系等所有语义对象。

通过定义同义词，用户可以使用不同的业务术语引用同一个语义对象，提升查询的灵活性。

表（Tables）

逻辑表代表业务实体（如客户、订单或产品），并映射到物理数据库表。每个逻辑表可定义基础表、主键和描述。

逻辑表的主要字段如下：

字段	说明
`name`	逻辑表名称。
`description`	逻辑表描述。
`synonyms`	同义词数组。
`base_table`	基础表配置，包含`schema`（数据库名）和`table`（物理表名）两个子字段。
`primary_key`	主键字段。

每个逻辑表内部还可以定义维度（dimensions）、事实（facts）、指标（metrics）。

维度（Dimensions）

维度代表为分析提供上下文的分类属性，回答"谁""什么""哪里""何时"等问题。

维度字段说明如下：

字段	是否必选	说明
`name`	是	维度名称。
`expr`	是	SQL表达式，用于从物理列计算维度值。
`data_type`	否	数据类型。
`synonyms`	否	同义词数组。
`description`	否	维度的文本描述。对于时间维度，建议包含时区信息等上下文。
`sample_values`	否	示例值列表。
`is_enum`	否	布尔值。如果设为`true`，则`sample_values`将被视为所有可能值的完整列表（枚举维度）。

事实（Facts）

事实列是行级定量属性，代表特定的业务事件或交易。事实通常在语义视图中作为"辅助"概念，帮助构建维度和指标。

事实字段说明如下：

字段	说明
`name`	事实名称。
`synonyms`	同义词数组。
`description`	事实的文本描述。
`expr`	SQL表达式，映射到物理列。
`data_type`	数据类型。

指标（Metrics）

指标是通过使用SUM、AVG和COUNT等聚合函数对事实或其他列进行聚合而计算的业务性能可量化度量。

语义视图支持两种类型的指标：

表级指标：定义在特定逻辑表内，限定于该表的作用域。
派生指标：定义在视图的顶层metrics数组中，不绑定到特定表，可组合来自多个表的指标。

表级指标

表级指标字段说明如下：

字段	说明
`name`	指标名称。
`synonyms`	同义词数组。
`description`	指标的文本描述。
`expr`	带聚合函数的SQL表达式，例如`SUM(o_totalprice)`或`COUNT(*)`。
`using_relationships`	当两个逻辑表之间存在多个关系路径时，使用此字段指定要使用的关系路径。

派生指标

派生指标定义在YAML顶层的metrics数组中，不绑定到特定表，可以组合来自多个逻辑表的指标。

例如，以下派生指标通过组合orders表和customers表的指标计算每位客户的平均收入：

metrics:
  - name: revenue_per_customer
    description: "Average revenue per customer"
    expr: orders.total_revenue / customers.customer_count

关系（Relationships）

关系定义在YAML顶层的relationships数组中，用于描述逻辑表之间的连接方式。

关系字段说明如下：

字段	说明
`name`	关系名称。
`synonyms`	同义词数组。
`left_table`	左表名称。
`right_table`	右表名称。
`relationship_columns`	列对数组，每对包含`left_column`和`right_column`，定义左表和右表的关联列。

说明

语义视图不需要传统语义模型中使用的join_type或relationship_type字段。关系类型（一对一、多对多等）会自动从数据和主键定义中推断。

完整示例

以下示例定义了一个名为revenue_analysis的语义视图，用于分析产品和客户的收入情况。该语义视图包含customers和orders两个逻辑表，定义了维度、事实、指标以及表之间的关系，还包含一个派生指标revenue_per_customer。

name: revenue_analysis
description: "Semantic view for analyzing revenue across products and customers"

tables:
  - name: customers
    description: "Customer information"
    base_table:
      schema: sales_db
      table: customers
    dimensions:
      - name: customer_name
        synonyms: ["client name", "customer"]
        description: "Full name of the customer"
        expr: c_name
        data_type: VARCHAR
      - name: customer_segment
        synonyms: ["segment", "market segment"]
        description: "Customer market segment"
        expr: c_mktsegment
        data_type: VARCHAR
        is_enum: true
    metrics:
      - name: customer_count
        description: "Total number of customers"
        expr: COUNT(c_custkey)

  - name: orders
    description: "Order information"
    base_table:
      schema: sales_db
      table: orders
    dimensions:
      - name: order_date
        description: "Date when order was placed"
        expr: o_orderdate
        data_type: DATE
      - name: order_year
        description: "Year when order was placed"
        expr: YEAR(o_orderdate)
        data_type: NUMBER
    facts:
      - name: order_total
        description: "Total order amount"
        expr: o_totalprice
        data_type: NUMBER
    metrics:
      - name: total_orders
        description: "Total number of orders"
        expr: COUNT(*)
      - name: total_revenue
        description: "Total revenue of orders"
        expr: SUM(o_totalprice)
      - name: average_order_value
        description: "Average order value"
        expr: AVG(o_totalprice)

relationships:
  - name: orders_to_customers
    left_table: orders
    right_table: customers
    relationship_columns:
      - left_column: o_custkey
        right_column: c_custkey

metrics:
  - name: revenue_per_customer
    description: "Average revenue per customer"
    expr: orders.total_revenue / customers.customer_count

该示例中的关键要素说明：

customers表：定义了customer_name维度和customer_segment枚举维度（is_enum: true），以及customer_count表级指标。
orders表：定义了order_date和order_year两个维度、order_total事实，以及total_orders、total_revenue、average_order_value三个表级指标。
orders_to_customers关系：通过o_custkey和c_custkey列关联orders和customers两个表。
revenue_per_customer派生指标：通过组合orders表的total_revenue和customers表的customer_count计算每位客户的平均收入。