Semantic YAML content specification-阿里云帮助中心

Semantic views support definition through a YAML specification. You can author a YAML file that describes your business concepts and then import it with a CREATE OR REPLACE SEMANTIC VIEW statement to build a business semantic layer on top of your data, enabling users to query and analyze data using business terms.

YAML structure overview

A semantic view YAML specification contains the following top-level fields:

name: The name of the semantic view.
description: A text description of the semantic view.
synonyms: An array of alternative names for the semantic view.
tables: An array of logical table definitions. Each entry describes a business entity and maps it to a physical table.
relationships: An array of view-level relationship definitions that describe how logical tables connect to each other.
metrics: An array of view-level derived metrics that combine metrics from multiple tables.

The full YAML syntax template is shown below:

# Name and description of the semantic view
name: <name>
description: <string>
synonyms: <array of strings>
# Logical table concepts
# A semantic view can contain one or more logical tables
tables:
  - name: <name>
    description: <string>
    synonyms: <array of strings>
    # Fully qualified name of the base table
    base_table:
      schema: <schema>
      table: <base table name>

    # Dimension columns in the logical table
    dimensions:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        expr: <SQL expression>
        data_type: <data type>
        is_enum: <boolean>

    # Fact columns in the logical table
    facts:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        expr: <SQL expression>
        data_type: <data type>

    # Metrics scoped to the logical table
    metrics:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        expr: <SQL expression>
        using_relationships:
        - <relationship_name>

# View-level concepts
# Relationships between logical tables
relationships:
  - name: <string>
    synonyms: <array of strings>
    left_table: <table>
    right_table: <table>
    relationship_columns:
      - left_column: <column>
        right_column: <column>

# Derived metrics scoped to the semantic view
# Derived metrics combine metrics from multiple tables
metrics:
  - name: <name>
    synonyms: <array of strings>
    description: <string>
    expr: <SQL expression>

Field reference

Synonyms

The synonyms field is a shared property available on all semantic objects. It accepts a string array of alternative names, aliases, or abbreviations for the object. You can define synonyms on semantic views, logical tables, dimensions, facts, metrics, relationships.

By registering synonyms, you allow users and AI agents to reference the same semantic object through different business terms, increasing query flexibility and discoverability.

Tables

Logical tables represent business entities such as customers, orders, or products, and map to physical database tables. Each logical table can define a base table, primary key, and description.

The following table describes the fields of a logical table definition:

Field	Description
`name`	The logical table name.
`description`	A text description of the logical table.
`synonyms`	An array of alternative names.
`base_table`	The physical table mapping. Contains two sub-fields: `schema` (database name) and `table` (physical table name).
`primary_key`	The primary key column.

Each logical table can also contain nested definitions for dimensions, facts, metrics.

Dimensions

Dimensions are categorical attributes that provide analytical context. They answer questions like "who," "what," "where," and "when."

The following table describes the fields of a dimension definition:

Field	Required	Description
`name`	Yes	The dimension name.
`expr`	Yes	A SQL expression that computes the dimension value from a physical column.
`data_type`	No	The data type of the dimension.
`synonyms`	No	An array of alternative names.
`description`	No	A text description of the dimension. For time dimensions, include context such as time zone information.
`sample_values`	No	A list of example values for the dimension.
`is_enum`	No	A boolean flag. When set to `true`, the `sample_values` list is treated as the exhaustive set of all possible values (enumerated dimension).

Facts

Facts are row-level quantitative attributes that represent specific business events or transactions. Within a semantic view, facts typically serve as the raw building blocks from which metrics are derived.

The following table describes the fields of a fact definition:

Field	Description
`name`	The fact name.
`synonyms`	An array of alternative names.
`description`	A text description of the fact.
`expr`	A SQL expression that maps to a physical column.
`data_type`	The data type of the fact.

Metrics

Metrics are quantifiable measures of business performance, computed by applying aggregate functions such as SUM, AVG, and COUNT to facts or other columns.

Semantic views support two types of metrics:

Table-level metrics: Defined within a specific logical table and scoped to that table.
Derived metrics: Defined in the top-level metrics array and not bound to any specific table. Derived metrics can combine metrics from multiple tables.

Table-level metrics

The following table describes the fields of a table-level metric definition:

Field	Description
`name`	The metric name.
`synonyms`	An array of alternative names.
`description`	A text description of the metric.
`expr`	A SQL expression that includes an aggregate function, such as `SUM(o_totalprice)` or `COUNT(*)`.
`using_relationships`	Specifies which relationship path to use when multiple paths exist between two logical tables.

Derived metrics

Derived metrics are defined in the top-level metrics array of the YAML file. They are not bound to any specific table and can combine metrics from multiple logical tables.

For example, the following derived metric calculates average revenue per customer by combining the total_revenue metric from the orders table and the customer_count metric from the customers table:

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

Relationships

Relationships are defined in the top-level relationships array and describe how logical tables join together.

The following table describes the fields of a relationship definition:

Field	Description
`name`	The relationship name.
`synonyms`	An array of alternative names.
`left_table`	The name of the left table in the join.
`right_table`	The name of the right table in the join.
`relationship_columns`	An array of column pairs. Each pair contains a `left_column` and a `right_column` that define the join condition between the two tables.

Note

Semantic views do not require the join_type or relationship_type fields that are common in traditional semantic models. The relationship type (one-to-one, many-to-many, and so on) is automatically inferred from the data and primary key definitions.

Complete example

The following example defines a semantic view named revenue_analysis for analyzing revenue across products and customers. It includes two logical tables (customers and orders), dimensions, facts, metrics, a relationship between the tables, and a derived metric called 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

Key elements in this example:

customers table: Defines a customer_name dimension and a customer_segment enumerated dimension (is_enum: true), along with a customer_count table-level metric.
orders table: Defines two dimensions (order_date and order_year), one fact (order_total), and three table-level metrics (total_orders, total_revenue, and average_order_value).
orders_to_customers relationship: Joins the orders and customers tables through the o_custkey and c_custkey columns.
revenue_per_customer derived metric: Calculates the average revenue per customer by dividing total_revenue from the orders table by customer_count from the customers table.