Pular para o conteúdo principal
Última atualização em

Use parâmetros com view de métricas

Os parâmetros permitem passar valores para uma view de métricas ao query-la. Use parâmetros para reutilizar uma única definição de métrica view em diferentes entradas, como uma taxa de desconto ou um período de datas. Referencie um parâmetro onde uma expressão SQL constante for válida, como em filtros, expressões de campo e de medida, a fonte e junções. Passe um valor como um argumento ao consultar a visualização.

Parâmetros reduzem a duplicação. Em vez de manter uma view de métricas separada para cada variante, você define a lógica uma vez e permite que cada chamador forneça seus próprios valores. Um parâmetro pode incluir um valor default, de modo que os chamadores que não passam um argumento recorrem ao default.

É possível passar valores de parâmetros de uma query SQL ou de um AI/BI dashboard. Em um dashboard, conecte um parâmetro a um widget de filtro para permitir que os visualizadores escolham o valor no Runtime. Consulte Usar uma query parametrizada em um dashboard.

Requisitos​

  • Para criar uma view de métricas que define parâmetros, são necessários os privilégios CREATE TABLE e USE SCHEMA no esquema e o privilégio USE CATALOG no catálogo pai. Para a lista completa de privilégios necessários para criar uma view de métricas, consulte Criar uma view de métricas.
  • Para consultar uma view de métricas que define parâmetros, você precisa de um SQL warehouse ou outro recurso de compute executando o Databricks Runtime 18.2 ou acima. Para mais requisitos de versão, consulte Disponibilidade do recurso de view de métricas.

Limitações​

As seguintes limitações se aplicam às views de métricas que definem parâmetros:

  • Não é possível materializar uma view de métricas que defina parâmetros.
  • Os valores default têm restrições. Um valor default deve ser compatível com o tipo de dados declarado do parâmetro e não pode referenciar outro parâmetro ou conter uma subquery. Se o senhor definir um default para um parâmetro, todo parâmetro que o seguir também deve ter um default. Consulte Parâmetros.

Definir parâmetros​

Você pode definir parâmetros no editor de baixo código do Catalog Explorer ou diretamente em YAML. Depois de criar um parâmetro, referencie-o pelo nome em qualquer lugar onde uma expressão SQL constante seja válida, como em filtros, expressões de campo e medida, na fonte e em joins.

Para definir parâmetros em YAML, adicione um bloco parameters de nível superior à definição da view de métricas. Para a referência completa de campos e um exemplo de YAML, consulte Parâmetros.

Os passos a seguir usam o editor de low-code do Catalog Explorer e a tabela samples.tpch.orders, disponível em todo Workspace, para criar uma view de métricas com um parâmetro discount e duas medidas. Uma medida aplica o parâmetro, e a outra calcula o total não descontado para que você possa comparar os dois.

o passo 1: Crie uma view de métricas​

Crie uma view de métricas para conter o parâmetro e as medidas.

  1. Clique em Ícone de dados. Catálogo na barra lateral do Workspace, em seguida, use a barra de pesquisa para encontrar samples.tpch.orders e clique no nome da tabela.
  2. Clique em Criar > View de métricas .
  3. Na caixa de diálogo Criar view de métricas , insira um nome e selecione um catálogo e um esquema para criar a view de métricas. Clique em Criar .

O editor abre na tab **UI**. Para um passo a passo completo do editor de view de métricas, consulte Criar uma view de métricas.

Passo 2: Adicionar um parâmetro​

Adicione um parâmetro discount com um tipo numérico e um valor default.

  1. No cabeçalho do editor, clique em Adicionar parâmetro .

  2. Na caixa de diálogo **Detalhes do parâmetro**:

    1. Insira discount para o Nome .
    2. Escolha **Numérico** no menu suspenso **Tipo**.
    3. Escolha **Duplo** no menu suspenso **Tipo numérico** que aparece.

    O botão Adicionar parâmetro e a caixa de diálogo Detalhes do parâmetro com um parâmetro de desconto definido como tipo Numérico e tipo Numérico Duplo.

  3. Clique fora da caixa de diálogo para fechá-la, em seguida, insira 0.15 como o valor default para **desconto**.

    O parâmetro de desconto com um valor default de 0,15.

O parâmetro aparece no cabeçalho do editor depois que o senhor o cria. O valor definido aqui é o default que se aplica quando uma query omite o argumento.

O passo 3: Adicione uma métrica que usa o parâmetro.​

Referencie o parâmetro pelo nome em uma expressão de métrica. Esta medida aplica o desconto ao total de cada pedido.

  1. Clique na tab Métricas perto do topo do editor.

  2. Clique em + Adicionar .

  3. Discounted Sales Insira como o **Nome da medida**.

  4. Clique em Personalizado e insira a seguinte expressão:

    SQL
    SUM((1 - discount) * source.o_totalprice)

Passo 4: Adicionar outra medida​

Adicione uma segunda medida para o total não descontado.

  1. Clique em + Adicionar .
  2. Total Sales Insira como o **Nome da medida**.
  3. Em **Construtor**, selecione source.o_totalprice e a agregação **Soma** para SUM(source.o_totalprice) produzir.

Etapa 5: Salvar a view de métricas​

Clique em Salvar . Para fazer query da view de métricas e passar um valor para o parâmetro discount, consulte Faça query de uma view de métricas com parâmetros.

Query uma view de métricas com parâmetros​

Para fazer uma query em uma view de métricas que define parâmetros, chame a view de métricas como uma função com valor de tabela e passe os parâmetros como argumentos. É possível passar argumentos por nome ou por posição, ou omiti-los para usar os valores default.

Passar argumentos por nome​

Para passar um argumento por nome, use o operador =>. O exemplo a seguir passa um valor discount de 0.15:

SQL
SELECT product, MEASURE(discountedSales)
FROM catalog.schema.metric_view(discount => 0.15)
GROUP BY product;

Passe argumentos por posição​

Para passar argumentos por posição, liste os valores na ordem em que os parâmetros são definidos. O exemplo a seguir passa o mesmo valor discount de 0.15:

SQL
SELECT product, MEASURE(discountedSales)
FROM catalog.schema.metric_view(0.15)
GROUP BY product;

Usar valores de parâmetro default​

Para usar os valores de parâmetro default ao chamar a view de métricas, omita os argumentos. As seguintes queries são equivalentes e usam todos os valores default:

SQL
SELECT product, MEASURE(discountedSales) FROM catalog.schema.metric_view() GROUP BY product;
SELECT product, MEASURE(discountedSales) FROM catalog.schema.metric_view GROUP BY product;

Exiba os parâmetros que uma view de métricas define​

Para ver os parâmetros que uma view de métricas define, visualize sua definição YAML, que inclui o bloco parameters. Consulte Ver definição e metadados da view de métricas.

Use uma query parametrizada em um dashboard​

Você pode usar qualquer uma dessas queries para definir um dataset em um AI/BI dashboard. Referencie a view de métricas em um dataset SQL e passe o parâmetro como um argumento na chamada de função com valor de tabela. Para permitir que os visualizadores do dashboard escolham o valor em tempo de Runtime, passe um parâmetro do dashboard para o argumento e conecte-o a um widget de filtro. Consulte Passe parâmetros para uma view de métricas.

Mais recursos​

Nesta página