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 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:

  1. Posicione o cursor onde o senhor deseja colocar o parâmetro na consulta.

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

  1. Clique em ícone de engrenagem 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.

  2. 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. Veja os filtros.

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:

  1. Crie um dataset cujo conjunto de resultados seja limitado a uma lista de possíveis valores de parâmetros.

  2. Crie uma consulta dataset que use um parâmetro.

  3. 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 é automaticamente adicionado como uma seleção de parâmetro quando o site dataset é atualizado. 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)

Tipos de filtros

Os filtros Single Value e Date Picker suportam parâmetros de configuração. Ao definir parâmetros baseados em consultas com um filtro Date Picker, as datas que aparecem nos resultados da consulta subjacente são mostradas em preto. As datas que não aparecem nos resultados da consulta estão em cinza. Os usuários podem escolher datas cinzas, mesmo que elas não estejam incluídas na consulta subjacente.

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 em um fim de semana.

O texto da consulta é fornecido no bloco de código a seguir, mas as instruções desta seção limitam-se à configuração das visualizações associadas, configuradas com parâmetros de widget estáticos. 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:

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

  2. Com o novo widget selecionado, escolha o dataset parametrizado no menu suspenso do conjunto de dados no painel de configuração. Para consultas que incluem parâmetros, a seção Parâmetros aparece no painel de configuração.

    Um painel de configuração de visualização mostrando a opção de escolher um parâmetro.

  3. Clique no sinal de mais à direita do cabeçalho Parameters (Parâmetros ) e escolha um parâmetro no menu suspenso.

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

  5. 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 iniciadas em 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.

    Dois histogramas, configurados para usar parâmetros estáticos em nível de widget, conforme descrito.

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

Você pode adicionar uma condição de filtro que permite comparar agregações em 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 um dos conjuntos de dados filtrados por tipo de dia com o conjunto inteiro dataset.

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

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

  2. Clone o gráfico para manter todas as configurações aplicadas.

  3. Para mostrar 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 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 que possam 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:

  1. Clique em Ícone de filtro Add a filter (field/parameter) (Adicionar um filtro (campo/parâmetro)).

  2. Clique em adicionar ícone de campo ao lado de Parameters (Parâmetros ) no painel de configuração.

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

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

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 no URL, permitindo que os usuários o marquem como favorito para manter o estado do painel, incluindo filtros e parâmetros predefinidos, ou o compartilhem com outras pessoas para aplicação consistente dos mesmos filtros e parâmetros.

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.