Referencia de sintaxis de YAML de la vista de métricas

En esta página se explica la gramática completa de YAML para las vistas de métricas. Las definiciones de la vista métrica siguen la sintaxis de notación YAML estándar.

Para conocer los requisitos mínimos de la versión de la especificación en tiempo de ejecución y YAML para cada característica, consulte Disponibilidad de características de la vista de métricas.

Consulte la documentación de YAML Specification 1.2.2 para obtener más información sobre las especificaciones de YAML.

Introducción a YAML

La definición de YAML para una vista de métrica incluye los siguientes campos de nivel superior:

Fuente

El source campo especifica el origen de datos para la vista de métricas. Entre los orígenes admitidos se incluyen tablas, vistas, vistas de métricas y consultas SQL. La capacidad de redacción se aplica en las vistas de métricas. Al usar una vista de métrica como origen, puede hacer referencia a sus dimensiones y medidas en la nueva vista de métricas. Consulte Composabilidad.

Origen de recursos similares a tabla

Haga referencia a un recurso similar a una tabla con su nombre de tres partes:

source: catalog.schema.source_table

Origen de consulta SQL

Para usar una consulta SQL, escriba el texto de la consulta directamente en YAML:

source: SELECT * FROM samples.tpch.orders o
  LEFT JOIN samples.tpch.customer c
  ON o.o_custkey = c.c_custkey

Filter

Un filtro de la definición de YAML se aplica a todas las consultas que hacen referencia a la vista de métricas. Escribir filtros como expresiones booleanas de SQL.

# Single condition filter
filter: o_orderdate > '2024-01-01'

# Multiple conditions with AND
filter: o_orderdate > '2024-01-01' AND o_orderstatus = 'F'

# Multiple conditions with OR
filter: o_orderpriority = '1-URGENT' OR o_orderpriority = '2-HIGH'

# Complex filter with IN clause
filter: o_orderstatus IN ('F', 'P') AND o_orderdate >= '2024-01-01'

# Filter with NOT
filter: o_orderstatus != 'O' AND o_totalprice > 1000.00

# Filter with LIKE pattern matching
filter: o_comment LIKE '%express%' AND o_orderdate > '2024-01-01'

Se une

Las combinaciones en vistas de métricas admiten combinaciones directas de una tabla de hechos a tablas de dimensiones (esquema de estrella) y combinaciones de varios saltos entre tablas de dimensiones normalizadas (esquemas de copo de nieve). También puede unirse a una consulta SQL mediante una SELECT instrucción . Consulte Uso de una consulta SQL como origen.

Cada definición de combinación incluye los siguientes campos:

Combinaciones de esquema de estrella

En un esquema de estrella, source es la tabla de hechos y combina con una o varias tablas de dimensiones mediante .LEFT OUTER JOIN Las vistas de métricas unen las tablas de hechos y dimensiones necesarias para la consulta específica, en función de las columnas seleccionadas.

Especifique las columnas de combinación mediante una ON cláusula o una USING cláusula :

• ON cláusula: usa una expresión booleana para definir la condición de combinación.
• USING cláusula: enumera las columnas con el mismo nombre en la tabla primaria y en la tabla combinada.

La unión debe seguir una relación de varios a uno. En los casos de varios a varios, se selecciona la primera fila coincidente de la tabla de dimensiones combinadas.

version: 1.1
source: samples.tpch.lineitem

joins:
  - name: orders
    source: samples.tpch.orders
    on: source.l_orderkey = orders.o_orderkey

  - name: part
    source: samples.tpch.part
    on: source.l_partkey = part.p_partkey

dimensions:
  - name: Order Status
    expr: orders.o_orderstatus

  - name: Part Name
    expr: part.p_name

measures:
  - name: Total Revenue
    expr: SUM(l_extendedprice * (1 - l_discount))

  - name: Line Item Count
    expr: COUNT(1)

Combinaciones de esquema de Snowflake

Un esquema de copo de nieve extiende un esquema de estrella normalizando las tablas de dimensiones y conectándolas a subdimensiones. Esto crea una estructura de combinación de varios niveles. Consulte Disponibilidad de características de la vista de métricas para conocer los requisitos mínimos del entorno de ejecución.

Para definir un esquema de copo de nieve, anida joins dentro de una definición de combinación primaria:

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    'on': o_custkey = c_custkey
    joins:
      - name: nation
        source: samples.tpch.nation
        'on': c_nationkey = n_nationkey

dimensions:
  - name: customer_nation
    expr: customer.nation.n_name

Dimensiones

Las dimensiones son columnas utilizadas en las cláusulas SELECT, WHERE y GROUP BY en el momento de la consulta. Cada expresión debe devolver un valor escalar. Las dimensiones pueden hacer referencia a columnas de los datos de origen o de las dimensiones definidas anteriormente en la vista de métricas.

Cada definición de dimensión incluye los siguientes campos:

Ejemplo:

dimensions:
  # Basic dimension
  - name: order_date
    expr: o_orderdate
    comment: 'Date the order was placed'
    display_name: 'Order Date'

  # Dimension with SQL expression
  - name: order_month
    expr: DATE_TRUNC('MONTH', o_orderdate)
    display_name: 'Order Month'

  # Dimension with synonyms
  - name: order_status
    expr: CASE
      WHEN o_orderstatus = 'O' THEN 'Open'
      WHEN o_orderstatus = 'P' THEN 'Processing'
      WHEN o_orderstatus = 'F' THEN 'Fulfilled'
      END
    display_name: 'Order Status'
    synonyms: ['status', 'fulfillment status']

Medidas

Las medidas son expresiones que generan resultados sin un nivel de agregación determinado previamente. Deben expresarse mediante funciones de agregado. Para hacer referencia a una medida en una consulta, use la MEASURE función . Las medidas pueden hacer referencia a campos base en los datos de origen, las dimensiones definidas anteriormente o las medidas definidas anteriormente.

Cada definición de medida incluye los siguientes campos:

Consulte Funciones de agregado para obtener una lista de funciones de agregado.

Ejemplo:

measures:
  # Simple count measure
  - name: order_count
    expr: COUNT(1)
    display_name: 'Order Count'

  # Sum aggregation measure with synonyms
  - name: total_revenue
    expr: SUM(o_totalprice)
    comment: 'Gross revenue from all orders'
    display_name: 'Total Revenue'
    synonyms: ['revenue', 'total sales']

  # Distinct count measure
  - name: unique_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: 'Unique Customers'

  # Calculated measure combining multiple aggregations
  - name: avg_order_value
    expr: SUM(o_totalprice) / COUNT(DISTINCT o_orderkey)
    display_name: 'Avg Order Value'
    synonyms: ['AOV', 'average order']

  # Filtered measure with WHERE condition
  - name: open_order_revenue
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'O')
    display_name: 'Open Order Revenue'
    synonyms: ['backlog', 'outstanding revenue']

Medidas de Windows

El window campo define agregaciones de ventanas, acumulativas o semiaditivas para las medidas. Para obtener información detallada sobre las medidas de ventana y los casos de uso, vea Medidas de ventana.

Cada especificación de ventana incluye los siguientes campos:

(1) La dimensión a la que se hace referencia debe ser determinista. Las expresiones no deterministas, como rand(), uuid()o current_timestamp() generan un orden de ventana impredecible y pueden dar lugar a resultados de agregación incorrectos.

Valores de range admitidos

• current: filas donde el valor de ordenación de la ventana es igual al valor de la fila actual.
• cumulative: todas las filas en las que el valor de ordenación de ventanas es menor o igual que el valor de la fila actual.
• trailing <value> <unit>: filas de la fila actual que va hacia atrás por las unidades de tiempo especificadas, por ejemplo trailing 7 day. No incluye la unidad actual.
• leading <value> <unit>: filas de la fila actual en adelante por las unidades de tiempo especificadas, por ejemplo leading 3 month. No incluye la unidad actual.
• all: todas las filas independientemente del valor de ordenación de ventanas.

Ejemplo de medida de ventana

En el ejemplo siguiente se calcula un recuento gradual de 7 días de clientes únicos:

version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate

measures:
  - name: rolling_7day_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: '7-Day Rolling Customers'
    window:
      - order: order_date
        range: trailing 7 day
        semiadditive: last

Materialización

El materialization campo configura la aceleración automática de consultas mediante vistas materializadas. Para obtener información detallada sobre cómo funciona la materialización, los requisitos y los procedimientos recomendados, consulte Materialización para vistas de métricas.

El materialization campo incluye los siguientes campos de nivel superior:

Cada entrada de materialized_views incluye los siguientes campos:

Ejemplo de materialización

En el ejemplo siguiente se define una vista de métrica con varias materializaciones:

version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate
  - name: order_status
    expr: o_orderstatus

measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
  - name: order_count
    expr: COUNT(1)

materialization:
  schedule: every 6 hours
  mode: relaxed
  materialized_views:
    - name: baseline
      type: unaggregated

    - name: daily_status_metrics
      type: aggregated
      dimensions:
        - order_date
        - order_status
      measures:
        - total_revenue
        - order_count

Referencias de nombre de columna

Al hacer referencia a nombres de columna que contienen espacios o caracteres especiales en expresiones YAML, encierra el nombre de columna en acentos inversas. Si la expresión comienza con un acento grave y se usa directamente como un valor YAML, incluya toda la expresión entre comillas dobles. Los valores válidos de YAML no pueden comenzar con un acento grave.

Ejemplos de formato

Use los ejemplos siguientes para aprender a dar formato a YAML correctamente en escenarios comunes.

Hacer referencia a un nombre de columna

En los ejemplos siguientes se muestra cómo dar formato a las referencias de columna en función de los caracteres que contienen.

Sin espacios

Columna de origen: revenue

expr: "revenue"
expr: 'revenue'
expr: revenue

Use comillas dobles, comillas simples o sin comillas alrededor del nombre de columna.

Nombre de columna con espacios

Columna de origen: `First Name`

expr: '`First Name`'

Use acentos graves para escapar espacios. Incluya toda la expresión entre comillas dobles.

Nombres de columna con espacios en una expresión SQL

Columnas de origen: `First Name`, `Last Name`

expr: CONCAT(`First Name`, ' ', `Last Name`)

Si la expresión no comienza con un verso, no se requieren comillas dobles.

Nombre de columna que contiene comillas

Columna de origen: "name"

expr: '`"name"`'

Use las comillas inversas para escapar las comillas dobles en el nombre de la columna. Incluya la expresión entre comillas simples.

Expresiones con dos puntos

expr: "CASE WHEN `Customer Tier` = 'Enterprise: Premium' THEN 1 ELSE 0 END"

Expresiones de varias líneas

expr: |
  CASE WHEN
    revenue > 100 THEN 'High'
  ELSE 'Low'
  END

Actualización a YAML 1.1

La actualización de una vista de métrica a la versión 1.1 de la especificación YAML requiere cuidado, ya que los comentarios se controlan de forma diferente a en versiones anteriores.

Tipos de comentarios

• Comentarios de YAML (#):comentarios insertados o de una sola línea escritos directamente en el archivo YAML.
• Comentarios del catálogo de Unity: comentarios almacenados en el Catálogo de Unity para la vista de métricas o sus columnas. Estos son independientes de los comentarios de YAML.

Consideraciones de actualización

Elija la ruta de actualización que coincida con la forma en que desea controlar los comentarios en la vista de métricas.

Opción 1: Conservar los comentarios de YAML mediante cuadernos o el editor de SQL

Si la vista de métrica contiene comentarios de YAML (#) que desea conservar, siga estos pasos:

1. Use el ALTER VIEW comando en un cuaderno o en un editor de SQL.
2. Copie la definición de YAML original en la sección después $$..$$de AS . Cambie el valor de version a 1.1.
3. Guarde la vista de métricas.

ALTER VIEW metric_view_name AS
$$
# The notebook preserves inline comments
version: 1.1
source: samples.tpch.orders
dimensions:
- name: order_date # The notebook preserves inline comments
  expr: o_orderdate
measures:
# The notebook preserves commented out definitions
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

Opción 2: Conservar los comentarios del catálogo de Unity

1. Copie todos los comentarios del catálogo de Unity en los campos comment adecuados de su definición de YAML. Cambie el valor de version a 1.1.
2. Guarde la vista de métricas.

ALTER VIEW metric_view_name AS
$$
version: 1.1
source: samples.tpch.orders
comment: "Metric view of order (Updated comment)"

dimensions:
- name: order_date
  expr: o_orderdate
  comment: "Date of order - Copied from Unity Catalog"

measures:
- name: total_revenue
  expr: SUM(o_totalprice)
  comment: "Total revenue"
$$

Para ver el historial de versiones de especificación de YAML y los requisitos mínimos de tiempo de ejecución para cada característica, consulte Disponibilidad de características de la vista de métricas.