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. Usado para unir LEFT a tabela de fatos definida em source com tabelas de dimensões como um modelo de esquema em estrela.
• 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.

Notação geral

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.

Ao referenciar nomes de colunas com espaços ou caracteres especiais em expressões em uma definição YAML, considere o seguinte:

• Escape de acentos: inclua o nome da coluna em acentos invertidos (`) para garantir a referência adequada. Por exemplo, para referenciar uma coluna com um espaço no nome, use column name.

• Escapamento de backtick cercado por aspas duplas: se a expressão começar com um nome de coluna com escapamento de backtick e precisar fazer parte de uma cadeia de caracteres em YAML, coloque toda a expressão entre aspas duplas para que seja compatível com YAML. Por exemplo, ao usar um nome de coluna com espaços, toda a expressão pode ter a aparência de "`column name`".

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

são usadas para modelar esquemas em estrela, onde a fonte é tratada como uma tabela de fatos e pode ser unida a várias tabelas de dimensões usando um LEFT OUTER JOIN. O senhor pode especificar as colunas join usando uma cláusula on ou using. A cláusula on permite que o senhor defina a condição join com uma expressão booleana. A cláusula using faz referência a colunas com os mesmos nomes nas duas tabelas.

O site join deve seguir uma relação de muitos para um. O exemplo a seguir mostra como expressar um join na definição de uma métrica view.

source: catalog.schema.fact_table

joins:

  # The on clause supports a boolean expression
  - name: dimension_table_1
    source: catalog.schema.dimension_table_1
    on: source.dimension_table_1_fk = dimension_table_1.pk

  # The using clause supports an array of columns
  # found in both of the tables being joined.
  - name: dimension_table_2
    source: catalog.schema.dimension_table_2
    using:
      - dimension_table_2_key_a
      - dimension_table_2_key_b

dimensions:

  # Dimension referencing a join column from dimension_table_1 using dot notation
  - name: Dimension table 1 key
    expr: dimension_table_1.pk

measures:

  # Measure referencing a join column from dimension_table_1
  - name: Count of dimension table 1 keys
    expr: COUNT(dimension_table_1.pk)

nota

O espaço de nome source faz referência a colunas da fonte métricas view, enquanto o join name faz referência a colunas da tabela unida. Por exemplo, na condição join source.dimension_table_1_fk = dimension_table_1.pk, source refere-se à tabela de origem das métricas view(fact_table) e dimension_table_1 refere-se à tabela unida. A referência padrão para a tabela join se nenhum prefixo for fornecido em uma cláusula on.

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

Beta

Esse recurso está na versão beta.

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)