Vista métrica Referência da sintaxe YAML

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

Para requisitos de tempo mínimo de execução e de versão da especificação YAML para cada funcionalidade, veja Disponibilidade de funcionalidades na vista 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:

Fonte

O source campo especifica a fonte de dados para a vista métrica. Pode usar um asset semelhante a uma tabela, como tabelas, vistas e vistas métricas, ou uma consulta SQL como fonte. A composabilidade aplica-se em várias vistas métricas. Ao usar uma vista métrica como fonte, pode referenciar as suas dimensões e medidas na nova vista métrica. Consulte Composabilidade.

Fonte de ativo em forma de tabela

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

source: catalog.schema.source_table

Fonte de 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 aplica-se a todas as consultas que referenciam a vista métrica. Escreva filtros como expressões SQL booleanas.

# 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 vistas métricas suportam tanto junções diretas de uma tabela de factos para tabelas de dimensões (esquema estrela) como uniões multi-saltos através de tabelas de dimensões normalizadas (esquemas floco de neve). Também pode juntar-se a uma consulta SQL usando uma SELECT instrução. Veja Usar uma consulta SQL como fonte.

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

Juntas de esquemas estelares

Em um esquema em estrela, o source é a tabela de fatos e se une a uma ou mais tabelas de dimensão usando um LEFT OUTER JOINarquivo . As vistas métricas juntam as tabelas de factos e dimensões 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 booleana para definir a condição de junção.
• cláusula USE: Lista colunas com o mesmo nome tanto na tabela principal como na tabela unida.

A união deve seguir uma relação muitos-para-um. Em casos de muitos-para-muitos, a primeira linha correspondente da tabela de dimensão 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)

Juntas de esquemas floco de neve

Um esquema de floco de neve estende um esquema de estrela normalizando tabelas de dimensões e conectando-as a subdimensões. Isto cria uma estrutura de junção multinível. Consulte a disponibilidade de funcionalidades na vista métrica para requisitos mínimos de tempo de execução.

Para definir um esquema snowflake, aninha-se joins dentro de uma definição de junção parental:

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 nas cláusulas SELECT, WHERE e GROUP BY no momento da consulta. Cada expressão deve retornar um valor escalar. As dimensões podem referenciar colunas a partir dos dados de origem ou dimensões definidas anteriormente na vista 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

As medidas são expressões que produzem resultados sem um nível pré-determinado de agregação. Devem ser expressos utilizando funções agregadas. Para referenciar uma medida numa 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 Agregar funções para obter uma lista de funções agregadas.

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

Medidas de janela

O window campo define agregações em janelas, cumulativas ou semiaditivas para as medidas. Para 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 seguinte calcula uma contagem móvel de 7 dias de clientes únicos:

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 consultas usando vistas materializadas. Para informações detalhadas sobre como funciona a materialização, requisitos e melhores práticas, consulte Materialização para vistas métricas.

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 seguinte define uma vista métrica com múltiplas 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 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.

Usar expressões com dois pontos

Recuo de várias linhas

Atualiza o teu YAML para a versão 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 a $$..$$ secção seguinte ASa . Altere o valor de version para 1.1.
3. Salve a visualização 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 Unity

1. Copie todos os comentários do Catálogo Unity para os campos apropriados comment na sua definição de YAML. Altere o valor de version 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"
$$

Para o histórico de versões da especificação YAML e os requisitos mínimos de execução para cada funcionalidade, consulte Disponibilidade de funcionalidades na vista métrica.