Referência de sintaxe YAML

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

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

Visão geral do YAML

A definição YAML para uma view de métricas inclui os seguintes campos de nível superior:

• version: padrão para 1.1. Esta é a versão da especificação view de métricas. Veja o changelog da especificação da versão.
• source: Os dados de origem para a view de métricas. Pode ser um ativo semelhante a uma tabela ou uma consulta SQL.
• joins: Opcional. Esquemas em estrela e em floco de neve são suportados.
• filter: Opcional. Uma expressão booleana SQL que se aplica a todas as consultas; equivalente à cláusula WHERE .
• comment: Opcional. Descrição da view de métricas.
• dimensions: Uma matriz de definições de dimensão, incluindo o nome da dimensão e a expressão.
• measures: Uma matriz de colunas de expressão agregada.

Referências de nomes de colunas

Ao referenciar nomes de colunas que contêm espaços ou caracteres especiais em expressões YAML, coloque o nome da coluna entre acentos graves para escapar do espaço ou caractere. Se a expressão começar com uma crase e for usada diretamente como um valor YAML, coloque toda a expressão entre aspas duplas. Valores YAML válidos não podem começar com uma crase.

Exemplos de formatação

Use os exemplos a seguir para aprender como formatar 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 eles contêm.

Caso	Nome(s) da(s) coluna(s) de origem	Expressão(ões) de referência	Notas
Sem espaços	revenue	expr: "revenue" expr: 'revenue' expr: revenue	Use aspas duplas, aspas simples ou sem aspas ao redor do nome da coluna.
Com espaços	First Name	expr: "`First Name`"	Use acentos graves para escapar de espaços. Coloque toda a expressão entre aspas duplas.
Nome da coluna com espaços em uma expressão SQL	First Name e Last Name	expr: CONCAT(`First Name`, , `Last Name`)	Se a expressão não começar com acentos graves, aspas duplas não serão necessárias.
As citações estão incluídas no nome da coluna de origem	"name"	expr: '`"name"`'	Use acentos graves para escapar das aspas duplas no nome da coluna. Coloque essa expressão entre aspas simples na definição YAML.

Use expressões com dois pontos

Caso	Expressão	Notas
Expressões com dois pontos	expr: "CASE WHENNível do cliente= 'Enterprise: Premium' THEN 1 ELSE 0 END"	Coloque toda a expressão entre aspas duplas para uma interpretação correta

nota

YAML interpreta dois pontos sem aspas como separadores key-valor. Sempre use aspas duplas em expressões que incluam dois pontos.

Recuo multilinha

Caso	Expressão	Notas
Recuo multilinha

nota

Use o bloco escalar | após expr: para expressões multilinhas. Todas as linhas devem ser recuadas pelo menos dois espaços além da key expr para uma análise correta.

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 em CREATE VIEW com YAML

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

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

SQL

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.

Atualize seu YAML para 1.1

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

Tipos de comentários

• Comentários YAML (#) : Comentários em linha ou de linha única escritos diretamente no arquivo YAML usando o símbolo #.
• ComentáriosUnity Catalog : comentários armazenados no Unity Catalog para a view 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 na sua view de métricas. As opções a seguir descrevem as abordagens disponíveis e fornecem exemplos.

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

Se sua view de métricas contiver comentários YAML (#) que você deseja manter, use os seguintes passos:

1. Use o comando ALTER VIEW em um editor de Notebook ou SQL .

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

3. Salve a view de métricas.

SQL

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

atenção

Executar ALTER VIEW remove comentários do Unity Catalog, a menos que eles sejam explicitamente incluídos nos campos comment da definição YAML. Se você quiser preservar os comentários mostrados no Unity Catalog, veja a opção 2.

Opção 2: Preservar comentários Unity Catalog

nota

A orientação a seguir se aplica somente ao usar o comando ALTER VIEW em um editor Notebook ou SQL . Se você atualizar sua view de métricas para a versão 1.1 usando a interface do editor YAML, seus comentários Unity Catalog serão preservados automaticamente.

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

2. Salve a view de métricas.

SQL

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 da especificação da versão

Versão 1.1

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

Versão 0.1

• Lançamento inicial da especificação YAML view de métricas.