Referência de sintaxe YAML

As definições de exibição de métrica seguem a sintaxe de notação YAML padrão. Esta página explica como definir uma exibição de métrica.

Consulte a documentação da Especificação 1.2.2 do YAML para saber mais sobre as especificações do YAML.

Visão geral do YAML

A definição yaml para uma exibição de métrica inclui os seguintes campos de nível superior:

• version: Define-se como 1.1. Esta é a versão da especificação de visualização de métricas. Consulte o registro de alterações da especificação da versão.
• source: Os dados de origem da visualização de métricas. Isso pode ser um ativo semelhante a uma tabela ou uma consulta SQL.
• joins: opcional. Há suporte para junções de esquema de estrela e esquema de floco de neve.
• filter: opcional. Uma expressão booliana do SQL que se aplica a todas as consultas; equivalente à WHERE cláusula.
• comment: opcional. Descrição da visualização de métrica.
• dimensions: uma matriz de definições de dimensão, incluindo o nome e a expressão da dimensão.
• measures: uma matriz de colunas de expressão de agregação.

Referências ao nome da coluna

Ao fazer referência a nomes de colunas que contenham espaços ou caracteres especiais em expressões YAML, coloque o nome da coluna entre chaves para escapar do espaço ou do caractere. Se a expressão começar com um acento grave e for usada diretamente como um valor YAML, coloque a expressão inteira entre aspas duplas. Valores YAML válidos não podem começar com um acento grave.

Exemplos de formatação

Use os exemplos a seguir para aprender a formatar o YAML corretamente em cenários comuns.

Referenciar um nome de coluna

A tabela a seguir mostra como formatar nomes de colunas dependendo dos caracteres que elas contêm.

Usar expressões com dois-pontos

Indentação de múltiplas linhas

Definir uma dimensão

O exemplo a seguir demonstra como definir dimensões:

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

Definir uma medida

O exemplo a seguir demonstra como 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')

Mapeamento de nomes de colunas CREATE VIEW com YAML

Quando você cria uma exibição de métrica usando CREATE VIEW com um column_list, o sistema mapeia colunas definidas por YAML (medidas e dimensões) para a column_list pela posição, não por nome.

Isso segue o comportamento padrão do SQL, conforme mostrado no exemplo a seguir:

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

Neste exemplo, a mapeia para col1, e b mapeia para col2, independentemente de seus nomes originais.

Atualizar seu YAML para 1.1

Atualizar uma exibição de métrica para a especificação YAML versão 1.1 requer cuidado, pois os comentários são tratados de forma diferente das versões anteriores.

Tipos de comentários

• Comentários YAML (#): comentários embutidos ou de linha única escritos diretamente no arquivo YAML usando o símbolo #.
• Comentários do Unity Catalog: Comentários armazenados no Unity Catalog para a visualização de métricas ou suas colunas (dimensões e medidas). Eles são separados dos comentários YAML.

Considerações sobre atualização

Escolha o caminho de atualização que corresponde à maneira como você deseja lidar com comentários em sua exibição de métrica. As opções a seguir descrevem as abordagens disponíveis e fornecem exemplos.

Opção 1: Preservar comentários YAML usando notebooks ou editor SQL

Se a exibição de métrica contiver comentários YAML (#) que você deseja manter, use as seguintes etapas:

1. Use o ALTER VIEW comando em um notebook ou editor do SQL.

2. Copie a definição original do YAML na seção $$..$$ após AS. Altere o valor da versão para 1.1.

3. Salve o modo de exibição de métrica.

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)
$$

Opção 2: Preservar comentários do Catálogo do Unity

1. Copie todos os comentários do Unity Catalog nos campos apropriados comment na definição do YAML. Altere o valor da versão para 1.1.

2. Salve o modo de exibição de métrica.

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 alterações das especificações de versão

Versão 1.1 (requer Databricks Runtime 17.2 ou superior)

• Adicionado:
  • Suporte para recursos de metadados semânticos. Consulte Usar metadados semânticos em exibições de métrica.
  • Suporte para o campo YAML comment opcional para descrever a visualização de métricas, dimensões ou medidas.

Versão 0.1 (requer Databricks Runtime 16.4 a 17.1)

• Versão inicial da especificação YAML da visualização de métricas.