Trabalhar com parâmetros de painel

Esta página explica como usar parâmetros em painéis de IA/BI. Se você quiser saber mais sobre filtros de campo, consulte Filtrar em campos.

Os parâmetros do painel de controle de AI/BI permitem substituir valores diferentes em consultas de conjunto de dados no runtime. Isso permite que você filtre 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 dos conjuntos de dados.

Autores ou editores de painéis de controle adicionam parâmetros aos conjuntos de dados e os conectam a um ou mais widgets na tela do painel. Para parâmetros estáticos configurados 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 em widgets de filtro no runtime. Essa interação executa novamente as consultas associadas e exibe visualizações com base nos dados filtrados.

Escolher entre filtros de campo e parâmetros

Os parâmetros modificam diretamente a consulta, que pode ser eficaz. Os filtros do campo de conjunto de dados também podem oferecer interatividade do painel, mais recursos e melhor desempenho com conjuntos de dados maiores do que parâmetros. Para obter mais informações, consulte Devo filtrar em um campo ou um parâmetro?.

Adicionar um parâmetro a uma consulta

Você precisa ter pelo menos permissões PODE EDITAR no painel de rascunho para adicionar um parâmetro a um conjunto de dados de painel. Você pode adicionar parâmetros diretamente às consultas do conjunto de dados na guia Dados.

Para adicionar um parâmetro a uma consulta:

1. Coloque o cursor onde você deseja colocar o parâmetro em sua consulta.

2. Clique em Adicionar Parâmetro para inserir um novo parâmetro.

   Isso cria um novo parâmetro com o nome padrão parameter. Para alterar o nome padrão, 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 no Ao lado do nome do parâmetro. Uma 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 filtro. Por padrão, o título é o mesmo que a palavra-chave.

   • Tipo: os tipos com suporte incluem Cadeia de caracteres, Data, Data e Hora e Numérico.

     • O tipo padrão é Cadeia de caracteres.
     • O tipo de dados Numérico permite que você especifique entre Decimal e Inteiro. O tipo numérico padrão é Decimal.

   • Permitir várias seleções: marque a caixa de seleção para permitir que os usuários escolham vários parâmetros no tempo de execução.

     Observação

     Essa seleção pode exigir uma alteração adicional em sua consulta. Consulte Permitir várias seleções.

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 testar sua consulta, digite um valor padrão no campo de texto sob o 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 consulta é executada conforme o esperado. Executar a consulta também salva o valor padrão.

Quando você usa o parâmetro em um widget de filtro, o valor padrão da guia Dados é usado, a menos que o widget especifique um padrão diferente. Consulte Usar filtros.

Os autores do painel devem confirmar que as consultas parametrizadas são executadas com êxito com os valores padrão selecionados na guia conjunto de dados. O Azure Databricks consulta o esquema do conjunto de dados para preencher o editor de configuração do widget. Em alguns casos, particularmente com consultas parametrizadas que usam a IDENTIFIER cláusula, a consulta do conjunto de dados pode falhar ao ser executada com os valores de parâmetro padrão, mesmo que tenha êxito quando um usuário seleciona um valor em runtime.

Permitir várias seleções

As consultas que permitem várias seleções devem incluir uma ARRAY_CONTAINS função 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 WHERE cláusula usa a ARRAY_CONTAINS função. Essa função usa a palavra-chave do parâmetro e o nome da coluna como argumentos. O parâmetro deve ser definido para conter vários valores para que possa ser inserido na consulta como uma matriz. Quando a consulta é executada, cada linha é avaliada e todas as linhas l_quantity em :parameter que correspondem a pelo menos um valor são incluídas no conjunto de resultados.

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

Para definir valores padrão:

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

2. Clique no O ícone de engrenagem ao lado do nome do parâmetro. Selecione Permitir várias seleções.

   Observação

   Essa etapa permite que o parâmetro seja inserido na consulta como uma matriz. Se a função ARRAY_CONTAINS for usada sem habilitar várias seleções, ocorrerá um erro.

3. Digite um valor no campo de texto sob o 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 resultados dentro desse intervalo. Ao escolher um dos seguintes tipos de parâmetro, você cria dois parâmetros que são designados por .min e .max sufixos:

• Intervalo de datas
• 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 período:

1. Clique em Adicionar parâmetro.

2. Clique no Ao lado do nome do parâmetro. Insira a palavra-chave e o nome de exibição. Não inclua .min sufixos ou .max sufixos.

3. Escolha Intervalo de datas ou Intervalo de datas e horas como o tipo.

4. Insira uma WHERE cláusula que defina o intervalo em sua consulta. Para definir o intervalo, use uma BETWEEN cláusula com .min e .max valores. Por exemplo:

    WHERE date_col BETWEEN :date_param.min AND :date_param.max
   

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

Parâmetros baseados em consulta

Parâmetros baseados em consulta permitem que autores definam uma lista dinâmica ou estática de valores que os visualizadores podem escolher ao definir parâmetros enquanto exploram dados em um painel. Eles são definidos combinando 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 as seguintes etapas:

1. Cria um conjunto de dados cujo conjunto de resultados esteja limitado a uma lista de possíveis valores de parâmetro.
2. Cria uma consulta de conjunto de dados que usa um parâmetro.
3. Configura um widget de filtro na tela que filtra um campo e usa um parâmetro.
   • As configurações de Campos devem ser definidas para usar o campo com a lista desejada de valores de parâmetro qualificados.
   • A configuração Parâmetros deve ser definida para selecionar um valor de parâmetro.

Consulte Usar parâmetros baseados em consulta para 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 conjunto de dados dinâmico que preencha a lista suspensa que os visualizadores usam para selecionar valores de parâmetro, escreva uma consulta SQL que retorna um único campo e inclua todos os valores nesse campo. Qualquer novo valor nesse campo é adicionado automaticamente como uma seleção de parâmetro. Uma consulta SQL de exemplo é a seguinte:

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

Criar uma lista de parâmetros estáticos

Você pode criar um conjunto de dados estático que inclui apenas valores codificados em seu conjunto de dados. Uma consulta de exemplo é a 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 da consulta.

Parâmetros de widget estáticos

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

O exemplo nesta seção é baseado em um conjunto de dados que consulta a samples.nyctaxi.trips tabela. 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 no fato de a coleta ter ocorrido em um dia da semana ou no fim de semana.

O texto da consulta é fornecido no bloco de código a seguir, mas as instruções nesta seção são limitadas à configuração das visualizações associadas configuradas com parâmetros de widget estáticos. Para obter instruções sobre como configurar um conjunto de dados 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 conjunto de dados parametrizado no menu suspenso Conjunto 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 é exibida no painel de configuração.

   

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

5. Por padrão, o valor do parâmetro reflete o que está definido na consulta na guia Dados. Você pode mantê-lo ou escolher um novo valor para substituir no conjunto de dados. Navegue para fora do campo de texto para mostrar a visualização com o novo parâmetro aplicado.

6. Revise seu dashboard.

   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 das viagens para viagens que começam nos dias úteis, enquanto o gráfico à direita mostra os mesmos dados para os fins de semana. Ambas as visualizações são baseadas no mesmo conjunto de dados.

   

Comparar dados usando uma condição de filtro

Você pode adicionar uma condição de filtro que permite comparar 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 em que 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 os resultados em que 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, nesse caso All, que não aparece nos dados. Quando você define o valor padrão para esse parâmetro no editor do conjunto de dados, 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'

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

O GIF a seguir mostra como você pode criar rapidamente três gráficos usando o conjunto de dados desenvolvido com essa consulta.

1. O primeiro gráfico é configurado para mostrar o conjunto de dados Distâncias de Viagem por Tipo de Dia com um valor de parâmetro definido como Dia útil.
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.
5. Defina o parâmetro no novo gráfico para Todos para mostrar a contagem total de viagens por distância para viagens de fim de semana e dias úteis.

Mostrar parâmetros no painel

Adicionar um filtro à tela do painel permite que os visualizadores selecionem e modifiquem valores de parâmetro para explorar e analisar os dados de forma interativa. Se você não expor o parâmetro no painel, os visualizadores verão apenas os resultados da consulta que usam o valor de parâmetro padrão definido na consulta.

Para adicionar um parâmetro ao seu painel:

1. Clique em Adicionar um filtro (campo/parâmetro)
2. Clique em ao lado de Parâmetros no painel de configuração.
3. Clique no nome do parâmetro para o visualizador usar com esse widget.

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

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 o 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 espectador.

Você pode usar um padrão como o do exemplo a seguir para definir valores de fallback para parâmetros diferentes 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 "Todos" no widget de visualização e no editor do conjunto de dados. O parâmetro :dash_param é um valor dinâmico controlado por um widget de filtro na tela do painel. Essa instrução verifica se há um valor fornecido como um parâmetro estático. Se nenhum for definido, ele retornará a um valor de parâmetro de painel selecionado pelo espectador.

Incluir parâmetros na URL

As configurações de parâmetro são armazenadas na URL, permitindo que os usuários o marquem para manter o estado do painel, incluindo filtros e parâmetros pré-definidos, ou compartilhá-lo com outras pessoas para aplicar os mesmos filtros e parâmetros consistentemente.

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

Os parâmetros de painel usam a mesma sintaxe que os marcadores de parâmetro nomeados. Consulte Marcadores de parâmetros nomeados. Os painéis não dão suporte a parâmetros de 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 cadeias de caracteres JSON. Para obter exemplos que demonstram como usar parâmetros nesses casos, consulte Exemplos de sintaxe de parâmetro nomeado.