Referência de sintaxe yaml de exibição de métrica

Esta página explica a gramática YAML completa para exibições de métrica. As definições de exibição de métrica seguem a sintaxe de notação YAML padrão.

Para obter requisitos mínimos de versão de especificação de runtime e YAML para cada recurso, consulte a disponibilidade do recurso de 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:

Fonte

O source campo especifica a fonte de dados para a exibição de métrica. Você pode usar um ativo semelhante a uma tabela, como tabelas, exibições e exibições de métrica, ou uma consulta SQL como a origem. A capacidade de composição se aplica entre exibições de métrica. Ao usar uma exibição de métrica como fonte, você pode referenciar suas dimensões e medidas na nova exibição de métrica. Consulte Modularidade.

Fonte de ativo semelhante à tabela

Faça referência a um ativo semelhante a uma tabela usando seu nome de três partes:

source: catalog.schema.source_table

Origem da consulta SQL

Para usar uma consulta SQL, escreva o texto da consulta diretamente no YAML:

source: SELECT * FROM samples.tpch.orders o
  LEFT JOIN samples.tpch.customer c
  ON o.o_custkey = c.c_custkey

Filter

Um filtro na definição yaml se aplica a todas as consultas que fazem referência à exibição de métrica. Escreva filtros como expressões boolianas do 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

As junções em exibições de métrica dão suporte a junções diretas de uma tabela de fatos a tabelas de dimensão (esquema estrela) e junções de vários saltos entre tabelas de dimensão normalizadas (esquemas floco de neve). Você também pode ingressar em uma consulta SQL usando uma SELECT instrução. Consulte Usar uma consulta SQL como fonte.

Cada definição de junção inclui os seguintes campos:

Junções de esquema estrela

Em um esquema de estrela, é a source tabela de fatos e une-se a uma ou mais tabelas de dimensão usando um LEFT OUTER JOIN. As exibições de métrica unem as tabelas de fato e dimensão necessárias para a consulta específica, com base nas colunas selecionadas.

Especifique colunas de junção usando uma ON cláusula ou uma USING cláusula:

• Cláusula ON: usa uma expressão booliana para definir a condição de junção.
• Cláusula USING: lista colunas com o mesmo nome na tabela pai e na tabela unida.

A junção deve seguir um relacionamento de muitos para um. Em casos de muitos para muitos, a primeira linha correspondente da tabela de dimensões unida é selecionada.

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

dimensions:
  - 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)

Junções de esquema snowflake

Um esquema floco de neve estende um esquema de estrela normalizando tabelas de dimensão e conectando-as a subdimensões. Isso cria uma estrutura de junção de vários níveis. Consulte a disponibilidade do recurso de exibição de métrica para obter requisitos mínimos de runtime.

Para definir um esquema de floco de neve, aninhar joins dentro de uma definição de junção pai:

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

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

Dimensões

As dimensões são colunas usadas em SELECT, WHEREe GROUP BY cláusulas no momento da consulta. Cada expressão deve retornar um valor escalar. As dimensões podem referenciar colunas dos dados de origem ou dimensões definidas anteriormente na exibição de métrica.

Cada definição de dimensão inclui os seguintes campos:

Exemplo:

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

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

  # Dimension 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

Medidas são expressões que produzem resultados sem um nível de agregação pré-determinado. Eles devem ser expressos usando funções de agregação. Para fazer referência a uma medida em uma consulta, use a MEASURE função. As medidas podem referenciar campos base nos dados de origem, dimensões definidas anteriormente ou medidas definidas anteriormente.

Cada definição de medida inclui os seguintes campos:

Consulte funções de agregação para obter uma lista de funções de agregação.

Exemplo:

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

Dimensões da janela

O window campo define agregações em janelas, cumulativas ou semiadditivas para medidas. Para obter informações detalhadas sobre medidas de janela e casos de uso, consulte medidas de janela.

Cada especificação de janela inclui os seguintes campos:

Exemplo de medida de janela

O exemplo a seguir calcula uma contagem sem interrupção de 7 dias de clientes exclusivos:

version: 1.1
source: samples.tpch.orders

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

Materialização

O materialization campo configura a aceleração automática de consulta usando exibições materializadas. Para obter informações detalhadas sobre como a materialização funciona, os requisitos e as práticas recomendadas, consulte Materialização para exibições de métrica.

O materialization campo inclui os seguintes campos de nível superior:

Cada entrada inclui materialized_views os seguintes campos:

Exemplo de materialização

O exemplo a seguir define uma exibição de métrica com várias materializações:

version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate
  - name: order_status
    expr: o_orderstatus

measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
  - name: order_count
    expr: COUNT(1)

materialization:
  schedule: every 6 hours
  mode: relaxed
  materialized_views:
    - name: baseline
      type: unaggregated

    - name: daily_status_metrics
      type: aggregated
      dimensions:
        - order_date
        - order_status
      measures:
        - total_revenue
        - order_count

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

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 para a $$..$$ seção após AS. Altere o valor de version para 1.1.
3. Salve o modo de exibição de métrica.

ALTER VIEW metric_view_name AS
$$
# The notebook preserves inline comments
version: 1.1
source: samples.tpch.orders
dimensions:
- 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)
$$

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 de version 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"
$$

Para obter o histórico de versão de especificação do YAML e os requisitos mínimos de runtime para cada recurso, consulte a disponibilidade do recurso de exibição de métrica.