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

Las definiciones de vista de métricas usan la sintaxis YAML estándar para declarar el origen, las combinaciones, los campos, las medidas, los filtros, las medidas de ventana y la materialización. En las secciones siguientes se documenta la gramática completa para cada una.

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.

Edición de YAML en el editor de vistas de métricas

Puede escribir y editar el CÓDIGO YAML descrito en esta página directamente en el editor de vistas de métricas. En el Explorador de catálogos, abra una vista de métricas y haga clic en el <> botón para editar la definición. Para generar YAML a partir de una descripción del lenguaje natural en su lugar, abra Genie Code desde el editor. Para ver el tutorial completo del editor, consulte Creación de una vista de métricas.

Campos YAML de nivel superior

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

Source

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 campos 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

Parámetros

El parameters bloque define los valores con nombre que los autores de llamada pasan cuando consultan la vista de métrica como una función con valores de tabla. Para saber cuándo y cómo usar parámetros, incluida la consulta de una vista de métrica con parámetros, consulte Uso de parámetros con vistas de métricas.

Cada definición de parámetro incluye los siguientes campos:

En el ejemplo siguiente se define un discount parámetro y se hace referencia a él en una expresión de medida:

version: 1.1
source: main.default.sales

parameters:
  - name: discount
    data_type: double
    default: 0

fields:
  - name: product
    expr: product

measures:
  - name: discountedSales
    expr: SUM((1 - discount) * amount)

Filtrar

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'

Joins

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 basarse en una relación de varios a uno. En los casos de muchos a muchos, se selecciona la primera fila coincidente de la tabla de dimensión combinada.

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

fields:
  - 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

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

Combinaciones de uno a varios

El cardinality campo establece la relación entre el origen y una tabla combinada. El valor predeterminado, many_to_one, trata la tabla combinada como una búsqueda de dimensiones. Se establece cardinality: one_to_many para tratar la tabla combinada como un origen de hechos que el motor agrega de forma independiente en el grano de origen, lo que permite que una sola fila de origen coincida con varias filas de la tabla combinada. Las combinaciones de uno a varios requieren Databricks Runtime 18.1 o posterior y la especificación YAML versión 1.1. Consulte Disponibilidad de características de la vista métrica.

Las reglas siguientes se aplican a combinaciones de uno a varios:

• Una columna de uno a varios no se puede usar en una fields definición, ya que un campo debe resolverse en un valor único por fila de origen.
• Una sola función de agregación debe hacer referencia a columnas de un origen. Puede aplicar aritmética en los resultados de agregaciones independientes, como count(orders.order_id) / count(*).
• Todos los descendientes de una combinación uno a varios también deben ser one_to_many. Las combinaciones del mismo nivel de nivel superior pueden mezclar cardinalidades.
• Haga referencia a una columna de una combinación anidada con su ruta de acceso de punto completa a través de los nombres de combinación, como orders.order_items.item_id.

En el orders ejemplo siguiente se combina con un customers origen con cardinality: one_to_many para que las medidas de pedido se agreguen sin duplicar las filas del cliente:

version: 1.1
source: main.sales.customers

joins:
  - name: orders
    source: main.sales.orders
    on: orders.customer_id = source.customer_id
    cardinality: one_to_many

fields:
  - name: customer_name
    expr: customer_name

measures:
  - name: customer_count
    expr: count(*)
  - name: order_count
    expr: count(orders.order_id)
  - name: total_order_revenue
    expr: sum(orders.amount)

Para obtener detalles conceptuales y ejemplos de combinación anidada y del mismo nivel, consulte Join cardinality(Cardinalidad de unión).

Optimización de combinaciones con rely

Use el rely campo de una combinación para declarar garantías sobre la relación que usa el analizador de consultas al planear las consultas. Estas garantías permiten al motor planear consultas de forma más eficaz y reducir los datos examinados, especialmente cuando se hace referencia a campos de la tabla combinada en filtros.

El rely mapa admite los siguientes campos:

En el ejemplo siguiente se habilita at_most_one_match una combinación de varios a uno de orders a customer. Las consultas que filtran o agrupan por atributos de cliente se benefician más:

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    rely:
      at_most_one_match: true

fields:
  - name: Customer name
    expr: customer.c_name
  - name: Customer market segment
    expr: customer.c_mktsegment

measures:
  - name: Total revenue
    expr: SUM(o_totalprice)

Campos

Los campos son columnas de vista de métricas usadas en SELECTlas cláusulas , WHEREy GROUP BY en el momento de la consulta. Cada expresión debe devolver un valor escalar. Los campos pueden hacer referencia a columnas de los datos de origen o a campos definidos anteriormente en la vista de métricas.

Un campo puede ser:

• Una columna de categoría o agrupación, como una región, un estado o un departamento.
• Columna numérica no agregado, como una antigüedad, un precio o una cantidad. Los campos numéricos se pueden agregar en tiempo de consulta mediante funciones SQL como SUM o AVG.

Cada definición de campo incluye las siguientes propiedades:

Example:

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

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

  # Field 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 columnas base en los datos de origen, los campos definidos 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.

Example:

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']

Importación masiva de campos y medidas con caracteres comodín

Se aplica a: Databricks Runtime 18.2 y versiones posteriores con la especificación YAML 1.1

En una fields definición o measures , puede usar un carácter comodín (*) en el expr campo para importar todas las columnas del origen o una tabla combinada sin enumerar cada una de ellas. Esto resulta útil cuando desea que una vista de métrica exponga cada columna de un recurso ascendente, similar a SELECT * en una vista estándar. Azure Databricks expande el carácter comodín a columnas concretas al crear o reemplazar la vista de métricas y deriva cada nombre de columna del nombre de columna de origen.

Al igual que las definiciones de columna explícitas, las expresiones comodín se expanden al crear la vista de métricas. Para recoger columnas agregadas al origen más adelante, vuelva a crear la vista de métricas con CREATE OR REPLACE o ALTER.

Los caracteres comodín admiten los siguientes formatos:

Las reglas siguientes se aplican a expresiones comodín:

• Omita el name campo. Azure Databricks deriva nombres de columna del origen, por lo que name no se permite en una expresión comodín.
• No se permiten metadatos semánticos en una expresión comodín. No establezca comment, display_name, formato synonyms en un carácter comodín. Para agregar metadatos a una columna específica, excluya del carácter comodín con EXCEPT y defina explícitamente.
• En una measures definición, un carácter comodín importa solo desde un origen de vista de métricas. Las tablas base no tienen medidas, por lo que un carácter comodín se expande a ninguna medida cuando el origen es una tabla base.
• No se puede hacer referencia a una columna importada por caracteres comodín por su nombre derivado en una expresión o fields posteriormeasures. Haga referencia a la columna de origen con su ruta de acceso completa en su lugar.

Resolución de colisiones de nombres

Al importar columnas de más de un origen con un carácter comodín, las columnas que comparten un nombre (como id o date) colisionan y provocan un error al guardar la definición. Para resolver una colisión, excluya la columna de cada carácter comodín con EXCEPTy defina explícitamente con un nombre único:

fields:
  - expr: source.* EXCEPT (id)
  - expr: customer.* EXCEPT (id)
  - name: source_id
    expr: source.id
  - name: customer_id
    expr: customer.id

Ejemplo de caracteres comodín

La siguiente definición importa todas las columnas del origen y de una tabla combinada, excluye dos columnas y define una columna explícitamente para agregar metadatos:

version: 1.1
source: samples.tpch.orders

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

fields:
  # Import all columns from the source
  - expr: source.*

  # Import all columns from a joined table, excluding two
  - expr: customer.nation.* EXCEPT (n_name, n_comment)

  # Define a specific column explicitly to add metadata
  - name: nation_name
    expr: customer.nation.n_name
    comment: "Customer's nation"
    display_name: 'Nation Name'

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) El campo al 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 ventanas es igual al valor de la fila de anclaje.
• cumulative: todas las filas en las que el valor de ordenación de ventanas es menor o igual que el valor de la fila de anclaje.
• trailing <value> <unit> [inclusive | exclusive]: filas de la fila de anclaje que va hacia atrás por las unidades de tiempo especificadas, por ejemplo trailing 7 day. El modificador o inclusive opcional exclusive requiere Databricks Runtime 18.1 y la especificación YAML versión 1.1 o posterior, y controla si la fila de anclaje está incluida en la ventana. El valor predeterminado es exclusive. Consulte Incluir o excluir la fila de anclaje.
• leading <value> <unit> [inclusive | exclusive]: filas de la fila de delimitador en adelante por las unidades de tiempo especificadas, por ejemplo leading 3 month. El modificador o inclusive opcional exclusive requiere Databricks Runtime 18.1 y la especificación YAML versión 1.1 o posterior, y controla si la fila de anclaje está incluida en la ventana. El valor predeterminado es exclusive. Consulte Incluir o excluir la fila de anclaje.
• 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

fields:
  - 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

Pasar un tamaño de ventana como parámetro

En lugar de codificar el valor numérico en un trailing o leadingrange o en un offset, puedes referenciar un parámetro, de modo que un llamador pasa el tamaño de la ventana cuando consulta la vista de la métrica. Esto requiere un almacén SQL u otro recurso de cómputo que ejecute Databricks Runtime 18.2 o superior.

Las siguientes reglas se aplican a un parámetro utilizado como tamaño de ventana:

• Los parámetros data_type deben ser integrales, como int, smallint, o bigint.
• El valor debe ser un nombre de parámetro básico, no una expresión. Por ejemplo, use trailing window_size day, no trailing window_size + 1 day. Tampoco puedes escribir un signo antes del nombre del parámetro, como -window_size en un offset. Para pasar un desplazamiento negativo, coloca el signo dentro del valor del parámetro.
• El parámetro no puede nombrarse según una palabra clave de ventana, como un tipo de rango (trailing, leading), un punto (day, month, year), una palabra clave de inclusión (inclusive, exclusive), o offset.
• La unidad sigue siendo literal. Solo puedes parametrizar la magnitud numérica, no el periodo.

El siguiente ejemplo define un window_size parámetro y lo referencia en un trailing rango, de modo que cada llamante elija el número de días en la ventana móvil:

version: 1.1
source: samples.tpch.orders

parameters:
  - name: window_size
    data_type: int
    default: 7

fields:
  - name: order_date
    expr: o_orderdate

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

Para consultar una vista métrica que define parámetros, véase Consulta una vista métrica con parámetros.

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: prod.operations.orders_enriched_view
filter: revenue > 0
# filter, fields, and measures can't use invoker-dependent expressions: no current_user(), is_member(), etc.
# source can't have RLS, column masking, or ABAC policies

joins:
  - name: customers
    source: prod.operations.customers
    on: source.customer_id = customers.id
    # if one-to-many, all materializations below drop to exact match only

fields:
  - name: category
    expr: substring(category, 5)
  - name: order_date
    expr: order_date

measures:
  - name: total_revenue
    expr: SUM(revenue)

  - name: number_of_suppliers
    expr: COUNT(DISTINCT supplier_id)

  - name: revenue_for_open_orders
    expr: SUM(revenue) FILTER (WHERE status = 'O')

  - name: blended_margin
    expr: SUM(revenue) - SUM(cost)

  - name: rolling_7day_customers
    expr: COUNT(DISTINCT customer_id)
    window:
      - order: order_date
        range: trailing 7 day
        semiadditive: last

materialization:
  schedule: every 6 hours
  mode: relaxed

  materialized_views:
    - name: baseline
      type: unaggregated
      # only one allowed per metric view; doesn't use dimensions or measures keys
      # no benefit if source is an unfiltered direct table reference

    - name: daily_status_metrics
      type: aggregated
      dimensions:
        - order_date
        - category # avoid overly granular dimensions, such as millisecond timestamps
      measures:
        - total_revenue # rollup-eligible
        - number_of_suppliers # exact match only (non-additive)
        - revenue_for_open_orders # rollup-eligible (deterministic filter)
        - blended_margin # exact match only (multiple aggregates)
        - rolling_7day_customers # exact match only (window measure)
      cluster_by:
        cols:
          - order_date
          - category
      partition_by:
        - order_date

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

Seleccione 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
fields:
- 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)"

fields:
- 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.