Usar parâmetros com visualizações métricas

Os parâmetros permitem que você passe valores para uma exibição de métrica ao consultá-la. Use parâmetros para reutilizar uma única definição de visualização de métrica em diferentes entradas, como uma taxa de desconto ou um intervalo de datas. Faça referência a um parâmetro em qualquer lugar em que uma expressão SQL constante seja válida, como em filtros, expressões de campo e medida, a origem e as junções. Você também pode referenciar um parâmetro inteiro como o valor de range ou offset de uma medida de janela, para que o chamador passe o tamanho da janela no momento da consulta. Passe um valor como argumento ao consultar a visualização.

Os parâmetros reduzem a duplicação. Em vez de manter uma exibição de métrica 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 padrão, para que os chamadores que não passam um argumento retornem ao padrão.

Você pode fornecer valores de parâmetros de uma consulta SQL ou de um painel de IA/BI. Em um painel, conecte um parâmetro a um widget de filtro para permitir que os visualizadores escolham o valor em runtime. Consulte Usar uma consulta parametrizada em um painel.

Requisitos

  • Para criar uma visualização de métrica que define parâmetros, você precisa dos privilégios CREATE TABLE e USE SCHEMA no esquema e do privilégio USE CATALOG no catálogo pai. Para obter a lista completa de privilégios necessários para criar uma exibição de métrica, consulte Criar uma exibição de métrica.
  • Para consultar uma exibição de métrica que define parâmetros, você precisa de um sql warehouse ou outro recurso de computação executando o Databricks Runtime 18.2 ou superior. Para obter mais requisitos de versão, consulte a disponibilidade do recurso de exibição de métrica.

Limitations

As seguintes limitações se aplicam a exibições de métrica que definem parâmetros:

  • Você não pode materializar uma exibição de métrica que define parâmetros.
  • Os valores padrão têm restrições. Um valor padrão deve ser castível para o tipo de dados declarado do parâmetro e não pode referenciar outro parâmetro ou conter uma subconsulta. Se você definir um padrão para um parâmetro, cada parâmetro que o segue também deverá ter um padrão. Consulte Parâmetros.

Definir parâmetros

Você pode definir parâmetros no editor de código baixo do Catalog Explorer ou diretamente no YAML. Depois de criar um parâmetro, faça referência a ele por nome em qualquer lugar em que uma expressão SQL constante seja válida, como em filtros, expressões de campo e medida, a origem e as junções. Você também pode referenciar um parâmetro inteiro como o valor de range ou offset de uma medida de janela. Veja as medidas da janela.

Para definir parâmetros no YAML, adicione um bloco de nível parameters superior à definição de exibição de métrica. Para obter a referência de campo completa e um exemplo de YAML, consulte Parâmetros.

As etapas a seguir usam o editor de código baixo do Catalog Explorer e a samples.tpch.orders tabela, disponíveis em cada workspace, para criar uma exibição de métrica com um discount parâmetro e duas medidas. Uma medida aplica o parâmetro e a outra calcula o total não contado para que você possa comparar os dois.

Etapa 1: Criar uma exibição de métrica

Crie uma exibição de métrica para manter o parâmetro e as medidas.

  1. Clique no ícone Dados.Cataloge na barra lateral do workspace e use a barra de pesquisa para localizar samples.tpch.orders e clicar no nome da tabela.
  2. Clique em Criar>Visão de métrica.
  3. Na caixa de diálogo Criar exibição de métrica, insira um nome e selecione um catálogo e um esquema nos quais a exibição de métrica será criada. Clique em Criar.

O editor é aberto na guia interface do usuário . Para obter um passo a passo completo do editor de exibição de métrica, consulte Criar uma exibição de métrica.

Etapa 2: Adicionar um parâmetro

Adicione um discount parâmetro com um tipo numérico e um valor padrão.

  1. No título 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 na lista suspensa Tipo.
    3. Escolha Duplo na lista suspensa tipo Numérico que é exibida.

    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 longe da caixa de diálogo para fechá-la e, em seguida, insira 0.15 como o valor padrão do desconto.

    O parâmetro de desconto com um valor padrão de 0,15.

O parâmetro aparece no título do editor depois de criá-lo. O valor definido aqui é o padrão que se aplica quando uma consulta omite o argumento.

Etapa 3: Adicionar uma medida que usa o parâmetro

Faça referência ao parâmetro por nome em uma expressão de medida. Essa medida aplica o desconto a cada total de pedidos.

  1. Clique na guia Medidas próxima à parte superior do editor.

  2. Clique em + Adicionar.

  3. Insira Discounted Sales como o nome da medida.

  4. Clique em Personalizar e, em seguida, insira a seguinte expressão:

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

Etapa 4: Adicionar outra medida

Adicione uma segunda medida para o total sem desconto.

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

Etapa 5: salve a visualização de métricas

Clique em Salvar. Para consultar a exibição de métrica e passar um valor para o discount parâmetro, consulte Consultar uma exibição de métrica com parâmetros.

Consultar uma visualização de métrica com parâmetros

Para consultar uma exibição de métrica que define parâmetros, chame a exibição de métrica como uma função com valor de tabela e passe parâmetros como argumentos. Você pode passar argumentos por nome ou por posição ou omiti-los para usar os valores padrão.

Passar argumentos por nome

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

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

Passar 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 discount valor de 0.15:

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

Usar valores de parâmetro padrão

Para usar os valores de parâmetro padrão ao chamar a exibição de métrica, omita argumentos. As consultas a seguir são equivalentes e usam todos os valores padrão:

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

Exibir os parâmetros que uma exibição de métrica define

Para ver os parâmetros que uma visualização de métrica define, exiba sua definição em YAML, que inclui o bloco parameters. Veja Definição e metadados da visualização de métrica.

Usar uma consulta parametrizada em um painel

Você pode usar qualquer uma dessas consultas para definir um conjunto de dados em um painel de IA/BI. Faça referência à exibição de métrica em um conjunto de dados SQL e passe o parâmetro como um argumento na chamada de função com valor de tabela. Para permitir que os visualizadores do painel escolham o valor em runtime, passe um parâmetro de painel para o argumento e conecte-o a um widget de filtro. Consulte Passar parâmetros para uma visualização de métrica.

Recursos adicionais

  • Last updated on