Trabalhar com parâmetros do painel de controle

Esta página explica como usar parâmetros em painéis de AI/BI . Se preferir aprender sobre filtros de campo, consulte Filtrar por campos.

Os parâmetros AI/BI dashboard permitem substituir valores diferentes em consultas dataset em tempo de execução. Isso permite filtrar dados por critérios como datas e categorias de produtos antes que os dados sejam agregados em uma consulta SQL , resultando 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 do painel 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 os parâmetros usados nos 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.

Escolha entre filtros de campo e parâmetros.

Os parâmetros modificam diretamente a consulta, o que pode ser muito útil. Os filtros de campos de conjuntos de dados também podem oferecer interatividade no painel, mais recursos e melhor desempenho com grandes conjuntos de dados do que os parâmetros. Para obter mais informações, consulte Devo filtrar por um campo ou por um parâmetro?

Adicionar um parâmetro a uma consulta

Você precisa ter pelo menos permissões CAN EDIT no painel de rascunho para adicionar um parâmetro a um dataset do painel. Você pode adicionar parâmetros diretamente às consultas dataset na tab Dados .

Para adicionar um parâmetro a uma consulta:

1. Posicione o cursor onde deseja inserir o parâmetro na sua consulta.

2. Clique em Adicionar parâmetro 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. Você também pode adicionar parâmetros digitando essa sintaxe no editor de consultas.

Editar um parâmetro de consulta

Para editar um parâmetro:

1. Clique ao lado do nome do parâmetro. Uma caixa de diálogo com os detalhes dos parâmetros é 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. Por default, o título é o mesmo que a palavra-chave.

   • Tipo : Os tipos suportados incluem strings , data , data e hora e numérico .

     • O tipo default é strings .
     • O tipo de dados Numérico permite especificar entre Decimal e Inteiro . O tipo numérico default é Decimal .

   • Permitir múltiplas seleções : Selecione a caixa de seleção para permitir que os usuários escolham vários parâmetros em tempo de execução.

nota

Essa seleção pode exigir uma alteração adicional em sua consulta. Consulte Permitir múltiplas seleções.

2. Clique em outra parte da interface do usuário para fechar a caixa de diálogo.

Defina um valor default para o parâmetro.

Para testar sua consulta, digite um valor default no campo de texto abaixo do nome do parâmetro e execute a consulta. Isso aplica o valor do parâmetro para que você possa visualizar os resultados e confirmar se a execução da consulta ocorreu conforme o esperado. Executar a consulta também salva o valor default .

Ao usar o parâmetro em um widget de filtro, o valor default da tab Dados será utilizado, a menos que o widget especifique um default diferente. Consulte Usar filtros do painel.

Os autores do painel de controle devem confirmar se as consultas parametrizadas foram executadas com sucesso, utilizando os valores default selecionados na tab dataset . Databricks consulta o esquema dataset para preencher o editor de configuração do widget. Em alguns casos, particularmente com consultas parametrizadas que usam a cláusula IDENTIFIER , a consulta dataset pode falhar na execução com os valores de parâmetro default , mesmo que seja bem-sucedida quando um usuário seleciona um valor em tempo de execução.

Permitir múltiplas seleções

Consultas que permitem múltiplas seleções devem incluir uma função ARRAY_CONTAINS na consulta.

O exemplo a seguir mostra uma consulta SQL que permite selecionar vários valores para inserir na consulta em tempo de execução. A cláusula WHERE usa a função ARRAY_CONTAINS com uma verificação NULL adicional. O parâmetro deve ser configurado para armazenar múltiplos valores, de forma que possa ser inserido na consulta como uma matriz.

Quando a consulta for executada:

• Se valores específicos forem selecionados, cada linha será avaliada e todas as linhas onde l_quantity corresponder a pelo menos um valor em :parameter serão incluídas no conjunto de resultados.
• Se "Todos" for selecionado, o parâmetro será NULL e todas as linhas serão retornadas (nenhum filtro será aplicado).

SQL

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

Para definir valores default :

1. Escreva uma consulta dataset que use a função ARRAY_CONTAINS para filtrar linhas com base em uma lista de valores.

2. Clique o ícone de engrenagem ao lado do nome do parâmetro. Selecione " Permitir múltiplas seleções" .

nota

Este passo permite que o parâmetro seja inserido na consulta como uma matriz. Se a função ARRAY_CONTAINS for usada sem habilitar seleções múltiplas, ocorrerá um erro.

3. Digite um valor no campo de texto abaixo do nome de exibição. Você pode inserir mais de um valor. Selecione o valor atual antes de inserir o próximo.

Aplicar parâmetros de intervalo de datas

Você pode usar parâmetros para definir um intervalo e retornar apenas os resultados dentro desse intervalo. Ao escolher um dos seguintes tipos de parâmetros, você cria dois parâmetros que são 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. A condição OR :date_param IS NULL trata o caso em que um visualizador seleciona Todos , o que define o parâmetro para null e retorna todas as linhas.

SQL

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min AND :date_param.max
  OR :date_param IS NULL

Para criar um parâmetro de intervalo de datas:

1. Clique em Adicionar parâmetro .

2. 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 .

3. Selecione Intervalo de datas ou Intervalo de data e hora como Tipo .

4. 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 e inclua uma condição OR :parameter IS NULL para lidar com todas as seleções. Por exemplo:

   SQL

    WHERE date_col BETWEEN :date_param.min AND :date_param.max
      OR :date_param IS NULL

5. Insira valores de data default e execute a consulta para testá-la. Use o ícone do calendário para escolher opções predefinidas, como semana passada ou mês passado.

Parâmetros baseados em consulta

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 configurar parâmetros enquanto 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:

1. Crie um conjunto dataset cujo resultado seja limitado a uma lista de valores de parâmetros possíveis.
2. Crie uma consulta dataset que utilize um parâmetro.
3. Configure um widget de filtro na tela que filtre por um campo e utilize um parâmetro.
   • As configurações de campos devem ser definidas para usar o campo com a lista desejada de valores de parâmetros elegíveis.
   • A configuração de parâmetros deve ser definida para selecionar um valor de parâmetro.

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 uma visualização.

nota

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

Criar uma lista de parâmetros dinâmica

Para criar um dataset dinâmico que preencha a lista suspensa usada pelos visualizadores 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âmetro. Um exemplo de consulta SQL é o seguinte:

SQL

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

Criar uma lista de parâmetros estáticos

Você pode criar um dataset estático que inclua apenas os valores que você definir diretamente no seu dataset. Um exemplo de consulta é o seguinte:

SQL

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 da 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 widgets de visualização que compartilham o mesmo dataset. Isso permite que o mesmo dataset apresente diferentes visualizações na tela.

O exemplo nesta 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 de coleta como Weekday ou Weekend. O parâmetro de consulta filtra os resultados com base em se a coleta ocorreu em um dia útil ou em um 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.

SQL

  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:

1. Adicione um widget de visualização à tela do painel de controle em rascunho.

2. Com o novo widget selecionado, escolha o dataset parametrizado na lista suspensa de conjuntos de dados no painel de configuração.

3. Clique em Mostrar filtros . Para conjuntos de dados que incluem parâmetros, uma seção "Parâmetros" aparece no painel de configuração.

   

4. Clique no sinal de mais à direita do título "Parâmetros" e escolha um parâmetro na lista suspensa.

5. Por default, o valor do parâmetro reflete o que está definido na consulta na tab Dados . Você pode manter o valor atual ou escolher um novo para substituir no dataset. Saia do campo de texto para exibir a visualização com o novo parâmetro aplicado.

6. Analise seu painel de controle.

   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 percorridas em viagens com início em dias úteis, enquanto o gráfico à direita mostra os mesmos dados para fins de semana. Ambas as visualizações são baseadas no mesmo dataset.

   

Compare o uso de dados com uma condição de filtro

Você pode adicionar uma condição de filtro que permite comparar as agregações em uma 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 onde o valor do parâmetro especificado é All, que não aparece nos dados. A primeira parte da condição de filtro funciona da mesma forma que no exemplo anterior, filtrando resultados onde day_type é Weekday ou Weekend. A segunda parte da condição de filtro verifica se o próprio parâmetro está definido para um determinado valor, neste caso All, que não aparece nos dados. Ao definir o valor default para esse parâmetro no editor dataset , você está efetivamente ignorando o filtro quando nem Weekday nem Weekend são passados como valores.

SQL

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'

nota

Este exemplo usa um valor de strings personalizado ('All') para parâmetros de valor único onde "All" é definido como uma opção estática. Para parâmetros de seleção múltipla, use OR :parameter IS NULL em vez de para lidar com seleções "Todas". Consulte Permitir múltiplas seleções.

Você pode usar este dataset para configurar três widgets de visualização, com day_type_param definido como All, Weekday e Weekend respectivamente. Em seguida, os usuários que visualizam o painel podem comparar cada dataset filtrado por tipo de dia com o dataset completo.

O GIF a seguir mostra como você pode criar rapidamente três gráficos a partir do dataset criado com esta consulta.

1. O primeiro gráfico está configurado para mostrar o dataset Distâncias de Viagem por Tipo de Dia com um valor de parâmetro definido como Dia da Semana .
2. Clone o gráfico para manter todas as configurações aplicadas.
3. Para exibir dados de viagens realizadas no fim de semana, ajuste o parâmetro estático para "Fim de semana" .
4. Clone o novo gráfico para manter todas as configurações aplicadas anteriormente.
5. Defina o parâmetro no novo gráfico como "Todos" para exibir o número total de viagens por distância, tanto para viagens de fim de semana quanto para viagens durante a semana.

Exibir parâmetros no painel de controle

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

Para adicionar um parâmetro ao seu painel:

1. Clique Adicionar um filtro (campo/parâmetro) .
2. Clique Ao lado de Parâmetros no painel de configuração.
3. Clique no nome do parâmetro que você deseja que o visualizador use com este widget.

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

Os parâmetros são valores fixos que são 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 o painel for atualizado, os widgets de visualização exibirão um erro indicando qual parâmetro possui 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 pelo visualizador.

Você pode usar um padrão como o do exemplo a seguir para definir valores fallback para diferentes parâmetros na mesma consulta.

SQL

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 'Todos' tanto no widget de visualização quanto no editor dataset . O parâmetro :dash_param é um valor dinâmico que é controlado por um widget de filtro na tela do painel. Esta instrução verifica um valor fornecido como parâmetro estático. Caso nenhum valor seja definido, o sistema utilizará o valor de um parâmetro do painel de controle selecionado pelo usuário.

Inclua parâmetros na URL.

As configurações dos 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 a compartilhem com outras pessoas para aplicar os mesmos filtros e parâmetros de forma consistente.

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

Os parâmetros do painel de controle usam a mesma sintaxe que os marcadores de parâmetros nomeados. Consulte Marcadores de parâmetros nomeados. Os painéis de controle não suportam parâmetros no estilo Mustache.

Exemplos de sintaxe

Os parâmetros são usados comumente para inserir datas, números, texto, objetos de banco de dados e valores de strings JSON. Para exemplos que demonstram como usar parâmetros nesses casos, consulte Exemplos de sintaxe de parâmetros nomeados.

importante

Permitir que os visualizadores acessem 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 você estiver publicando um painel com essas opções, a Databricks recomenda não incorporar credenciais no painel publicado.