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

Os parâmetros permitem-te passar valores para uma vista métrica quando a consultas. Use parâmetros para reutilizar uma única definição de vista métrica em diferentes entradas, como uma taxa de desconto ou uma janela de data. Referenciar um parâmetro em qualquer lugar onde uma expressão SQL constante seja válida, como em filtros, expressões de campo e medida, a fonte e joins. Também pode referenciar um parâmetro inteiro como o valor de uma medida range de janela ou offset, para que um chamador passe o tamanho da janela no momento da consulta. Passe um valor como argumento ao consultar a vista.

Os parâmetros reduzem a duplicação. Em vez de manter uma vista métrica separada para cada variante, defines a lógica uma vez e deixas que cada chamador forneça os seus próprios valores. Um parâmetro pode incluir um valor por defeito, por isso os chamadores que não passam um argumento voltam ao valor por defeito.

Pode passar valores de parâmetros a partir de uma consulta SQL ou de um painel de IA/BI. Num painel, ligue um parâmetro a um widget de filtro para permitir que os espectadores escolham o valor em tempo de execução. Veja Usar uma consulta parametrizada num painel de controlo.

Requisitos

  • Para criar uma vista métrica que define parâmetros, é necessário ter 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 vista métrica, veja Criar uma vista métrica.
  • Para consultar uma visualização de métricas que define parâmetros, é necessário ter um SQL warehouse ou outro recurso de computação com o Databricks Runtime 18.2 ou superior em execução. Para mais requisitos de versão, consulte a disponibilidade da funcionalidade de visualização métrica.

Limitations

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

  • Não se pode materializar uma vista métrica que defina parâmetros.
  • Os valores padrão têm restrições. Um valor predefinido tem de ser convertível para o tipo de dados declarado do parâmetro e não pode fazer referência a outro parâmetro nem conter uma subconsulta. Se definires um padrão para um parâmetro, todos os parâmetros que o seguem também devem ter um padrão. Consulte Parâmetros.

Definir parâmetros

Pode definir parâmetros no editor low-code Catalog Explorer ou diretamente no YAML. Depois de criares um parâmetro, referencia-o pelo nome em qualquer lugar onde uma expressão SQL constante seja válida, como em filtros, expressões de campo e medida, a fonte e joins. Também pode referenciar um parâmetro inteiro como o valor de uma medida range de janela ou offset. Consulte Dimensões da janela.

Para definir parâmetros no YAML, adicione um bloco de topo parameters à definição da vista métrica. Para a referência completa do campo e um exemplo YAML, veja Parâmetros.

Os passos seguintes utilizam o editor de baixo código do Catalog Explorer e a tabela samples.tpch.orders, disponível em todos os espaços de trabalho, para criar uma vista 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 possas comparar os dois.

Passo 1: Criar uma vista métrica

Crie uma vista métrica para conter o parâmetro e as medidas.

  1. Clique no ícone de Dados.Cataloga na barra lateral do espaço de trabalho, depois usa a barra de pesquisa para encontrar samples.tpch.orders e clicar no nome da tabela.
  2. Clique em Criar>visualização de métrica.
  3. No diálogo Criar vista métrica , introduza um nome e depois selecione um catálogo e um esquema para criar a vista métrica. Clique em Criar.

O editor abre no separador UI . Para uma perspetiva completa do editor de vista métrica, veja Criar uma vista métrica.

Passo 2: Adicionar um parâmetro

Adiciona um discount parâmetro com um tipo numérico e um valor predefinido.

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

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

    1. Digite discount para o Nome.
    2. Escolha Numérico na lista pendente Tipo.
    3. Escolha Double na lista pendente tipo numérico que aparece.

    O botão Adicionar parâmetro e os detalhes do parâmetro dialogam com um parâmetro de desconto definido para o tipo Numérico e o tipo Duplo Numérico.

  3. Clique fora da caixa de diálogo para a fechar e, em seguida, insira 0.15 como valor predefinido para discount.

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

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

Passo 3: Adicionar uma medida que utilize o parâmetro

Referenciar o parâmetro pelo nome numa expressão de medida. Esta medida aplica o desconto ao total de cada encomenda.

  1. Clique no separador Medidas perto do topo do editor.

  2. Clique em + Adicionar.

  3. Introduza Discounted Sales como nome da Medida.

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

    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. Introduza Total Sales como nome da Medida.
  3. No Builder, selecione source.o_totalprice e a agregação Sum para produzir SUM(source.o_totalprice).

Passo 5: Guardar a vista métrica

Clique em Salvar. Para consultar a vista métrica e passar um valor para o discount parâmetro, veja Consultar uma vista métrica com parâmetros.

Consultar uma vista métrica com parâmetros

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

Passe os argumentos por nome

Para passar um argumento por nome, use o operador =>. O exemplo seguinte passa um valor de discount 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 pela ordem em que os parâmetros são definidos. O exemplo seguinte transmite o mesmo valor de discount de 0.15:

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

Usar valores de parâmetros por defeito

Para usar os valores padrão dos parâmetros ao chamar a vista métrica, omita os argumentos. As seguintes consultas são equivalentes e utilizam todos os valores por defeito:

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

Veja os parâmetros que uma vista métrica define

Para ver os parâmetros que uma vista métrica define, veja a sua definição YAML, que inclui o parameters bloco. Consulte Definição e metadados da vista de métricas.

Use uma consulta parametrizada num painel de controlo

Pode usar qualquer uma destas consultas para definir um conjunto de dados num painel de IA/BI. Referenciar a vista métrica num conjunto de dados SQL e passar o parâmetro como argumento na chamada de função com valores de tabela. Para permitir que os visualizadores do painel escolham o valor em tempo de execução, passe um parâmetro do painel no argumento e ligue-o a um widget de filtro. Veja Passar parâmetros para uma vista métrica.

Recursos adicionais

  • Last updated on