métricas view Referência YAML

info

Visualização

Esse recurso está em Public Preview.

Esta página descreve cada componente do YAML usado para definir uma métrica view.

Visão geral do YAML

A definição YAML para uma métrica view inclui seis campos de nível superior:

• version: padrão para 0.1. Essa é a versão da especificação métricas view.
• source: Os dados de origem das métricas view. Isso pode ser um ativo semelhante a uma tabela ou uma consulta SQL.
• joins: Opcional. A junção de esquemas em estrela e em floco de neve é suportada.
• filter: Opcional. Uma expressão booleana SQL que se aplica a todas as consultas; equivalente à cláusula WHERE.
• dimensions: Uma matriz de definições de dimensão, incluindo o nome e a expressão da dimensão.
• measures: Uma matriz de colunas de expressão agregada.

Sintaxe e formatação YAML

métricas view definições seguem a sintaxe de notação YAML padrão. Consulte a documentação do yaml.org para saber mais sobre as especificações do YAML.

Referências ao nome da coluna

Ao fazer referência a nomes de colunas que contêm espaços ou caracteres especiais em expressões YAML, coloque o nome da coluna em acentos invertidos para escapar do espaço ou do caractere. Se a expressão começar com um acento grave e for utilizada 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 acento grave.

Exemplos de formatação

Use os exemplos a seguir para aprender a formatar o YAML corretamente em cenários comuns.

Faça referência ao nome de uma coluna

A tabela a seguir mostra como formatar nomes de colunas dependendo dos caracteres que elas contêm.

Caso	Nome (s) da coluna de origem	Expressão (s) de referência	Notas
Sem espaços	revenue	expr: "revenue" expr: 'revenue' expr: revenue	Use aspas duplas, aspas simples ou nenhuma aspa ao redor do nome da coluna.
Com espaços	First Name	expr: "`First Name`"	Use acentos nas costas para escapar dos espaços. Coloque a expressão inteira entre aspas duplas.
Nome da coluna com espaços em uma expressão SQL	First Name e Last Name	expr: CONCAT(`First Name`, , `Last Name`)	Se a expressão não começar com crase, não é necessário utilizar aspas duplas.
As cotações estão incluídas no nome da coluna de origem	"name"	expr: '`"name"`'	Use acentos invertidos para escapar das aspas duplas no nome da coluna. Coloque essa expressão entre aspas simples na definição YAML.

Use expressões com dois pontos

Caso	Expressão	Notas
Expressões com dois pontos	expr: "CASE WHENNível de cliente= 'Enterprise: Premium' THEN 1 ELSE 0 END"	Coloque a expressão inteira entre aspas duplas para uma interpretação correta

nota

O YAML interpreta dois pontos sem aspas como separadores de valor key. Sempre use aspas duplas em expressões que incluam dois pontos.

Indentação de várias linhas

Caso	Expressão	Notas
Indentação de várias linhas

nota

Use o escalar de bloco > após expr: para expressões de várias linhas. Todas as linhas devem ser recuadas pelo menos dois espaços além do expr key para uma análise correta.

Fonte

O senhor pode usar um ativo do tipo tabela ou uma consulta SQL como fonte para suas métricas view. Para usar um ativo do tipo tabela, o senhor deve ter pelo menos SELECT privilégios no ativo.

Use uma tabela como fonte

Para usar uma tabela como fonte, inclua o nome totalmente qualificado da tabela, como no exemplo a seguir.

source: samples.tpch.orders

Usar uma consulta SQL como fonte

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

nota

Ao usar uma consulta SQL como fonte com uma cláusula JOIN, o Databricks recomenda definir restrições primárias e estrangeiras key nas tabelas subjacentes e usar a opção RELY para otimizar o desempenho no momento da consulta, se aplicável. Para obter mais informações sobre o uso de restrições primárias e estrangeiras key, consulte Declare primary key and foreign key relationships e Query optimization using primary key constraints.

Use o site métricas view como fonte

O senhor também pode usar uma métrica existente view como fonte para uma nova métrica view:

version: 0.1
source: views.examples.source_metric_view

dimensions:

  # Dimension referencing dimension from source_metric_view
  - name: Order date
    expr: order_date_dim

measures:

  # Measure referencing dimension from source_metric_view
  - name: Latest order month
    expr: MAX(order_date_dim_month)

  # Measure referencing measure from source_metric_view
  - name: Latest order year
    expr: DATE_TRUNC('year', MEASURE(max_order_date_measure))

Ao usar uma métrica view como fonte:

• As dimensões nas novas métricas view podem fazer referência a qualquer dimensão nas métricas de origem view.

• As medidas nas novas métricas view podem fazer referência a qualquer dimensão ou medida nas métricas de origem view.

Todas as outras regras de composição se aplicam. Consulte Composabilidade.

Filtro

Um filtro na definição YAML de uma métrica view se aplica a todas as consultas que fazem referência a ela. Ela deve ser escrita como uma expressão booleana SQL e é equivalente ao uso de uma cláusula WHERE em uma consulta SQL.

unir-se

viewAs funções JOIN permitem definir relações entre uma fonte de métricas e outras fontes, como tabelas, visualizações ou outras visualizações de métricas. É possível utilizar a junção para modelar relações da tabela de fatos para tabelas de dimensões (esquema em estrela) e para percorrer dimensões e subdimensões, permitindo junções de múltiplos saltos entre tabelas de dimensões normalizadas (esquema em floco de neve). Se o usuário join para outra métricas view, apenas as dimensões estarão disponíveis na métricas view.

Snowflake A junção é suportada apenas ao utilizar Databricks Runtime compute 17.1 e versões superiores. Consulte Utilizar a junção na visualização de métricas.

Dimensões

As dimensões são usadas nas cláusulas SELECT, WHERE e GROUP BY no momento da consulta. Cada expressão deve retornar um valor escalar. Cada dimensão consiste em dois componentes:

• name: O alias da coluna.

• expr: Uma expressão SQL nos dados de origem que define a dimensão.

O exemplo a seguir demonstra como definir dimensões:

dimensions:

  # Column name
  - name: Order date
    expr: o_orderdate

  # SQL expression
  - name: Order month
    expr: DATE_TRUNC('MONTH', `Order date`)

  # Referring to a column with a space in the name
  - name: Month of order
    expr: `Order month`

  # Multi-line expression
  - name: Order status
    expr: CASE
            WHEN o_orderstatus = 'O' THEN 'Open'
            WHEN o_orderstatus = 'P' THEN 'Processing'
            WHEN o_orderstatus = 'F' THEN 'Fulfilled'
          END

Medidas

As medidas são uma matriz de expressões agregadas que definem resultados agregados sem um nível predeterminado de agregação. Elas devem ser expressas como funções agregadas. Para referenciar uma medida em uma consulta, você deve usar a função MEASURE. Cada medida consiste nos seguintes componentes:

• name: O alias da medida.

• expr: Uma expressão SQL agregada que pode incluir funções SQL agregadas.

Consulte Funções agregadas para obter uma lista de funções agregadas.

Veja a função agregadameasure.

O exemplo a seguir demonstra como definir medidas:

measures:

  # Basic aggregation
  - name: Total revenue
    expr: SUM(o_totalprice)

  # Basic aggregation with ratio
  - name: Total revenue per customer
    expr: SUM(`Total revenue`) / COUNT(DISTINCT o_custkey)

  # Measure-level filter
  - name: Total revenue for open orders
    expr: COUNT(o_totalprice) FILTER (WHERE o_orderstatus='O')

  # Measure-level filter with multiple aggregate functions
  # filter needs to be specified for each aggregate function in the expression
  - name: Total revenue per customer for open orders
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus='O')/COUNT(DISTINCT o_custkey) FILTER (WHERE o_orderstatus='O')

Medidas de janela

info

Experimental

Esse recurso é experimental.

As medidas de janela permitem que o senhor defina medidas com agregações de janela, cumulativas ou semiaditivas em sua visualização métricas. Esses tipos de medidas permitem cálculos mais complexos, como médias móveis, mudanças de período a período e totais correntes. Consulte Usar medidas de janela na visualização métricas para obter exemplos que demonstram como usar medidas de janela na visualização métricas.

Composibilidade

As visualizações métricas são compostas, o que permite que o senhor crie uma lógica complexa fazendo referência a elementos definidos anteriormente.

Em uma definição métrica view:

• As dimensões podem referenciar dimensões previamente definidas no YAML.
• As medidas podem referenciar todas as dimensões.
• As medidas podem referenciar medidas definidas anteriormente usando a função MEASURE().

O exemplo a seguir mostra como as dimensões e medidas podem ser compostas:

dimensions:

  # Dimension referencing a source column
  - name: Order month
    expr: DATE_TRUNC('month', o_orderdate)

  # Dimension referencing a previously defined dimension
  - name: Previous order month
    expr: ADD_MONTHS(`Order Month`, -1)

measures:

  # Measure referencing a dimension
  - name: Earliest order month
    expr: MIN(`Order month`)

  # Measure referencing a source column
  - name: Revenue
    expr: SUM(sales_amount)

  # Measure referencing a source column
  - name: Costs
    expr: SUM(item_cost)

  # Measure referencing previously defined measures
  - name: Profit
    expr: MEASURE(Revenue) - MEASURE(Costs)

Mapeamento do nome da coluna em CREATE VIEW com YAML

Ao criar uma métrica view utilizando CREATE VIEW com um column_list, o sistema mapeia as colunas definidas em YAML (medidas e dimensões) para o column_list por posição, e não por nome.

Isso segue o comportamento padrão do SQL, conforme mostrado no exemplo a seguir:

SQL

CREATE VIEW v (col1, col2) AS SELECT a, b FROM table;

Neste exemplo, a mapeia para col1 e b mapeia para col2, independentemente de seus nomes originais.