métricas view referência de sintaxe YAML

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

Para requisitos mínimos de tempo de execução e versão da especificação YAML para cada recurso, consulte métricas view recurso availability.

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:

campo	Tipo	Descrição
`version`	String	Obrigatório. Versão da especificação view de métricas. Consulte as versões da especificação YAML.
`comment`	String	Opcional. Descrição da view de métricas.
`source`	String	Obrigatório. Os dados de origem para a view de métricas. Pode ser qualquer tabela do Unity Catalog ativa, incluindo uma view de métricas ou uma consulta SQL . Ver fonte.
`filter`	String	Opcional. Uma expressão booleana SQL que se aplica a todas as consultas. Consulte o filtro.
`joins`	matriz	Opcional. Junção dos esquemas estrela e floco de neve. See join.
`dimensions`	matriz	Condicional. Definições de dimensões, incluindo nome, expressão e metadados semânticos opcionais. Obrigatório se nenhum `measures` for especificado. Veja as dimensões.
`measures`	matriz	Condicional. Definições de medidas, incluindo nome, expressão agregada e metadados semânticos opcionais. Obrigatório se nenhum `dimensions` for especificado. Ver Medidas.
`materialization`	Objeto	Opcional. Configuração para acelerar consultas com visão materializada. Inclui refresh das definições view programática e materializada. Ver Materialização.

Fonte

O campo source especifica a fonte de dados para a view de métricas. As fontes suportadas incluem tabelas, visualizações, visualizações métricas e consultas SQL . A capacidade de composição se aplica a toda a visão das métricas. Ao usar uma view de métricas como fonte, você pode referenciar suas dimensões e medidas na nova view de métricas. Veja Composability.

Fonte ativa em forma de tabela

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

YAML
source: catalog.schema.source_table

Fonte da consulta SQL

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

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

nota

Ao usar uma consulta SQL como fonte com uma cláusula JOIN , defina restrições key primária e estrangeira nas tabelas subjacentes e use a opção RELY para obter o desempenho ideal da consulta. Para obter mais informações, consulte Declarar relações key primária e key estrangeira e Otimização de consultas usando restrições key primária.

Filtro

Um filtro na definição YAML se aplica a todas as consultas que fazem referência à view métricas. Escreva filtros como expressões booleanas SQL .

YAML
# 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'

join

A funcionalidade de junção na visualização de métricas suporta tanto a junção direta de uma tabela de fatos para tabelas de dimensões (esquema em estrela) quanto a junção de múltiplos saltos entre tabelas de dimensões normalizadas (esquemas em floco de neve). Você também pode join a uma consulta SQL usando uma instrução SELECT . Consulte Usar uma consulta SQL como fonte.

nota

Tabelas unidas não podem incluir colunas do tipo MAP . Para desempacotar valores de colunas do tipo MAP , consulte Explodir elementos aninhados de um mapa ou matriz.

Cada definição join inclui os seguintes campos:

campo	Tipo	Descrição
`name`	String	Obrigatório. Alias para a tabela resultante da junção ou para a consulta SQL. Use esse alias ao referenciar colunas da tabela combinada em dimensões ou medidas.
`source`	String	Obrigatório. Nome da tabela a join, composto por três partes. Também pode ser uma consulta SQL.
`on`	String	Condicional. Expressão Boolean que define a condição join . Obrigatório se `using` não for especificado.
`using`	matriz	Condicional. Lista dos nomes das colunas presentes tanto na tabela principal quanto na tabela resultante da junção. Obrigatório se `on` não for especificado.
`joins`	matriz	Opcional. Uma lista de definições join aninhadas para modelagem de esquema em floco de neve. Consulte as métricas view a disponibilidade de recursos e os requisitos mínimos de tempo de execução.

junção de esquema em estrela

Em um esquema em estrela, o source é a tabela de fatos e se junta a uma ou mais tabelas de dimensão usando um LEFT OUTER JOIN. A visualização de métricas join as tabelas de fatos e dimensões necessárias para a consulta específica, com base nas colunas selecionadas.

Especifique as colunas join usando uma cláusula ON ou uma cláusula USING :

ON Cláusula: Utiliza uma expressão booleana para definir a condição join .
USING Cláusula: Lista as colunas com o mesmo nome tanto na tabela principal quanto na tabela resultante da junção.

A join deve seguir uma relação de muitos para um. Em casos de relacionamento muitos-para-muitos, a primeira linha correspondente da tabela de dimensão unida é selecionada.

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

nota

O namespace source faz referência a colunas da fonte da view métricas, enquanto o name de uma join se refere a colunas da tabela unida. Por exemplo, em source.l_orderkey = orders.o_orderkey, source refere-se a lineitem e orders refere-se à tabela unida. Se nenhum prefixo for fornecido em uma cláusula on , a referência padrão será a tabela unida.

Junção de esquemaSnowflake

Um esquema em floco de neve estende um esquema em estrela normalizando tabelas de dimensão e conectando-as a subdimensões. Isso cria uma estrutura join multinível. Consulte as métricas view a disponibilidade de recursos e os requisitos mínimos de tempo de execução.

Para definir um esquema em forma de floco de neve, aninhe joins dentro de uma definição join pai:

YAML
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 fazer referência a colunas dos dados de origem ou a dimensões definidas anteriormente na view de métricas.

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

campo	Tipo	Descrição
`name`	String	Obrigatório. O alias da coluna para a dimensão.
`expr`	String	Obrigatório. Uma expressão SQL que pode fazer referência a colunas dos dados de origem ou a uma dimensão previamente definida.
`comment`	String	Opcional. Descrição da dimensão. Aparece no Unity Catalog e nas ferramentas de documentação.
`display_name`	String	Opcional. rótulo que aparece em ferramentas de visualização. Limitado a 255 caracteres. Requer a especificação YAML 1.1. Veja métricas view disponibilidade de recursos.
`format`	Mapa	Opcional. Especificação do formato de exibição dos valores. Requer a especificação YAML 1.1. Consulte as especificações de formato.
`synonyms`	matriz	Opcional. Nomes alternativos para ferramentas de AI e BI para descobrir a dimensão. Até 10 sinônimos, cada um limitado a 255 caracteres. Requer a especificação YAML 1.1. Veja Sinônimos.

Exemplo:

YAML
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 de agregação predeterminado. Elas devem ser expressas usando funções agregadas. Para referenciar uma medida em uma consulta, use a função MEASURE . As medidas podem fazer referência a campos base nos dados de origem, dimensões definidas anteriormente ou medidas definidas anteriormente.

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

campo	Tipo	Descrição
`name`	String	Obrigatório. O pseudônimo da medida.
`expr`	String	Obrigatório. Uma expressão SQL contendo uma ou mais funções de agregação.
`comment`	String	Opcional. Descrição da medida. Aparece no Unity Catalog e nas ferramentas de documentação.
`display_name`	String	Opcional. rótulo que aparece em ferramentas de visualização. Limitado a 255 caracteres. Requer a especificação YAML 1.1. Veja métricas view disponibilidade de recursos.
`format`	Mapa	Opcional. Especificação do formato de exibição dos valores. Requer a especificação YAML 1.1. Consulte as especificações de formato.
`synonyms`	matriz	Opcional. Nomes alternativos para ferramentas de AI e BI para descobrir a métrica. Até 10 sinônimos, cada um limitado a 255 caracteres. Requer a especificação YAML 1.1. Veja métricas view disponibilidade de recursos.
`window`	matriz	Opcional. Especificações de janelas para agregações em janelas, cumulativas ou semiaditivas. Quando não especificada, a medida comporta-se como um agregado padrão. Veja Medidas da janela.

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

Exemplo:

YAML
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 da janela

info

Experimental

Este recurso é experimental.

O campo window define agregações em janela, cumulativas ou semiaditivas 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:

campo	Tipo	Descrição
`order`	String	Obrigatório. A dimensão que determina a ordem da janela. (1)
`range`	String	Obrigatório. A extensão da janela. Consulte os valores suportados `range`.
`semiadditive`	String	Obrigatório. Método de agregação. Valores suportados: `first` ou `last`.

(1) A dimensão referenciada deve ser determinística. Expressões não determinísticas como rand(), uuid() ou current_timestamp() produzem ordenação de janelas imprevisível e podem levar a resultados de agregação incorretos.

Valores suportados `range`

currentLinhas em que o valor de ordenação da janela é igual ao valor da linha atual.
cumulativeTodas as linhas em que o valor de ordenação da janela é menor ou igual ao valor da linha atual.
trailing <value> <unit>: Linhas da linha atual retrocedendo pelas unidades de tempo especificadas, por exemplo trailing 7 day. Não inclui a unidade atual.
leading <value> <unit>: Linhas da linha atual avançando pelas unidades de tempo especificadas, por exemplo leading 3 month. Não inclui a unidade atual.
allTodas as linhas, independentemente do valor de ordenação da janela.

Exemplo de medida de janela

O exemplo a seguir calcula uma contagem móvel de 7 dias de clientes únicos:

YAML
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

info

Experimental

Este recurso é experimental.

O campo materialization configura a aceleração automática de consultas usando a visão materializada. Para informações detalhadas sobre como a materialização funciona, requisitos e melhores práticas, consulte Materialização para visualização de métricas.

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

campo	Tipo	Descrição
`schedule`	String	Obrigatório. atualizar programar. Utiliza a mesma sintaxe da cláusula programar na visão materializada. A cláusula `TRIGGER ON UPDATE` não é suportada.
`mode`	String	Obrigatório. Deve ser definido como `relaxed`.
`materialized_views`	matriz	Obrigatório. Lista de visões materializadas a serem materializadas. Cada entrada requer os campos descritos abaixo.

Cada entrada em materialized_views inclui os seguintes campos:

campo	Tipo	Descrição
`name`	String	Obrigatório. O nome da materialização.
`type`	String	Obrigatório. Tipo de materialização. Valores suportados: `aggregated` (requer `dimensions`, `measures` ou ambos) ou `unaggregated`.
`dimensions`	matriz	Condicional. Lista de nomes de dimensões a serem materializadas. Obrigatório se `type` for `aggregated` e nenhum `measures` for especificado.
`measures`	matriz	Condicional. Lista de nomes de medidas a serem materializadas. Obrigatório se `type` for `aggregated` e nenhum `dimensions` for especificado.

Exemplo de materialização

O exemplo a seguir define uma view de métricas com múltiplas materializações:

YAML
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 aos nomes das colunas

Ao referenciar nomes de colunas que contenham espaços ou caracteres especiais em expressões YAML, coloque o nome da coluna entre crases (`). Se a expressão começar com um 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 um acento grave (`).

Exemplos de formatação

Utilize os exemplos a seguir para aprender como formatar YAML corretamente em cenários comuns.

Faça referência ao nome de uma coluna.

Os exemplos a seguir mostram como formatar referências de coluna dependendo dos caracteres que elas contêm.

Sem espaços

Coluna de origem: revenue

YAML
expr: "revenue"
expr: 'revenue'
expr: revenue

Use aspas duplas, aspas simples ou nenhuma aspa em torno do nome da coluna.

Nome da coluna com espaços

Coluna de origem: `First Name`

YAML
expr: '`First Name`'

Use crases (`) para escapar espaços. Coloque toda a expressão entre aspas duplas.

Nomes de colunas com espaços em uma expressão SQL

Colunas de origem: `First Name`, `Last Name`

YAML
expr: CONCAT(`First Name`, ' ', `Last Name`)

Se a expressão não começar com um crase (`), as aspas duplas não são necessárias.

Nome da coluna que contém aspas

Coluna de origem: "name"

YAML
expr: '`"name"`'

Use crases (`) para escapar as aspas duplas no nome da coluna. Coloque a expressão entre aspas simples.

Expressões com dois pontos

YAML
expr: "CASE WHEN `Customer Tier` = 'Enterprise: Premium' THEN 1 ELSE 0 END"

nota

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

Expressões de múltiplas linhas

YAML
expr: |
  CASE WHEN
    revenue > 100 THEN 'High'
  ELSE 'Low'
  END

nota

Use o escalar de bloco | após expr: para expressões de várias linhas. Todas as linhas devem ser recuadas em pelo menos dois espaços além da key expr para serem analisadas corretamente.

Atualize para YAML 1.1

A atualização de uma view de métricas para a versão 1.1 da especificação YAML 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 em linha ou de linha única escritos diretamente no arquivo YAML.
ComentáriosUnity Catalog : Comentários armazenados no Unity Catalog para a view de métricas ou suas colunas. Esses itens são distintos dos comentários YAML.

Considerações sobre a atualização

Escolha o caminho de atualização que corresponda à forma como deseja lidar com os comentários na sua view de métricas.

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

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

Use o comando ALTER VIEW em um Notebook ou editor SQL .
Copie a definição YAML original para a seção $$..$$ após AS. Altere o valor de version para 1.1.
Salve a view dos métricas.

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

atenção

Executar ALTER VIEW remove os comentários Unity Catalog , a menos que estejam explicitamente incluídos nos campos comment da definição YAML. Para preservar os comentários exibidos no Unity Catalog, consulte a Opção 2.

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

nota

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

Copie todos os comentários do Unity Catalog para os campos comment apropriados em sua definição YAML. Altere o valor de version para 1.1.
Salve a view dos 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"
$$

Para a história da versão da especificação YAML e os requisitos mínimos de tempo de execução para cada recurso, consulte detalhes view disponibilidade do recurso.

Visão geral do YAML​

Fonte​

Fonte ativa em forma de tabela​

Fonte da consulta SQL​

Filtro​

join​

junção de esquema em estrela​

Junção de esquemaSnowflake​

Dimensões​

Medidas​

Medidas da janela​

Valores suportados range​

Exemplo de medida de janela​

Materialização​

Exemplo de materialização​

Referências aos nomes das colunas​

Exemplos de formatação​

Faça referência ao nome de uma coluna.​

Sem espaços​

Nome da coluna com espaços​

Nomes de colunas com espaços em uma expressão SQL​

Nome da coluna que contém aspas​

Expressões com dois pontos​

Expressões de múltiplas linhas​

Atualize para YAML 1.1​

Tipos de comentários​

Considerações sobre a atualização​

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

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

Visão geral do YAML

Fonte

Fonte ativa em forma de tabela

Fonte da consulta SQL

Filtro

join

junção de esquema em estrela

Junção de esquemaSnowflake

Dimensões

Medidas

Medidas da janela

Valores suportados `range`

Exemplo de medida de janela

Materialização

Exemplo de materialização

Referências aos nomes das colunas

Exemplos de formatação

Faça referência ao nome de uma coluna.

Sem espaços

Nome da coluna com espaços

Nomes de colunas com espaços em uma expressão SQL

Nome da coluna que contém aspas

Expressões com dois pontos

Expressões de múltiplas linhas

Atualize para YAML 1.1

Tipos de comentários

Considerações sobre a atualização

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

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