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:

Campo	Tipo	Descrição
`version`	String	Obrigatório Versão da especificação de exibição de métrica. Consulte as versões de especificação do YAML.
`comment`	String	Optional. Descrição da visualização de métrica.
`source`	String	Obrigatório Os dados de origem da exibição de métrica. Pode ser qualquer ativo do Catálogo do Unity semelhante a uma tabela, incluindo uma exibição de métrica ou uma consulta SQL. Consulte a origem.
`filter`	String	Optional. Uma expressão booliana sql que se aplica a todas as consultas. Consulte Filtro.
`joins`	Array	Optional. Esquema estelar e junções de esquema floco de neve. Consulte Junções.
`dimensions`	Array	Condicional. Definições de dimensão, incluindo nome, expressão e metadados semânticos opcionais. Obrigatório se não `measures` for especificado. Consulte Dimensões.
`measures`	Array	Condicional. Definições de medida, incluindo nome, expressão agregada e metadados semânticos opcionais. Obrigatório se não `dimensions` for especificado. Consulte Medidas.
`materialization`	Objeto	Optional. Configuração para acelerar consultas com exibições materializadas. Inclui agendamento de atualização e definições de exibição materializadas. Consulte Materialização.

Fonte

O source campo especifica a fonte de dados para a exibição de métrica. As fontes com suporte incluem tabelas, exibições, exibições de métrica e consultas SQL. 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

Observação

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

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.

Observação

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

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

Campo	Tipo	Descrição
`name`	String	Obrigatório Alias para a tabela unida ou a consulta SQL. Use esse alias ao referenciar colunas da tabela unida em dimensões ou medidas.
`source`	String	Obrigatório Nome de três partes da tabela a ser unida. Também pode ser uma consulta SQL.
`on`	String	Condicional. Expressão booliana definindo a condição de junção. Obrigatório se `using` não for especificado.
`using`	Array	Condicional. Lista de nomes de coluna presentes na tabela pai e na tabela unida. Obrigatório se `on` não for especificado.
`joins`	Array	Optional. Uma lista de definições de junção aninhadas para modelagem de esquema floco de neve. Consulte a disponibilidade do recurso de exibição de métrica para obter requisitos mínimos de runtime.

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:

ON cláusula: usa uma expressão booliana para definir a condição de junção.
USING cláusula: 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)

Observação

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

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:

Campo	Tipo	Descrição
`name`	String	Obrigatório O alias de coluna para a dimensão.
`expr`	String	Obrigatório Uma expressão SQL que pode referenciar colunas dos dados de origem ou de uma dimensão definida anteriormente.
`comment`	String	Optional. Descrição da dimensão. Aparece no Catálogo do Unity e nas ferramentas de documentação.
`display_name`	String	Optional. Rótulo que aparece em ferramentas de visualização. Limitado a 255 caracteres. Requer a especificação YAML 1.1. Consulte a disponibilidade do recurso de exibição de métrica.
`format`	Mapa	Optional. Especificação de formato de como os valores são exibidos. Requer a especificação YAML 1.1. Consulte as especificações de formato.
`synonyms`	Array	Optional. Nomes alternativos para ferramentas de IA e BI para descobrir a dimensão. Até 10 sinônimos, cada um limitado a 255 caracteres. Requer a especificação YAML 1.1. Consulte Sinônimos.

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:

Campo	Tipo	Descrição
`name`	String	Obrigatório O alias da medida.
`expr`	String	Obrigatório Uma expressão SQL que contém uma ou mais funções de agregação.
`comment`	String	Optional. Descrição da medida. Aparece no Catálogo do Unity e nas ferramentas de documentação.
`display_name`	String	Optional. Rótulo que aparece em ferramentas de visualização. Limitado a 255 caracteres. Requer a especificação YAML 1.1. Consulte a disponibilidade do recurso de exibição de métrica.
`format`	Mapa	Optional. Especificação de formato de como os valores são exibidos. Requer a especificação YAML 1.1. Consulte as especificações de formato.
`synonyms`	Array	Optional. Nomes alternativos para ferramentas de IA e BI para descobrir a medida. Até 10 sinônimos, cada um limitado a 255 caracteres. Requer a especificação YAML 1.1. Consulte a disponibilidade do recurso de exibição de métrica.
`window`	Array	Optional. Especificações de janela para agregações em janelas, cumulativas ou semiadditivas. Quando não especificada, a medida se comporta como uma agregação padrão. Veja as medidas da Janela.

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

Importante

Esse recurso é experimental.

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:

Campo	Tipo	Descrição
`order`	String	Obrigatório A dimensão que determina a ordenação da janela. (1)
`range`	String	Obrigatório A extensão da janela. Consulte os valores com `range` suporte.
`semiadditive`	String	Obrigatório Método de agregação. Valores com suporte: `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ções de janela imprevisíveis e podem levar a resultados de agregação incorretos.

Valores de `range` com suporte

current: linhas em que o valor de ordenação da janela é igual ao valor da linha atual.
cumulative: todas 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 indo para trás pelas unidades de tempo especificadas, por exemplo trailing 7 day. Não inclui a unidade atual.
leading <value> <unit>: linhas da linha atual daqui para frente pelas unidades de tempo especificadas, por exemplo leading 3 month. Não inclui a unidade atual.
all: todas as linhas, independentemente do valor de ordenação da janela.

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

Importante

Esse recurso é experimental.

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:

Campo	Tipo	Descrição
`schedule`	String	Obrigatório Agendamento de atualização. Usa a mesma sintaxe que a cláusula schedule em exibições materializadas. Não há suporte para a cláusula `TRIGGER ON UPDATE`.
`mode`	String	Obrigatório Deve ser definido como `relaxed`.
`materialized_views`	Array	Obrigatório Lista de exibições materializadas a serem materializadas. Cada entrada requer os campos descritos abaixo.

Cada entrada inclui materialized_views 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 com suporte: `aggregated` (requer `dimensions`, `measures`ou ambos) ou `unaggregated`.
`dimensions`	Array	Condicional. Lista de nomes de dimensão a serem materializados. Obrigatório se `type` for `aggregated` e não `measures` for especificado.
`measures`	Array	Condicional. Lista de nomes de medidas a serem materializados. Obrigatório se `type` for `aggregated` e não `dimensions` for especificado.

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 referenciar nomes de coluna que contêm espaços ou caracteres especiais em expressões YAML, coloque o nome da coluna em backticks. 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

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

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

Use aspas duplas, aspas simples ou nenhuma aspa ao redor do nome da coluna.

Nome da coluna com espaços

Coluna de origem: `First Name`

expr: '`First Name`'

Use acentos graves para escapar de espaços. Coloque a expressão inteira entre aspas duplas.

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

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

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

Se a expressão não começar com um backtick, as aspas duplas não serão necessárias.

Nome da coluna que contém aspas

Coluna de origem: "name"

expr: '`"name"`'

Use backticks para escapar das aspas duplas no nome da coluna. Coloque a expressão entre aspas simples.

Expressões com dois pontos

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

Observação

YAML interpreta dois pontos sem estar entre aspas como separadores chave-valor. Sempre use aspas duplas em torno de expressões com dois pontos.

Expressões de várias linhas

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

Observação

Use o escalar de bloco | depois de 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 correta análise.

Atualizar para o YAML 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.
Comentários do Catálogo do Unity: Comentários armazenados no Catálogo do Unity para a exibição de métrica ou suas colunas. 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.

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:

Use o ALTER VIEW comando em um notebook ou editor do SQL.
Copie a definição original do YAML para a $$..$$ seção após AS. Altere o valor de version para 1.1.
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)
$$

Aviso

A execução de ALTER VIEW remove os comentários do Unity Catalog, a menos que eles sejam incluídos explicitamente nos campos comment da definição YAML. Para preservar os comentários mostrados no Catálogo do Unity, consulte a Opção 2.

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

Observação

As diretrizes a seguir se aplicam somente ao usar o ALTER VIEW comando em um notebook ou editor do SQL. Se você atualizar sua exibição de métrica para a versão 1.1 usando a interface do usuário do editor YAML, a interface do usuário do editor YAML preservará automaticamente os comentários do Catálogo do Unity.

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.
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.

Comentários

Esta página foi útil?

Last updated on 2026-04-25

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

Visão geral do YAML

Fonte

Fonte de ativo semelhante à tabela

Origem da consulta SQL

Filter

Joins

Junções de esquema estrela

Junções de esquema snowflake

Dimensões

Medidas

Dimensões da janela

Valores de range com suporte

Exemplo de medida de janela

Materialização

Exemplo de materialização

Referências ao nome da coluna

Exemplos de formatação

Referenciar um nome de coluna

Sem espaços

Nome da coluna com espaços

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

Nome da coluna que contém aspas

Expressões com dois pontos

Expressões de várias linhas

Atualizar para o YAML 1.1

Tipos de comentários

Considerações sobre atualização

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

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

Comentários

Recursos adicionais

Valores de `range` com suporte