Partilhar via

Trabalhar com parâmetros do painel

  • Artigo

Este artigo 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 AI/BI permitem substituir valores diferentes em consultas de conjunto de dados 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, levando a consultas mais eficientes e análises precisas. Os parâmetros podem ser usados com widgets de filtro para tornar os painéis interativos ou com widgets de visualização para tornar os conjuntos de dados mais fáceis de reutilizar.

Os autores ou editores do painel adicionam parâmetros aos conjuntos 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 em 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, que pode ser poderosa. 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 parâmetros. Consulte Usar filtros.

Adicionar um parâmetro a uma consulta

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

O Gif mostra um exemplo das etapas a seguir.

Para adicionar um parâmetro a uma consulta:

  1. Coloque o cursor onde pretende colocar o parâmetro na consulta.

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

    Isso cria um novo parâmetro com o nome parameterpadrão . 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 ao Ícone de engrenagem 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 para exibição: o nome no editor de filtro. Por padrão, o título é o mesmo que a palavra-chave.

    • Tipo: Os tipos suportados incluem String, Data, Data e Hora, Numérico.

      • O tipo padrão é String.
      • O tipo de dados numérico permite especificar 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 em tempo de execução.

      Nota

      Esta seleção pode exigir uma alteração adicional à 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 que a consulta seja executada, escolha um valor padrão para o parâmetro digitando-o no campo de texto abaixo do nome do parâmetro. Execute 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 padrão. Quando você define esse parâmetro usando um widget de filtro na tela, o valor padrão é usado, a menos que um novo valor padrão 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 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 parameter e o nome da coluna como argumentos. Quando a consulta é executada, ela retorna todas as linhas que contêm os valores de parâmetro selecionados.

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

Para definir valores padrão, digite-os no campo de texto abaixo do nome para 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 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 intervalo de datas:

  1. Clique em Adicionar parâmetro.

  2. Clique ao Ícone de engrenagem lado do nome do parâmetro. Insira a palavra-chave e o nome para exibição. Não inclua .min nem .max sufixos.

  3. Escolha Intervalo de datas ou Intervalo de data e hora como o tipo.

  4. Insira uma WHERE cláusula que defina o intervalo na 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 os valores de data padrão e execute a consulta para testá-la. Use o ícone de calendário para escolher opções predefinidas, como a semana passada ou o 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 definir parâmetros à medida que exploram 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 as seguintes etapas:

  1. Crie um conjunto de dados cujo conjunto de resultados seja limitado a uma lista de possíveis valores de parâmetros.
  2. Crie uma consulta de conjunto de dados 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 Campos devem ser definidas para usar o campo com a lista desejada de valores de parâmetros elegíveis.
    • A configuração Parâmetros deve ser definida para selecionar um valor de parâmetro.

Nota

Se um conjunto de dados usado em parâmetros baseados em consulta 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 conjunto de dados 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 e uma visualização baseados em consulta.

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 inclui todos os valores nesse 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

Você pode criar um conjunto de dados estático que inclua apenas valores codificados em seu conjunto de dados. 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 da 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 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 ou Weekday 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 estão limitadas à configuração das visualizações associadas configuradas com parâmetros estáticos do widget. 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 na lista suspensa 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 aparece no painel de configuração.

    Um painel de configuração de visualização mostrando a opção de escolher um paramter.

  4. Clique no sinal de adição à direita do título Parâmetros e escolha um parâmetro na lista suspensa.

  5. Por padrão, o valor do parâmetro espelha 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. Reveja o 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 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 conjunto de dados.

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

Comparar dados usando uma condição de filtro

Você pode adicionar uma condição de filtro que permite comparar agregações na 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 o day_type é ou Weekday Weekend. A segunda parte da condição do filtro verifica se o próprio parâmetro está definido para um determinado valor, neste caso All, que não aparece nos dados. Quando você define o valor padrão para esse parâmetro no editor de conjunto de dados, você está efetivamente ignorando o filtro quando nem Weekday 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 day_type_param conjunto 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 a partir do conjunto de dados criado com essa consulta.

  1. O primeiro gráfico está configurado para mostrar o conjunto de dados 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 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 Todos para mostrar o total de contagens de viagens por distância para viagens de fim de semana e dias úteis.

Um gif como descrito no texto anterior.

Mostrar parâmetros no painel

Adicionar um filtro à tela do painel permite que os visualizadores selecionem e modifiquem valores de parâmetros 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 Ícone de filtro Adicionar um filtro (campo/parâmetro).
  2. Clique ícone adicionar campo 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 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 visualizador.

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 de conjunto de dados. O parâmetro :dash_param é um valor dinâmico controlado por um widget de filtro na tela do painel. Esta instrução verifica um valor fornecido como um parâmetro estático. Se nenhum estiver definido, ele retornará a um valor de parâmetro do painel selecionado pelo visualizador.

Incluir parâmetros no URL

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

Parâmetros do painel vs. parâmetros de consulta Mustache

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

Exemplos de sintaxe

Os usos comuns para 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â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, o Azure Databricks recomenda não incorporar credenciais no painel publicado.