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

As definições de exibição de métrica usam sintaxe YAML padrão para declarar a origem, junções, campos, medidas, filtros, medidas de janela e materialização. As seções a seguir documentam a gramática completa para cada um.

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.

Editar YAML no editor de exibição de métrica

Você pode escrever e editar o YAML descrito nesta página diretamente no editor de modo de exibição de métrica. No Gerenciador de Catálogos, abra uma exibição de métrica e clique no <> botão para editar a definição. Para gerar YAML a partir de uma descrição de linguagem natural, abra o Genie Code do editor. Para obter o passo a passo completo do editor, consulte Criar uma exibição de métrica.

Campos YAML de nível superior

A definição yaml para uma exibição de métrica inclui os seguintes campos de nível superior:

Source

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 seus campos 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

Parâmetros

O parameters bloco define valores nomeados que os chamadores passam quando consultam a exibição de métrica como uma função com valor de tabela. Para quando e como usar parâmetros, incluindo a consulta de uma exibição de métrica parametrizada, consulte Usar parâmetros com exibições de métrica.

Cada definição de parâmetro inclui os seguintes campos:

O exemplo a seguir define um discount parâmetro e faz referência a ele em uma expressão de medida:

version: 1.1
source: main.default.sales

parameters:
  - name: discount
    data_type: double
    default: 0

fields:
  - name: product
    expr: product

measures:
  - name: discountedSales
    expr: SUM((1 - discount) * amount)

Filtro

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 é a tabela de fatos e se conecta 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 uma relação 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

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

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

Junções um-para-muitos

O cardinality campo define a relação entre a origem e uma tabela unida. O padrão trata many_to_onea tabela unida como uma pesquisa de dimensão. Definido cardinality: one_to_many para tratar a tabela unida como uma fonte de fato que o mecanismo agrega independentemente no grão de origem, o que permite que uma única linha de origem corresponda a várias linhas na tabela unida. As junções de um para muitos exigem o Databricks Runtime 18.1 ou posterior e a versão 1.1 da especificação YAML. Consulte a disponibilidade do recurso de exibição de métrica.

As seguintes regras se aplicam a junções um para muitos:

• Uma coluna um para muitos não pode ser usada em uma fields definição, pois um campo deve ser resolvido para um único valor por linha de origem.
• Uma única função de agregação deve referenciar colunas de uma fonte. Você pode aplicar aritmética nos resultados de agregações separadas, como count(orders.order_id) / count(*).
• Todos os descendentes de uma junção um-para-muitos também devem ser one_to_many. Junções de irmãos de alto nível podem misturar cardinalidades.
• Referencie uma coluna em uma junção aninhada com seu caminho de ponto completo por meio dos nomes de junção, como orders.order_items.item_id.

O exemplo a seguir une-se orders a uma customers origem com cardinality: one_to_many a qual as medidas de pedido são agregadas sem duplicar linhas do cliente:

version: 1.1
source: main.sales.customers

joins:
  - name: orders
    source: main.sales.orders
    on: orders.customer_id = source.customer_id
    cardinality: one_to_many

fields:
  - name: customer_name
    expr: customer_name

measures:
  - name: customer_count
    expr: count(*)
  - name: order_count
    expr: count(orders.order_id)
  - name: total_order_revenue
    expr: sum(orders.amount)

Para obter detalhes conceituais e exemplos de junção aninhada e irmão, consulte Junção de cardinalidade.

Otimizar junções com rely

Use o rely campo em uma junção para declarar garantias sobre a relação que o analisador de consulta usa ao planejar consultas. Essas garantias permitem que o mecanismo planeje consultas com mais eficiência e reduza os dados verificados, especialmente quando os campos da tabela unida são referenciados em filtros.

O rely mapa dá suporte aos seguintes campos:

O exemplo a seguir permite at_most_one_match uma junção muitos para um de orders .customer As consultas que filtram ou agrupam por atributos do cliente se beneficiam mais:

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    rely:
      at_most_one_match: true

fields:
  - name: Customer name
    expr: customer.c_name
  - name: Customer market segment
    expr: customer.c_mktsegment

measures:
  - name: Total revenue
    expr: SUM(o_totalprice)

Campos

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

Um campo pode ser:

• Uma coluna categórica ou de agrupamento, como uma região, status ou departamento.
• Uma coluna numérica não agregada, como idade, preço ou quantidade. Campos numéricos podem ser agregados em tempo de consulta usando funções SQL como SUM ou AVG.

Cada definição de campo inclui as seguintes propriedades:

Example:

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

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

  # Field 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 fazer referência a colunas base nos dados de origem, campos definidos 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.

Example:

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

Campos e medidas de importação em massa com curingas

Aplica-se a: Databricks Runtime 18.2 e superior com a especificação YAML 1.1

Em uma fields ou measures definição, você pode usar um curinga (*) no expr campo para importar todas as colunas da origem ou de uma tabela unida sem listar cada uma delas. Isso é útil quando você deseja que uma exibição de métrica exponha cada coluna de um ativo upstream, semelhante a SELECT * uma exibição padrão. Azure Databricks expande o curinga para colunas concretas ao criar ou substituir a exibição de métrica e deriva cada nome de coluna do nome da coluna de origem.

Assim como as definições de coluna explícitas, as expressões curinga são expandidas quando você cria a exibição de métrica. Para pegar as colunas adicionadas à origem posteriormente, recrie a exibição de métrica com CREATE OR REPLACE ou ALTER.

Os curingas dão suporte aos seguintes formulários:

As seguintes regras se aplicam a expressões curinga:

• Omita o name campo. Azure Databricks deriva nomes de coluna da origem, portantoname, não é permitido em uma expressão curinga.
• Metadados semânticos não são permitidos em uma expressão curinga. Não defina comment, display_nameou formatsynonyms em um curinga. Para adicionar metadados a uma coluna específica, exclua-os do curinga EXCEPT e defina-os explicitamente.
• Em uma measures definição, um curinga importa medidas somente de uma fonte de exibição de métrica. As tabelas base não têm medidas, portanto, um curinga se expande para nenhuma medida quando a origem é uma tabela base.
• Você não pode referenciar uma coluna importada por curinga por seu nome derivado em uma expressão ou fields posteriormeasures. Faça referência à coluna de origem com seu caminho completo.

Resolver colisões de nome

Quando você importa colunas de mais de uma fonte com um curinga, colunas que compartilham um nome (como id ou date) colidem e causam um erro ao salvar a definição. Para resolver uma colisão, exclua a coluna de cada caractere curinga e EXCEPTdefina-a explicitamente com um nome exclusivo:

fields:
  - expr: source.* EXCEPT (id)
  - expr: customer.* EXCEPT (id)
  - name: source_id
    expr: source.id
  - name: customer_id
    expr: customer.id

Exemplo curinga

A definição a seguir importa todas as colunas da origem e de uma tabela unida, exclui duas colunas e define uma coluna explicitamente para adicionar metadados:

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    joins:
      - name: nation
        source: samples.tpch.nation
        on: customer.c_nationkey = nation.n_nationkey

fields:
  # Import all columns from the source
  - expr: source.*

  # Import all columns from a joined table, excluding two
  - expr: customer.nation.* EXCEPT (n_name, n_comment)

  # Define a specific column explicitly to add metadata
  - name: nation_name
    expr: customer.nation.n_name
    comment: "Customer's nation"
    display_name: 'Nation Name'

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:

(1) O campo referenciado deve ser determinístico. 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 suportados de range

• current: linhas em que o valor de ordenação da janela é igual ao valor da linha de âncora.
• cumulative: todas as linhas em que o valor de ordenação da janela é menor ou igual ao valor da linha de âncora.
• trailing <value> <unit> [inclusive | exclusive]: linhas da linha de âncora indo para trás pelas unidades de tempo especificadas, por exemplo trailing 7 day. O modificador ou inclusive opcional exclusive requer o Databricks Runtime 18.1 e a especificação YAML versão 1.1 ou superior e controla se a linha de âncora está incluída na janela. O padrão é exclusive. Consulte Incluir ou excluir a linha de âncora.
• leading <value> <unit> [inclusive | exclusive]: linhas da linha de âncora daqui para frente pelas unidades de tempo especificadas, por exemplo leading 3 month. O modificador ou inclusive opcional exclusive requer o Databricks Runtime 18.1 e a especificação YAML versão 1.1 ou superior e controla se a linha de âncora está incluída na janela. O padrão é exclusive. Consulte Incluir ou excluir a linha de âncora.
• 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

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

Passe um tamanho de janela como parâmetro

Em vez de codificar o valor numérico em um trailing ou leadingrange ou em um offset, você pode referenciar um parâmetro, para que o chamador passe o tamanho da janela ao consultar a visualização da métrica. Isso requer um SQL warehouse ou outro recurso de computação rodando Databricks Runtime 18.2 ou superior.

As seguintes regras se aplicam a um parâmetro usado como tamanho de janela:

• Os data_type parâmetros devem ser integrais, como int, smallint, ou bigint.
• O valor deve ser um nome de parâmetro simples, não uma expressão. Por exemplo, use trailing window_size day, e não trailing window_size + 1 day. Você também não pode escrever um sinal antes do nome do parâmetro, como -window_size em um offset. Para passar um deslocamento negativo, coloque o sinal dentro do valor do parâmetro.
• O parâmetro não pode ser nomeado a partir de uma palavra-chave de janela, como um tipo de intervalo (trailing, leading), um período (day, month, year), uma palavra-chave de inclusividade (inclusive, exclusive), ou offset.
• A unidade permanece literal. Você pode parametrizar apenas a magnitude numérica, não o período.

O exemplo a seguir define um window_size parâmetro e o referencia em um trailing intervalo, de modo que cada chamador escolhe o número de dias na janela móvel:

version: 1.1
source: samples.tpch.orders

parameters:
  - name: window_size
    data_type: int
    default: 7

fields:
  - name: order_date
    expr: o_orderdate

measures:
  - name: rolling_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: 'Rolling Customers'
    window:
      - order: order_date
        range: trailing window_size day
        semiadditive: last

Para consultar uma visualização métrica que define parâmetros, veja Consultar uma visualização métrica com parâmetros.

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: prod.operations.orders_enriched_view
filter: revenue > 0
# filter, fields, and measures can't use invoker-dependent expressions: no current_user(), is_member(), etc.
# source can't have RLS, column masking, or ABAC policies

joins:
  - name: customers
    source: prod.operations.customers
    on: source.customer_id = customers.id
    # if one-to-many, all materializations below drop to exact match only

fields:
  - name: category
    expr: substring(category, 5)
  - name: order_date
    expr: order_date

measures:
  - name: total_revenue
    expr: SUM(revenue)

  - name: number_of_suppliers
    expr: COUNT(DISTINCT supplier_id)

  - name: revenue_for_open_orders
    expr: SUM(revenue) FILTER (WHERE status = 'O')

  - name: blended_margin
    expr: SUM(revenue) - SUM(cost)

  - name: rolling_7day_customers
    expr: COUNT(DISTINCT customer_id)
    window:
      - order: order_date
        range: trailing 7 day
        semiadditive: last

materialization:
  schedule: every 6 hours
  mode: relaxed

  materialized_views:
    - name: baseline
      type: unaggregated
      # only one allowed per metric view; doesn't use dimensions or measures keys
      # no benefit if source is an unfiltered direct table reference

    - name: daily_status_metrics
      type: aggregated
      dimensions:
        - order_date
        - category # avoid overly granular dimensions, such as millisecond timestamps
      measures:
        - total_revenue # rollup-eligible
        - number_of_suppliers # exact match only (non-additive)
        - revenue_for_open_orders # rollup-eligible (deterministic filter)
        - blended_margin # exact match only (multiple aggregates)
        - rolling_7day_customers # exact match only (window measure)
      cluster_by:
        cols:
          - order_date
          - category
      partition_by:
        - order_date

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"

Expressões de várias linhas

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

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

Selecione o caminho de atualização que corresponde à forma 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:

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
fields:
- 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)"

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