Trabalhe com parâmetros do painel

Este artigo explica como usar parâmetros nos painéis do site AI/BI. Se, em vez disso, quiser saber mais sobre filtros de campo, consulte Filtrar por campos.

AI/BI Os parâmetros do painel permitem que o senhor substitua valores diferentes nas consultas do site dataset em tempo de execução. Isso permite que o senhor filtre os dados por critérios como datas e categorias de produtos antes que os dados sejam agregados em uma consulta no site SQL, o que resulta em consultas mais eficientes e análises mais precisas. Os parâmetros podem ser usados com widgets de filtro para tornar os painéis interativos ou com widgets de visualização para facilitar a reutilização do conjunto de dados.

Os autores ou editores de painéis adicionam parâmetros ao conjunto de dados e os conectam a um ou mais widgets na tela do painel. Para parâmetros estáticos definidos em widgets de visualização, os valores são definidos pelos autores ou editores. Para parâmetros usados em widgets de filtro, os visualizadores do painel podem interagir com os dados selecionando valores nos widgets de filtro em tempo de execução. Essa interação executa novamente as consultas associadas e exibe visualizações com base nos dados filtrados.

Os parâmetros modificam diretamente a consulta, o que pode ser poderoso. Os filtros de campo do conjunto de dados também podem oferecer interatividade do painel, mais recursos e melhor desempenho com grandes conjuntos de dados do que os parâmetros. Consulte Usar filtros.

Adicionar um parâmetro a uma consulta

O senhor deve ter pelo menos CAN EDIT permissões no painel de rascunho para adicionar um parâmetro a um painel dataset. O senhor pode adicionar parâmetros diretamente às consultas do site dataset nos dados tab.

O gif mostra um exemplo dos seguintes passos.

Para adicionar um parâmetro a uma consulta:

Posicione o cursor onde o senhor deseja colocar o parâmetro na consulta.
Clique em Add parameter para inserir um novo parâmetro.

Isso cria um novo parâmetro com o nome default parameter. Para alterar o nome default, substitua-o no editor de consultas. O senhor também pode adicionar parâmetros digitando essa sintaxe no editor de consultas.

Editar um parâmetro de consulta

Para editar um parâmetro:

Clique em ao lado do nome do parâmetro. A caixa de diálogo Detalhes do parâmetro é exibida e inclui as seguintes opções de configuração:
- Palavra-chave: a palavra-chave que representa o parâmetro na consulta. Isso só pode ser alterado atualizando diretamente o texto na consulta.
- Nome de exibição: O nome no editor de filtros. Em default, o título é o mesmo que a palavra-chave.
- Type (Tipo): Os tipos compatíveis incluem cadeias de caracteres, data, data e hora, numérico.
  - O tipo de default é strings.
  - O tipo de dado Numeric permite que o senhor especifique entre Decimal e Integer. O tipo numérico do site default é Decimal.
- Permitir várias seleções: marque a caixa de seleção para permitir que os usuários escolham vários parâmetros em tempo de execução.
  
  Observação
  
  Essa seleção pode exigir uma alteração adicional em sua consulta. Consulte Permitir várias seleções.
Clique em outra parte da interface do usuário para fechar a caixa de diálogo.

Definir um valor de parâmetro padrão

Para sua consulta de execução, escolha um valor default para seu parâmetro, digitando-o no campo de texto abaixo do nome do parâmetro. executar a consulta para visualizar os resultados da consulta com o valor do parâmetro aplicado. A execução da consulta também salva o valor default. Quando o senhor define esse parâmetro usando um widget de filtro na tela, o valor default é usado, a menos que um novo valor default seja especificado no widget de filtro. Consulte Usar filtros.

Permitir várias seleções

As consultas que permitem várias seleções devem incluir uma função ARRAY_CONTAINS na consulta.

O exemplo a seguir mostra uma consulta SQL que permite que o senhor selecione vários valores para inserir na consulta em tempo de execução. A cláusula WHERE usa a função ARRAY_CONTAINS. Essa função usa a palavra-chave do parâmetro e o nome da coluna como argumentos. Quando a consulta é executada, ela retorna todas as linhas que contêm os valores dos parâmetros selecionados.

SELECT
  *
FROM
  samples.tpch.lineitem
WHERE array_contains(:parameter, l_quantity)

Para definir os valores de default, digite-os no campo de texto abaixo do nome de exibição. Selecione o valor atual antes de inserir o próximo.

os valores padrão são definidos no editor. Vários valores são selecionados e separados por um espaço.

Aplicar parâmetros de intervalo de datas

Você pode usar parâmetros para definir um intervalo e retornar somente resultados dentro desse intervalo. Ao escolher um dos seguintes tipos de parâmetros, você cria dois parâmetros designados pelos sufixos .min e .max:

Intervalo de dados
Intervalo de data e hora

O exemplo a seguir mostra uma consulta SQL que cria um parâmetro de intervalo de datas chamado date_param.

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min and :date_param.max

Para criar um parâmetro de intervalo de datas:

Clique em Adicionar parâmetro.
Clique ao lado do nome do parâmetro. Insira a palavra-chave e o nome de exibição. Não inclua os sufixos .min ou .max.
Escolha Intervalo de datas ou Intervalo de data e hora como o Tipo.
Insira uma cláusula WHERE que defina o intervalo em sua consulta. Para definir o intervalo, use uma cláusula BETWEEN com valores .min e .max. Por exemplo:
```
 WHERE date_col BETWEEN :date_param.min AND :date_param.max
```
Digite default valores de data e execute a consulta para testá-la. Use o ícone do calendário para escolher opções predefinidas, como na semana passada ou no mês passado.

Parâmetros baseados em consultas

Os parâmetros baseados em consulta permitem que os autores definam uma lista dinâmica ou estática de valores que os visualizadores podem escolher ao definir parâmetros à medida que exploram os dados em um painel. Eles são definidos pela combinação de um filtro de campo e um filtro de parâmetro em um único widget de filtro.

Para criar um parâmetro baseado em consulta, o autor do painel executa os seguintes passos:

Crie um dataset cujo conjunto de resultados seja limitado a uma lista de possíveis valores de parâmetros.
Crie uma consulta dataset que use um parâmetro.
Configure um widget de filtro na tela que filtra em um campo e usa um parâmetro.
- As configurações de Fields devem ser definidas para usar o campo com a lista desejada de valores de parâmetros elegíveis.
- A configuração Parameters deve ser definida para selecionar um valor de parâmetro.

Observação

Se um dataset usado em parâmetros baseados em consultas também for usado em outras visualizações em um painel, a seleção de filtro de um visualizador modificará todas as consultas conectadas. Para evitar isso, os autores devem criar um site dataset dedicado para parâmetros baseados em consulta que não seja usado em nenhuma outra visualização no painel.

Consulte Usar parâmetros baseados em consulta para obter um tutorial passo a passo que demonstra como adicionar um parâmetro baseado em consulta e visualização.

Criar uma lista de parâmetros dinâmicos

Para criar um dataset dinâmico que preencha o menu suspenso que os visualizadores usam para selecionar os valores dos parâmetros, escreva uma consulta SQL que retorne um único campo e inclua todos os valores desse campo. Qualquer novo valor nesse campo é adicionado automaticamente como uma seleção de parâmetros. Um exemplo de consulta SQL é o seguinte:

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

Criar uma lista de parâmetros estáticos

O senhor pode criar um dataset estático que inclua apenas os valores que o senhor codificou em seu dataset. Um exemplo de consulta é o seguinte:

SELECT
  *
FROM
  (
    VALUES
      ('MACHINERY'),
      ('BUILDING'),
      ('FURNITURE'),
      ('HOUSEHOLD'),
      ('AUTOMOBILE')
  ) AS data(available_choices)

Remover um parâmetro de consulta

Para remover um parâmetro, exclua-o de sua consulta.

Parâmetros estáticos do widget

Os parâmetros estáticos do widget são configurados diretamente em um widget de visualização, permitindo que os autores parametrizem individualmente os widgets de visualização que compartilham o mesmo dataset. Isso permite que o mesmo dataset apresente diferentes visualizações na tela.

O exemplo desta seção é baseado em um dataset que consulta a tabela samples.nyctaxi.trips. A consulta fornecida retorna a distância de cada viagem e categoriza o dia da coleta como Weekday ou Weekend. O parâmetro de consulta filtra os resultados com base no fato de a coleta ter ocorrido em um dia da semana ou fim de semana.

O texto da consulta é fornecido no bloco de código a seguir, mas as instruções nesta seção se limitam à configuração das visualizações associadas configuradas com parâmetros estáticos do widget. Para obter instruções sobre como configurar um dataset com parâmetros, consulte Adicionar um parâmetro a uma consulta.

  WITH DayType AS (
    SELECT
      CASE
        WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
        ELSE 'Weekday'
      END AS day_type,
      trip_distance
    FROM samples.nyctaxi.trips
  )
  SELECT day_type, trip_distance
  FROM DayType
  WHERE day_type = :day_type_param

Para adicionar um parâmetro de widget estático a uma visualização:

Adicione um widget de visualização à tela do painel de rascunho.
Com o novo widget selecionado, escolha o dataset parametrizado no menu suspenso do conjunto de dados no painel de configuração.
Clique em Mostrar filtros. Para conjuntos de dados que incluem parâmetros, uma seção Parâmetros é exibida no painel de configuração.
Clique no sinal de mais à direita do cabeçalho Parameters (Parâmetros ) e escolha um parâmetro no menu suspenso.
Em default, o valor do parâmetro reflete o que está definido na consulta nos dados tab. O senhor pode mantê-lo ou escolher um novo valor para substituir no site dataset. Navegue para fora do campo de texto para mostrar a visualização com o novo parâmetro aplicado.
Revise seu painel.

A imagem a seguir mostra dois widgets de visualização. Cada um é configurado como um histograma com um parâmetro de widget estático. O gráfico à esquerda mostra a distribuição das distâncias de viagem para viagens que começam nos dias de semana, enquanto o gráfico à direita mostra os mesmos dados para fins de semana. Ambas as visualizações são baseadas no mesmo site dataset.

Comparar o uso de dados com a condição de filtro

Você pode adicionar uma condição de filtro que permite comparar as agregações da parte dos dados com as agregações aplicadas a todo o conjunto de dados.

O exemplo a seguir estende a consulta anterior para incluir uma condição de filtro em que o valor do parâmetro especificado é All, que não aparece nos dados. A primeira parte da condição do filtro funciona da mesma forma que no exemplo anterior, filtrando os resultados em que day_type é Weekday ou Weekend. A segunda parte da condição do filtro verifica se o parâmetro em si está definido com um determinado valor, neste caso All, que não aparece nos dados. Quando o senhor define o valor default para esse parâmetro no editor dataset, está efetivamente ignorando o filtro quando nem Weekday nem Weekend são passados como valores.

WITH DayType AS (
  SELECT
    CASE
      WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
      ELSE 'Weekday'
    END AS day_type,
    trip_distance
  FROM
    samples.nyctaxi.trips
)
SELECT
  day_type,
  trip_distance
FROM
  DayType
WHERE
  day_type = :day_type_param
  OR :day_type_param = 'All'

O senhor pode usar esse dataset para configurar três widgets de visualização, com day_type_param definido como All, Weekday e Weekend, respectivamente. Em seguida, os visualizadores do painel podem comparar cada dataset filtrado por tipo de dia com o dataset inteiro.

O GIF a seguir mostra como o senhor pode criar rapidamente três gráficos a partir do site dataset criado com essa consulta.

O primeiro gráfico está configurado para mostrar as distâncias de viagem por tipo de dia dataset com um valor de parâmetro definido como dia da semana.
Clone o gráfico para manter todas as configurações aplicadas.
Para mostrar dados de viagens realizadas no fim de semana, ajuste o parâmetro estático para Fim de semana.
Clone o novo gráfico para manter todas as configurações aplicadas anteriormente.
Defina o parâmetro no novo gráfico como Tudo para mostrar a contagem total de viagens por distância para viagens de fim de semana e dias úteis.

Um gif conforme descrito no texto anterior.

Mostrar parâmetros no painel

Adicionar um filtro à tela do painel permite que os visualizadores selecionem e modifiquem os valores dos parâmetros para explorar e analisar os dados de forma interativa. Se o parâmetro não for exposto no painel, os visualizadores verão apenas os resultados da consulta que usam o valor do parâmetro default que o senhor definiu na consulta.

Para adicionar um parâmetro ao seu painel:

Clique em Add a filter (field/parameter) (Adicionar um filtro (campo/parâmetro)).
Clique em ao lado de Parameters (Parâmetros ) no painel de configuração.
Clique no nome do parâmetro que o usuário deseja que o visualizador use com esse widget.

Trabalhando com widgets de filtro e parâmetros estáticos

Os parâmetros são valores fixos substituídos em uma consulta em tempo de execução. Se duas ou mais referências ao mesmo parâmetro forem definidas com valores diferentes quando seu painel for atualizado, os widgets de visualização exibirão um erro indicando qual parâmetro tem valores conflitantes. Isso pode ocorrer quando vários widgets de filtro usam o mesmo parâmetro ou quando um parâmetro estático entra em conflito com um widget de filtro que permite a seleção do visualizador.

O senhor poderia usar um padrão como o do exemplo a seguir para definir valores de fallback para diferentes parâmetros na mesma consulta.

CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END

Neste exemplo, :static_param refere-se a um parâmetro estático, que deve ser definido como "All" no widget de visualização e no editor dataset. O parâmetro :dash_param é um valor dinâmico controlado por um widget de filtro na tela do painel. Essa instrução verifica um valor fornecido como um parâmetro estático. Se nenhum for definido, ele retornará a um valor de parâmetro do painel selecionado pelo espectador.

Incluir parâmetros no URL

As configurações de parâmetros são armazenadas na URL, permitindo que os usuários a adicionem aos favoritos para manter o estado do painel, incluindo filtros e parâmetros predefinidos, ou compartilhá-la com outras pessoas para aplicar os mesmos filtros e parâmetros de forma consistente.

Parâmetros do painel versus parâmetros de consulta do Mustache

Os parâmetros do painel usam a mesma sintaxe dos marcadores de parâmetros nomeados. Consulte Marcadores de parâmetros nomeados. Os painéis não oferecem suporte aos parâmetros do estilo Mustache.

Exemplos de sintaxe

Os usos comuns de parâmetros incluem a inserção de datas, números, texto, objetos de banco de dados e valores de JSON strings. Para exemplos que demonstram como usar parâmetros nesses casos, consulte Exemplos de sintaxe de parâmetros nomeados

Importante

Permitir que os visualizadores acessem os dados por meio de seleções de parâmetros, como nomes de tabelas ou catálogos, pode levar à exposição acidental de informações confidenciais. Se o senhor estiver publicando um painel com essas opções, a Databricks recomenda não incorporar credenciais no painel publicado.