Partilhar via

Referência de sintaxe YAML

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

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 de YAML para uma exibição métrica inclui os seguintes campos de nível superior:

  • version: O padrão é 1.1. Esta é a versão da especificação da visualização métrica. Consulte Changelog da especificação de versão.
  • source: Os dados de origem para a visualização métrica. Pode ser um ativo semelhante a uma tabela ou uma consulta SQL.
  • joins: Opcional. O esquema de estrela e as junções de esquema de floco de neve são suportados.
  • filter: Opcional. Uma expressão booleana SQL que se aplica a todas as consultas; equivalente à WHERE cláusula.
  • comment: Opcional. Descrição da visualização 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 agregada.

Referências de nomes de colunas

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

Exemplos de formatação

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

Fazer referência a um nome de coluna

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

Incidente Nome(s) da(s) coluna(s) de origem Expressão(ões) de referência Observações
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 backticks 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 backticks, aspas duplas não são necessárias.
As citações são incluídas no nome da coluna de origem "name" expr: '`"name"`' Use backticks para escapar das aspas duplas no nome da coluna. Coloque essa expressão entre aspas simples na definição YAML.

Usar expressões com dois pontos

Incidente Expression Observações
Expressões com dois pontos expr: "CASE WHEN Nível de cliente = 'Enterprise: Premium' THEN 1 ELSE 0 END" Envolva toda a expressão entre aspas duplas para uma interpretação correta

Observação

YAML interpreta dois pontos sem aspas como separadores chave-valor. Use sempre aspas duplas em torno de expressões que incluam dois pontos.

Recuo de várias linhas

Incidente Expression Observações
Recuo de várias linhas expr: \|
CASE WHEN
revenue > 100 THEN 'High'
ELSE 'Low'
END		 Indentar a expressão na alinhamento da primeira linha

Observação

Use o | bloco escalar depois do expr: para expressões de várias linhas. Todas as linhas devem ser recuadas pelo menos dois espaços além da chave expr para a 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')

Mapeação de nomes de colunas em CREATE VIEW com YAML

Quando se cria uma vista métrica usando CREATE VIEW com um column_list, o sistema mapeia colunas definidas em YAML (medidas e dimensões) por posição, não pelo 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 col1e b mapeia para col2, independentemente de seus nomes originais.

Atualize o seu YAML para 1.1

A atualização de uma visualização métrica 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 embutidos ou de linha única escritos diretamente no arquivo YAML usando o símbolo #.
  • Comentários do Catálogo Unity: Comentários armazenados no Catálogo Unity para a visualização métrica ou suas colunas (dimensões e medidas). Estes são separados dos comentários YAML.

Considerações sobre a atualização

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

Opção 1: Preservar comentários YAML usando blocos de anotações ou o editor SQL

Se sua 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 bloco de anotações ou editor SQL.

  2. Copie a definição original do YAML para $$..$$ depois de AS. Altere o valor da versão para 1.1.

  3. Salve a visualização 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)
$$

Advertência

A execução ALTER VIEW remove os comentários do Catálogo Unity, a menos que eles estejam explicitamente incluídos nos comment campos da definição YAML. Se você quiser preservar os comentários mostrados no Catálogo Unity, consulte a opção 2.

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

Observação

As diretrizes a seguir se aplicam somente ao usar o ALTER VIEW comando em um bloco de anotações ou editor SQL. Se você atualizar sua visualização métrica para a versão 1.1 usando a interface do usuário do editor YAML, seus comentários do Catálogo Unity serão preservados automaticamente.

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

  2. Salve a visualização 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"
$$

Registo de alterações da especificação da versão

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

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

  • Liberação inicial da especificação YAML da visualização métrica.
  • Last updated on