Referência de sintaxe YAML da view de métricas
As definições de view de métricas usam a sintaxe YAML padrão para declarar a origem, joins, campos, medidas, filtros, medidas de window e materialização. As seções a seguir documentam a gramática completa de cada um.
Para os requisitos mínimos de Runtime e de versão de especificação YAML para cada recurso, consulte Disponibilidade de recurso da view de métricas.
Consulte a documentação da Especificação YAML 1.2.2 para saber mais sobre as especificações YAML.
Editar YAML no editor de view de métricas
Você pode escrever e editar o YAML descrito nesta página diretamente no editor de view de métricas. No Explorador de Catálogos, abra uma view de métricas e clique no botão <> para editar a definição. Para gerar YAML a partir de uma descrição em linguagem natural, abra o Genie Code no editor. Para o guia completo do editor, consulte Criar uma view de métricas.
Campos YAML de nível superior
A definição YAML de uma view de métricas inclui os seguintes campos de nível superior:
campo | Tipo | Descrição |
|---|---|---|
| String | Obrigatório. A versão da especificação YAML da view de métricas que a definição usa, como |
| String | Opcional. Descrição da view de métricas. |
| String | Obrigatório. Os dados de origem para a view de métricas. Pode ser qualquer ativo do Unity Catalog semelhante a uma tabela, incluindo uma view de métricas ou uma query SQL. Consulte Origem. |
| matriz | Opcional. Valores nomeados que os chamadores passam quando consultam a query da view de métricas como uma função com valor de tabela. Consulte Parâmetros. |
| String | Opcional. Uma expressão booleana SQL que se aplica a todas as queries. Consulte Filtro. |
| matriz | Opcional. Junções de esquemas em estrela e em floco de neve. See join. |
| matriz | Condicional. Definições de campo, incluindo nome, expressão e metadados semânticos opcionais. Obrigatório se nenhum |
| matriz | Condicional. Definições de medida, incluindo nome, expressão de agregação e metadados semânticos opcionais. Obrigatório se nenhum |
| Objeto | Opcional. Configuração para acelerar queries com views materializadas. Inclui cronograma de refresh e definições de view materializada. Consulte Materialização. |
Origem
O campo source especifica a fonte de dados para a view de métricas. As fontes compatíveis incluem tabelas, views, views de métricas e queries SQL. A componibilidade se aplica a todas as views de métricas. Ao usar uma view de métricas como fonte, você pode referenciar seus campos e medidas na nova view de métricas. Consulte Componibilidade.
Fonte de ativo semelhante a tabela
Referencie um ativo semelhante a uma tabela usando seu nome de três partes:
source: catalog.schema.source_table
Fonte da query SQL
Para usar uma query SQL, escreva o texto da query diretamente no YAML:
source: SELECT * FROM samples.tpch.orders o
LEFT JOIN samples.tpch.customer c
ON o.o_custkey = c.c_custkey
Ao usar uma query SQL como fonte com uma cláusula JOIN, defina restrições de key primária e key estrangeira nas tabelas subjacentes e use a opção RELY para obter o desempenho ideal da query. Para mais informações, consulte Declarar key primária, key estrangeira e restrições de exclusividade e Otimização de query usando key primária e restrições de exclusividade.
Parâmetros
O bloco parameters define valores nomeados que os chamadores passam ao consultarem a view de métricas como uma função com valor de tabela. Para saber quando e como usar parâmetros, incluindo como consultar uma view de métricas parametrizada, consulte Usar parâmetros com views de métricas.
Cada definição de parâmetro inclui os seguintes campos:
campo | Tipo | Descrição |
|---|---|---|
| String | Obrigatório. O nome do parâmetro. Referencie o parâmetro por este nome em expressões de campo e de medida, e passe-o como um argumento nomeado ao query a view de métricas. |
| String | Obrigatório. O tipo de dados SQL do parâmetro, como |
| Varia | Opcional. O valor usado quando um chamador não passa o parâmetro. O default deve ser conversível para |
O exemplo a seguir define um parâmetro discount e o referencia 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 aplica-se a todas as queries que referenciam a view de métricas. Escrever filtros como expressões Boolean de 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'
join
As uniões em views de métricas suportam tanto uniões diretas de uma tabela de fatos a tabelas de dimensão (esquema em estrela) quanto uniões multi-salto entre tabelas de dimensão normalizadas (esquemas em floco de neve). Você também pode join a uma query SQL usando uma instrução SELECT. Consulte Usar uma query SQL como origem.
Tabelas unidas não podem incluir colunas do tipo MAP. Para descompactar valores de colunas do tipo MAP, consulte Explodir elementos aninhados de um mapa ou array.
Cada definição de join inclui os seguintes campos:
campo | Tipo | Descrição |
|---|---|---|
| String | Obrigatório. Apelido para a tabela unida ou query SQL. Use este apelido ao referenciar colunas da tabela unida em campos ou medidas. |
| String | Obrigatório. Nome de três partes da tabela para join. Também pode ser uma query SQL. |
| String | Condicional. Expressão Boolean que define a condição de join. Obrigatório se |
| matriz | Condicional. Lista de nomes de colunas presentes na tabela pai e na tabela unida. Obrigatório se |
| String | Opcional. default é |
| matriz | Opcional. Uma lista de definições de join aninhadas para modelagem de esquema snowflake. Consulte a disponibilidade do recurso de view de métricas para os requisitos mínimos de Runtime. |
| Mapa | Opcional. Promessas sobre o join em que o analisador pode confiar para produzir planos de query mais eficientes. Consulte Otimizar joins com |
Star schema join
Em um esquema em estrela, o source é a tabela de fatos e faz join com uma ou mais tabelas de dimensões usando um LEFT OUTER JOIN. Views de métricas join as tabelas de fatos e de dimensões necessárias para a query específica, com base nas colunas selecionadas.
Especifique as colunas de join usando uma cláusula ON ou uma cláusula USING:
ONcláusula: Usa uma expressão Boolean para definir a condição de join.USINGCláusula: Lista colunas com o mesmo nome na tabela pai e na tabela unida.
A join deve 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)
O namespace source faz referência a colunas da fonte da view de métricas, enquanto o name de um join se refere a colunas da tabela unida. Por exemplo, em source.l_orderkey = orders.o_orderkey, source se refere a lineitem e orders se refere à tabela unida. Se nenhum prefixo for fornecido em uma cláusula on, a referência será default para a tabela unida.
Joins de esquema Snowflake
Um esquema Snowflake estende um esquema em estrela ao normalizar tabelas de dimensão e conectá-las a subdimensões. Isso cria uma estrutura join multinível. Consulte a disponibilidade do recurso de view de métricas para os requisitos mínimos de Runtime.
Para definir um esquema em floco de neve, aninhe joins dentro de uma definição de join 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 campo cardinality define o relacionamento entre a fonte e uma tabela unida. O default, many_to_one, trata a tabela unida como uma pesquisa de dimensão. Defina cardinality: one_to_many para tratar a tabela unida como uma fonte de fatos que o mecanismo agrega independentemente no nível da fonte, o que permite que uma única linha de origem corresponda a várias linhas na tabela unida. Os joins de um para muitos exigem o Databricks Runtime 18.1 ou acima e a versão 1.1 da especificação YAML. Consulte disponibilidade do recurso de view de métricas.
As seguintes regras se aplicam a joins um-para-muitos:
- Uma coluna um-para-muitos não pode ser usada em uma definição de
fields, 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 origem. Você pode aplicar operações aritméticas nos resultados de agregações separadas, como
count(orders.order_id) / count(*). - Todos os descendentes de uma join de um para muitos também devem ser
one_to_many. Junções irmãs de nível superior podem misturar cardinalidades. - Faça referência a uma coluna em um join aninhado com seu caminho de ponto completo através dos nomes do join, como
orders.order_items.item_id.
O exemplo a seguir une orders a uma fonte customers com cardinality: one_to_many para que as medidas de ordem agreguem sem duplicar as 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ã, consulte Cardinalidade da junção.
Otimizar joins com rely
Use o campo rely em um join para declarar garantias sobre o relacionamento que o analisador de query usa ao planejar queries. Essas garantias permitem que o mecanismo planeje queries de forma mais eficiente e reduza os dados escaneados, especialmente quando os campos da tabela combinada são referenciados em filtros.
O mapa rely suporta os seguintes campos:
campo | Tipo | Descrição |
|---|---|---|
| Booleana | Opcional. O default é |
Defina at_most_one_match: true somente quando a join for muitos-para-um. Essa relação não é validada em Runtime. Se várias linhas na tabela de junção corresponderem a uma única linha de origem, as medidas (como SUM e COUNT) retornarão resultados incorretos.
O exemplo a seguir habilita at_most_one_match em um join de muitos para um de orders para customer. Queries que filtram ou agrupam por atributos do cliente são as mais beneficiadas:
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
fields e dimensions são palavras-chave equivalentes em uma definição de view de métrica. fields é o termo preferido e é usado em toda esta documentação. O editor low-code do Catalog Explorer rotula essas colunas como **Fields**, mas o YAML que ele gera usa a dimensions palavra-chave. Views de métricas existentes que usam dimensions continuam a funcionar, e ambas as palavras-chave são aceitas em definições novas ou atualizadas.
Os campos são colunas da view de métricas usadas nas cláusulas SELECT, WHERE e GROUP BY no momento da query. Cada expressão deve retornar um valor escalar. Campos podem referenciar colunas dos dados de origem ou campos definidos anteriormente na view de métricas.
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 no momento da query usando funções SQL, como
SUMouAVG.
Cada definição de campo inclui as seguintes propriedades:
Propriedade | Tipo | Descrição |
|---|---|---|
| String | Necessário para expressões de coluna explícitas. O alias de coluna para o campo. Omita-o para expressões curinga, onde o Databricks deriva nomes da origem. Consulte Campos e medidas de importação em massa com curingas. |
| String | Obrigatório. Uma expressão SQL que pode referenciar colunas dos dados de origem ou um campo definido anteriormente. Pode ser um curinga para importar todas as colunas da origem ou de uma tabela unida. Consulte Campos e medidas de importação em massa com curingas. |
| String | Opcional. Descrição do campo. Aparece no Unity Catalog e nas ferramentas de documentação. |
| String | Opcional. Rótulo que aparece em ferramentas de visualização. Limitado a 255 caracteres. Exige a especificação YAML 1,1. Consulte disponibilidade do recurso de view de métricas. |
| Mapa | Opcional. Especificação de formato de como os valores são exibidos. Requer especificação YAML 1.1. Consulte Especificações de formato. |
| matriz | Opcional. Nomes alternativos para ferramentas de AI e BI para descobrir o campo. Até 10 sinônimos, cada um limitado a 255 caracteres. Exige a especificação YAML 1,1. Consulte Sinônimos. |
Os campos da view de métricas semelhantes a strings são sempre STRING, mesmo quando a coluna de origem é CHAR ou VARCHAR. Como o preenchimento de espaço CHAR(n) é perdido, as comparações podem retornar resultados diferentes. Por exemplo, column = 'COLLEGE' corresponde a um valor CHAR(10) na tabela de origem (que é preenchida com espaços), mas não no campo da view de métricas.
Exemplo:
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. Elas devem ser expressas usando funções de agregação. Para referenciar uma medida em uma query, use a função MEASURE. 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:
campo | Tipo | Descrição |
|---|---|---|
| String | Obrigatório para expressões de medida explícitas. O alias para a medida. Omita-o para expressões curinga, onde o Databricks deriva nomes da origem. Consulte Campos e medidas de importação em massa com curingas. |
| String | Obrigatório. Uma expressão SQL que contém uma ou mais funções de agregação. Pode ser um curinga para importar todas as medidas de uma origem de view de métricas. Consulte Campos e medidas de importação em massa com curingas. |
| String | Opcional. Descrição da medida. Aparece no Unity Catalog e nas ferramentas de documentação. |
| String | Opcional. Rótulo que aparece em ferramentas de visualização. Limitado a 255 caracteres. Exige a especificação YAML 1,1. Consulte disponibilidade do recurso de view de métricas. |
| Mapa | Opcional. Especificação de formato de como os valores são exibidos. Requer especificação YAML 1.1. Consulte Especificações de formato. |
| matriz | Opcional. Nomes alternativos para ferramentas de AI e BI para descobrir a medida. Até 10 sinônimos, cada um limitado a 255 caracteres. Requer a especificação YAML 1.1. Consulte disponibilidade do recurso de view de métricas. |
| matriz | Opcional. Especificações de janela para agregações de janela, cumulativas ou semiaditivas. Quando não especificada, a medida se comporta como uma agregação padrão. Consulte Medidas de janela. |
Consulte Funções de agregação para 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']
Importar campos e medidas em massa com curingas
Aplica-se a: Databricks Runtime 18.2 e acima com a especificação YAML 1.1
Em uma definição de fields ou measures, você pode usar um caractere curinga (*) no campo expr para importar todas as colunas da origem ou de uma tabela combinada sem listar cada uma. Isso é útil quando você deseja que uma view de métricas exponha todas as colunas de um ativo de origem, semelhante a SELECT * em uma view padrão. O Databricks expande o caractere curinga para colunas concretas ao criar ou substituir a view de métricas, 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 a view de métricas é criada. Para incluir colunas adicionadas à fonte posteriormente, recrie a view de métricas com CREATE OR REPLACE ou ALTER.
Caracteres curinga suportam as seguintes formas:
Sintaxe | Descrição |
|---|---|
| Importar todas as colunas da fonte da view de métricas. |
| Importar todas as colunas de uma tabela join, referenciadas pelo nome de join. As junções aninhadas usam o caminho de pontos completo, como |
| Importe todas as colunas do destino, exceto as listadas. |
| Expanda os campos de uma coluna |
As seguintes regras se aplicam a expressões curinga:
- Omitir o campo
name. Databricks deriva nomes de colunas da origem, portanto,namenã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_name,formatousynonymsem um curinga. Para adicionar metadados a uma coluna específica, exclua-a do curinga comEXCEPTe defina-a explicitamente. - Em uma definição de
measures, um curinga importa medidas apenas de uma fonte de view de métricas. Tabelas base não têm medidas, então um curinga é expandido para nenhuma medida quando a fonte é uma tabela base. - Não é possível referenciar uma coluna importada com curinga pelo seu nome derivado em uma expressão
fieldsoumeasuresposterior. Referencie a coluna de origem com seu caminho completo em vez disso.
Resolver colisões de nomes
Ao importar colunas de mais de uma origem com um curinga, as 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 curinga com EXCEPT, depois defina-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 de curinga
A seguinte definição 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'
Medidas de janela
Experimental
Este recurso é Experimental.
O campo window define agregações em janela, cumulativas ou semiaditivas para 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:
campo | Tipo | Descrição |
|---|---|---|
| String | Obrigatório. O campo que determina a ordenação da janela. (1) |
| String | Obrigatório. A extensão da janela. Consulte valores |
| String | Obrigatório. Método de agregação. Valores aceitos: |
| String | Opcional. Requer Databricks Runtime 18.1 e a versão 1.1 ou acima da especificação YAML. Desloca o quadro da janela para trás ou para a frente ao longo do campo |
(1) O campo referenciado deve ser determinístico. Expressões não determinísticas, como rand(), uuid() ou current_timestamp(), produzem ordenação de janela imprevisível e podem levar a resultados de agregação incorretos.
Valores range suportados.
current: Linhas onde o valor de ordenação da janela é igual ao valor da linha de ancoragem.cumulative: Todas as linhas em que o valor de ordenação da janela é menor ou igual ao valor da linha âncora.trailing <value> <unit> [inclusive | exclusive]: Linhas da linha âncora retrocedendo pelas unidades de tempo especificadas, por exemplo,trailing 7 day. O modificador opcionalinclusiveouexclusiverequer o Databricks Runtime 18.1 e a versão 1.1 ou superior da especificação YAML, e controla se a linha âncora é incluída na janela. O default éexclusive. Consulte Incluir ou excluir a linha âncora.leading <value> <unit> [inclusive | exclusive]: Linhas da linha âncora avançando pelas unidades de tempo especificadas, por exemploleading 3 month. O modificador opcionalinclusiveouexclusiverequer o Databricks Runtime 18.1 e a versão 1.1 ou superior da especificação YAML, e controla se a linha âncora é incluída na janela. O default éexclusive. Consulte Incluir ou excluir a linha â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 contínua 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
Materialização
Pré-lançamento público
Este recurso está em Pré-visualização Pública.
O campo materialization configura a aceleração automática de query usando views materializadas. Para informação detalhada sobre como a materialização funciona, requisitos e práticas recomendadas, veja Materialização para view de métricas.
Não é possível materializar uma view de métricas que defina parâmetros.
O campo materialization inclui os seguintes campos de nível superior:
campo | Tipo | Descrição |
|---|---|---|
| String | Opcional. Programação de Refresh. Usa a mesma sintaxe da cláusula de programar em views materializadas. Se omitido, as materializações são atualizadas apenas manualmente. A cláusula |
| String | Obrigatório. Deve ser definido como |
| matriz | Obrigatório. Lista de visualizações materializadas a materializar. Cada entrada requer os campos descritos abaixo. |
Cada entrada em materialized_views inclui os seguintes campos:
campo | Tipo | Descrição |
|---|---|---|
| String | Obrigatório. O nome da materialização. |
| String | Obrigatório. Tipo de materialização. Valores suportados: |
| matriz | Condicional. Lista de nomes de campo para materializar. Obrigatório se |
| matriz | Condicional. Lista de nomes de medida a serem materializados. Obrigatório se |
| Objeto | Opcional. Colunas de clusterização para a materialização, equivalente à cláusula em uma materialized |
| matriz | Opcional. Lista de colunas para particionar a materialização, equivalente à |
O bloco de materialização usa a palavra-chave dimensions: em vez de fields:. Use dimensions: ao listar campos para materializar, mesmo que sua definição de nível superior use fields:.
Exemplo de materialização
O exemplo a seguir define uma visualização de métrica com várias materializações:
version: 1.1
source: samples.tpch.orders
fields:
- 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
cluster_by:
cols:
- order_date
- order_status
partition_by:
- order_date
Referências de nome de coluna
Ao fazer referência a nomes de coluna que contêm espaços ou caracteres especiais em expressões YAML, coloque o nome da coluna entre backticks. Se a expressão começar com um backtick e for usada diretamente como um valor YAML, envolva a expressão inteira em aspas duplas. Valores YAML válidos não podem começar com um backtick.
Exemplos de formatação
Utilize os exemplos a seguir para aprender a formatar 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 em torno do nome da coluna.
Nome da coluna com espaços
Coluna de origem: `First Name`
expr: '`First Name`'
Use acentos graves para escapar espaços. Delimite a expressão inteira com aspas duplas.
Nomes de colunas 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 acento grave, as aspas duplas não são necessárias.
Nome da coluna contendo aspas
Coluna de origem: "name"
expr: '`"name"`'
Use acentos graves para escapar das 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"
YAML interpreta dois-pontos sem aspas como separadores de chave-valor. Sempre use aspas duplas em expressões que incluem dois-pontos.
Expressões de várias linhas
expr: |
CASE WHEN
revenue > 100 THEN 'High'
ELSE 'Low'
END
Use o escalar de bloco | depois de expr: para expressões de várias linhas. Todas as linhas devem ter um recuo de pelo menos dois espaços além da chave expr para análise correta.
Atualizar para YAML 1.1
Atualizar uma view de métricas para a versão 1.1 da especificação YAML exige atenção, 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ários do Unity Catalog : Comentários armazenados no Unity Catalog para a view de métricas ou suas colunas. Estes 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 os comentários na sua view de métricas.
Opção 1: Preservar comentários YAML usando notebooks ou o editor SQL
Se sua view de métricas contiver comentários YAML (#) que você deseja manter, use os seguintes passos:
- Use o comando
ALTER VIEWem um notebook ou editor SQL. - Copie a definição YAML original para a seção
$$..$$apósAS. Altere o valor deversionpara1.1. - Salve a view da 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)
$$
A execução de ALTER VIEW remove os comentários do Unity Catalog, a menos que eles sejam explicitamente incluídos nos campos comment da definição YAML. Para preservar os comentários mostrados no Unity Catalog, consulte Opção 2.
Opção 2: Preservar comentários do Unity Catalog
A orientação a seguir aplica-se 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 IU do editor YAML, a IU do editor YAML preservará automaticamente seus comentários do Unity Catalog.
- Copie todos os comentários do Unity Catalog nos campos
commentapropriados na sua definição YAML. Altere o valor deversionpara1.1. - Salve a view da 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 Runtime para cada recurso, consulte Disponibilidade de recursos da view de métricas.