Comparteix via

Referencia de sintaxis de YAML

Las definiciones de la vista métrica siguen la sintaxis de notación YAML estándar. En esta página se explica cómo definir una 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:

  • version: Tiene como valor predeterminado 1.1. Esta es la versión de la especificación de visualización de métricas. Consulte Registro de cambios de especificación de versión.
  • source: Los datos de origen de la vista de métricas. Puede ser un recurso similar a una tabla o una consulta SQL.
  • joins: opcional. Se admiten el esquema de estrella y las combinaciones de esquema de copo de nieve.
  • filter: opcional. Expresión booleana SQL que se aplica a todas las consultas; equivalente a la WHERE cláusula .
  • comment: opcional. Descripción de la vista de métricas.
  • dimensions: matriz de definiciones de dimensión, incluido el nombre y la expresión de la dimensión.
  • measures: matriz de columnas de expresión de agregado.

Referencias de nombre de columna

Al hacer referencia a nombres de columna que contienen espacios o caracteres especiales en expresiones YAML, incluya el nombre de la columna entre acentos graves para escapar el espacio o carácter. 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 la tabla siguiente se muestra cómo dar formato a los nombres de columna en función de los caracteres que contienen.

Caso Nombres de columnas de origen Expresiones de referencia Notas
Sin espacios revenue expr: "revenue"
expr: 'revenue'
expr: revenue		 Use comillas dobles, comillas simples o sin comillas alrededor del nombre de columna.
Con espacios First Name expr: "`First Name`" Use acentos graves para escapar espacios. Incluya toda la expresión entre comillas dobles.
Nombre de columna con espacios en una expresión SQL First Name y Last Name expr: CONCAT(`First Name`, , `Last Name`) Si la expresión no comienza con acentos graves, no son necesarias las comillas dobles.
Las comillas se incluyen en el nombre de la columna de origen. "name" expr: '`"name"`' Use los acentos graves para escapar las comillas dobles en el nombre de columna. Incluya esa expresión entre comillas simples en la definición de YAML.

Uso de expresiones con dos puntos

Caso Expression Notas
Expresiones con dos puntos expr: "CASE WHEN Nivel de cliente = 'Enterprise: Premium' THEN 1 ELSE 0 END" Envuelva toda la expresión entre comillas dobles para una interpretación correcta

Nota:

YAML interpreta dos puntos sin comillas como separadores de clave-valor. Use siempre comillas dobles alrededor de expresiones que incluyan dos puntos.

Indentación de varias líneas

Caso Expression Notas
Indentación de varias líneas expr: \|
CASE WHEN
revenue > 100 THEN 'High'
ELSE 'Low'
END		 Indenta la expresión debajo de la primera línea

Nota:

Utilice el bloque escalar | después del expr: para expresiones de varias líneas. Todas las líneas deben tener una sangría de al menos dos espacios más allá de la tecla expr para que el análisis sea correcto.

Definición de una dimensión

En el ejemplo siguiente se muestra cómo definir dimensiones:

dimensions:

  # Column name
  - name: Order date
    expr: o_orderdate

  # SQL expression
  - name: Order month
    expr: DATE_TRUNC('MONTH', `Order date`)

  # Referring to a column with a space in the name
  - name: Month of order
    expr: `Order month`

  # Multi-line expression
  - name: Order status
    expr: CASE
            WHEN o_orderstatus = 'O' THEN 'Open'
            WHEN o_orderstatus = 'P' THEN 'Processing'
            WHEN o_orderstatus = 'F' THEN 'Fulfilled'
          END

Definición de una medida

En el ejemplo siguiente se muestra cómo definir medidas:

measures:

  # Basic aggregation
  - name: Total revenue
    expr: SUM(o_totalprice)

  # Basic aggregation with ratio
  - name: Total revenue per customer
    expr: SUM(`Total revenue`) / COUNT(DISTINCT o_custkey)

  # Measure-level filter
  - name: Total revenue for open orders
    expr: COUNT(o_totalprice) FILTER (WHERE o_orderstatus='O')

  # Measure-level filter with multiple aggregate functions
  # filter needs to be specified for each aggregate function in the expression
  - name: Total revenue per customer for open orders
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus='O')/COUNT(DISTINCT o_custkey) FILTER (WHERE o_orderstatus='O')

Asignación de nombres de columna en CREATE VIEW con YAML

Cuando creas una vista de métricas mediante CREATE VIEW con column_list, el sistema asigna las columnas definidas por YAML (medidas y dimensiones) a la column_list por posición, no por nombre.

Esto sigue el comportamiento de SQL estándar, como se muestra en el ejemplo siguiente:

CREATE VIEW v (col1, col2) AS SELECT a, b FROM table;

En este ejemplo, a se asigna a col1y b se asigna a col2, independientemente de sus nombres originales.

Actualización de YAML a 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 en línea o de una sola línea escritos directamente en el archivo YAML mediante el símbolo #.
  • Comentarios del catálogo de Unity: comentarios almacenados en el Catálogo de Unity para la vista de métricas o sus columnas (dimensiones y medidas). 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. Las siguientes opciones describen los enfoques disponibles y proporcionan ejemplos.

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 versión a 1.1.

  3. Guarde la vista de métricas.

ALTER VIEW metric_view_name AS
$$
# Inline comments are preserved in the notebook
version: 1.1
source: samples.tpch.orders
dimensions:
- name: order_date # Inline comments are preserved in the notebook
  expr: o_orderdate
measures:
# Commented out definition is preserved
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

Advertencia

Al ejecutar ALTER VIEW , se quitan los comentarios del catálogo de Unity a menos que se incluyan explícitamente en los comment campos de la definición de YAML. Si desea conservar los comentarios que se muestran en el catálogo de Unity, consulte la opción 2.

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

Nota:

Las instrucciones siguientes solo se aplican cuando se usa el ALTER VIEW comando en un cuaderno o en un editor de SQL. Si actualiza la vista de métrica a la versión 1.1 mediante la interfaz de usuario del editor de YAML, los comentarios del catálogo de Unity se conservarán automáticamente.

  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 versión 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"
$$

Registro de cambios de especificación de versión

Versión 1.1 (requiere Databricks Runtime 17.2 o posterior)

Versión 0.1 (requiere Databricks Runtime 16.4 a 17.1)

  • Versión inicial de la especificación YAML de la vista de métricas.
  • Last updated on