Vista métrica Referência da sintaxe YAML

As definições de vista métrica usam a sintaxe padrão YAML para declarar a fonte, joins, campos, medidas, filtros, medidas janela e materialização. As secções seguintes documentam a gramática completa de cada um.

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.

Editar YAML no editor de vista métrica

Pode escrever e editar o YAML descrito nesta página diretamente no editor de vista métrica. No Explorador de Catálogos, abra uma vista métrica e clique no <> botão para editar a definição. Para gerar YAML a partir de uma descrição em linguagem natural, abra o Código Genie a partir do editor. Para o guia completo do editor, consulte Criar uma vista métrica.

Campos YAML de topo

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

Source

O source campo especifica a fonte de dados para a vista métrica. As fontes suportadas incluem tabelas, vistas, vistas métricas e consultas SQL. A composabilidade aplica-se em várias vistas métricas. Ao usar uma vista métrica como fonte, pode referenciar os seus campos 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

Parâmetros

O bloco parameters define valores nomeados que os chamadores passam quando consultam a vista da métrica como uma função com valores de tabela. Para saber quando e como usar parâmetros, incluindo consultar uma vista métrica parametrizada, veja Usar parâmetros com vistas métricas.

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

O exemplo seguinte define um discount parâmetro e referencia-o numa 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 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

Junções em vistas métricas suportam tanto junções diretas de uma tabela de factos para tabelas de dimensões (esquema estrela) como junções multi-etapas 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:

• ON cláusula: Usa uma expressão booleana para definir a condição de junção.
• USING cláusula: Lista colunas com o mesmo nome tanto na tabela principal como na tabela junta.

A associação tem de seguir uma relação de 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

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)

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

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

Junções de um para muitos

O cardinality campo define a relação entre a fonte e uma tabela unida. O padrão, many_to_one, trata a tabela unida como uma consulta de dimensão. Definido cardinality: one_to_many para tratar a tabela unida como uma fonte de factos que o motor agrega independentemente no grão de origem, o que permite que uma única linha de origem corresponda a várias linhas na tabela junta. As junções de um para muitos requerem o Databricks Runtime 18.1 ou posterior e a versão 1.1 da especificação YAML. Ver disponibilidade da funcionalidade de vista métrica.

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

• Uma coluna um-para-muitos não pode ser usada numa fields definição, porque um campo deve resolver para um único valor por linha de origem.
• Uma única função de agregação deve referenciar colunas de uma fonte. Pode aplicar a aritmética entre os 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. As junções de irmãos de topo podem misturar cardinalidades.
• Referenciar uma coluna numa junção aninhada com o seu caminho de pontos completo através dos nomes da junção, como orders.order_items.item_id.

O exemplo seguinte junta-se orders a uma customers fonte com cardinality: one_to_many para que as medidas de encomenda se agreguem sem duplicar linhas de clientes:

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 detalhes conceptuais e exemplos de junções aninhadas e irmãs, veja Cardinalidade de junção.

Otimizar junções com rely

Use o rely campo numa junção para declarar garantias sobre a relação que o analisador de consultas utiliza ao planear consultas. Estas garantias permitem ao motor planear consultas de forma mais eficiente e reduzir a análise de dados, especialmente quando os campos da tabela unida são referenciados em filtros.

O rely mapa suporta os seguintes campos:

O exemplo seguinte permite at_most_one_match numa junção muitos-para-um de orders para customer. As consultas que filtram ou agrupam por atributos do cliente são as que mais beneficiam:

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 vista métrica usadas em SELECT, WHERE, e GROUP BY cláusulas no momento da consulta. Cada expressão deve retornar um valor escalar. Os campos podem referenciar colunas a partir dos dados de origem ou campos definidos anteriormente na vista métrica.

Um campo pode ser:

• Uma coluna categórica ou de agrupamento, como uma região, estatuto ou departamento.
• Uma coluna numérica não agregada, como uma idade, preço ou quantidade. Os 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

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 colunas base nos dados de origem, campos definidos 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.

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 superiores com especificação YAML 1.1

Na definição de uma fields ou measures ou, pode usar um coringa (*) no expr campo para importar todas as colunas da fonte ou de uma tabela unida sem listar cada uma. Isto é útil quando se quer que uma vista métrica exponha todas as colunas de um ativo a montante, semelhante a SELECT * uma vista padrão. O Azure Databricks expande o coringa para colunas concretas quando cria ou substitui a vista métrica, e deriva o nome de cada coluna a partir do nome da coluna de origem.

Tal como as definições explícitas de colunas, as expressões coringa são expandidas quando se cria a vista métrica. Para apanhar colunas adicionadas à fonte mais tarde, recrie a vista métrica com CREATE OR REPLACE ou ALTER.

Os curingas suportam as seguintes formas:

As seguintes regras aplicam-se às expressões coringa:

• Omite o name campo. O Azure Databricks deriva nomes de colunas da fonte, por isso name não é permitido numa expressão wildcard.
• Metadados semânticos não são permitidos numa expressão wildcard. Não definas comment, display_name, format, nem synonyms num coringa. Para adicionar metadados a uma coluna específica, exclua-a do coringa com EXCEPT e defina-a explicitamente.
• Numa measures definição, um curinga importa medidas apenas de uma fonte de visualização métrica. As tabelas base não têm medidas, por isso um coringa expande-se para nenhuma medida quando a fonte é uma tabela base.
• Não podes referenciar uma coluna importada por um coringa pelo seu nome derivado numa expressão posterior fields ou measures expressão. Consulte a coluna de origem com o seu caminho completo em vez disso.

Colisões de nomes de resolução

Quando importa colunas de mais do que uma fonte com um coringa, colunas que partilham um nome (como id ou date) colidem e causam um erro ao guardar a definição. Para resolver uma colisão, exclua a coluna de cada curinga com EXCEPT, depois defina-a explicitamente com um nome único:

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

Exemplo de coringa

A definição seguinte importa todas as colunas da fonte e de uma tabela unida, exclui duas colunas e define explicitamente uma coluna 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'

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:

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

• current: Linhas em que o valor da ordem das janelas é igual ao valor da linha âncora.
• cumulative: Todas as linhas em que o valor da ordem das janelas é menor ou igual ao valor da linha âncora.
• trailing <value> <unit> [inclusive | exclusive]: Linhas da linha âncora a recuar pelas unidades de tempo especificadas, por trailing 7 dayexemplo . O opcional inclusive ou exclusive modificador requer Databricks Runtime 18.1 e especificação YAML versão 1.1 ou superior, e controla se a linha âncora está incluída na janela. A predefinição é exclusive. Veja Incluir ou excluir a linha âncora.
• leading <value> <unit> [inclusive | exclusive]: Linhas da linha âncora a avançar pelas unidades de tempo especificadas, por leading 3 monthexemplo . O opcional inclusive ou exclusive modificador requer Databricks Runtime 18.1 e especificação YAML versão 1.1 ou superior, e controla se a linha âncora está incluída na janela. A predefinição é exclusive. Veja Incluir ou excluir a linha âncora.
• all: Todas as linhas independentemente do valor de ordem da janela.

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

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

Passar um tamanho de janela como parâmetro

Em vez de codificar o valor numérico num trailing ou leadingrangeoffset num , podes referenciar um parâmetro, para que o chamador passe o tamanho da janela quando consulta a vista métrica. Isto requer um SQL warehouse ou outro recurso de computação a correr Databricks Runtime 18.2 ou superior.

As seguintes regras aplicam-se 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 apenas um nome de parâmetro, não uma expressão. Por exemplo, use trailing window_size day, não trailing window_size + 1 day. Também não pode escrever um sinal antes do nome do parâmetro, como -window_size num 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 mantém-se literal. Podes parametrizar apenas a magnitude numérica, não o período.

O exemplo seguinte define um window_size parâmetro e referencia-o num 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 vista métrica que define parâmetros, veja Consultar uma vista métrica com parâmetros.

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: 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 de nomes de colunas

Ao referenciar nomes de colunas que contenham espaços ou caracteres especiais em expressões YAML, inclua o nome da coluna em backticks. 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

Os exemplos seguintes mostram como formatar referências de colunas dependendo dos caracteres que contêm.

Sem espaços

Coluna fonte: revenue

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

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

Nome da coluna com espaços

Coluna fonte: `First Name`

expr: '`First Name`'

Use backticks para escapar de espaços. Coloque toda a expressão entre aspas duplas.

Nomes de colunas com espaços numa expressão SQL

Colunas fonte: `First Name`, `Last Name`

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

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

Nome da coluna contendo aspas

Coluna fonte: "name"

expr: '`"name"`'

Use os backticks para evitar as aspas duplas no nome da coluna. Inclua 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 multi-linha

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

Atualização para YAML 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 em linha ou de linha única escritos diretamente no ficheiro YAML.
• Comentários do Catálogo Unity: Comentários armazenados no Catálogo Unity para a vista métrica ou as suas colunas. Estes são separados dos comentários YAML.

Considerações sobre a atualização

Seleciona o caminho de atualização que corresponde à forma como queres tratar os comentários na tua vista métrica.

Opção 1: Preservar comentários YAML usando blocos de anotações ou o editor SQL

Se a sua vista métrica contiver comentários YAML (#) que pretende manter, use os seguintes passos:

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

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