O que são parâmetros do painel?

Os parâmetros de painel são uma forma de tornar os painéis interativos, permitindo que os visualizadores usem seletores de valor único e seletores de data para inserir valores específicos em consultas de conjunto de dados em runtime. Por exemplo, os parâmetros podem filtrar dados com base em critérios como datas e categorias de produto antes de serem agregados em uma consulta SQL, permitindo uma consulta mais eficiente e análise precisa.

Os parâmetros são adicionados a conjuntos de dados e conectados a um ou mais widgets na tela de um painel por um autor ou editor do painel. Os visualizadores do painel interagem com os dados do painel selecionando valores em widgets de filtro no runtime. Isso executa novamente as consultas associadas e apresenta visualizações criadas nos dados filtrados.

Os parâmetros modificam diretamente a consulta, que pode ser eficaz. Os filtros 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. Confira Filtros.

Adicionar um parâmetro a uma consulta

Você deve 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 em 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.
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

Você pode definir um valor padrão para o parâmetro digitando-o no campo de texto sob o nome do parâmetro. Execute a consulta para visualizar os resultados da consulta com o valor do parâmetro aplicado. Executar a consulta também salva o valor padrão. Quando você define este parâmetro usando um widget de filtro na tela, o valor padrão é usado.

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.

Observação

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 do 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 são usados em nenhuma outra visualização no painel.

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 quando o conjunto de dados é atualizado. Uma consulta SQL de exemplo é a seguinte:

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

Criar uma lista de parâmetros estáticos

É possível criar um conjunto de dados estático que inclui apenas valores que você codifica em seu conjunto de dados. Uma consulta de exemplo é a seguinte:

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

Tipos de filtro

Os filtros Valor Único e Seletor de Data dão suporte a parâmetros de configuração. Ao definir parâmetros baseados em consulta com um filtro do Seletor de Datas, as datas que aparecem nos resultados da consulta subjacente são mostradas em preto. As datas que não aparecem nos resultados da consulta são cinzas. Os usuários podem escolher datas cinzas mesmo que não estejam incluídos na consulta subjacente.

Remover um parâmetro de consulta

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

Mostrar parâmetros no painel

Adicionar um filtro à tela do painel permite que os visualizadores selecionem e modifiquem valores de parâmetro, para que possam explorar e analisar os dados interativamente. Se você não expuser 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.

Incluir parâmetros na URL

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

Exemplos de sintaxe de parâmetro

Os exemplos a seguir demonstram alguns casos de uso comuns para parâmetros.

Inserir uma data

O exemplo a seguir inclui um parâmetro de data que limita os resultados da consulta a registros após uma data específica.

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  sum(o_totalprice) AS `Total Price`
FROM
  samples.tpch.orders
WHERE
  o_orderdate > :date_param
GROUP BY
  1,
  2

Inserir um número

O exemplo a seguir inclui um parâmetro Numérico que limita os resultados aos registros em que o campo o_total_price é maior que o valor do parâmetro fornecido.

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  o_totalprice AS Price
FROM
  samples.tpch.orders
WHERE
  o_totalprice > :num_param

Inserir um nome de campo

No exemplo a seguir, field_param é usado com a função IDENTIFIER para fornecer um valor de limite para a consulta em runtime. O valor do parâmetro deve ser um nome de coluna da tabela usada na consulta.

SELECT
  *
FROM
  samples.tpch.orders
WHERE
  IDENTIFIER(:field_param) < 10000

Inserir objetos de banco de dados

O exemplo a seguir cria três parâmetros: catalog, schema e table. Os visualizadores de painel podem usar widgets de filtro na tela para selecionar valores de parâmetro.

SELECT
  *
FROM
  IDENTIFIER(:catalog || '.' || :schema || '.' || :table)

Confira a cláusula IDENTIFIER.

Importante

Permitir que os visualizadores de painel acessem dados por meio de seleções de parâmetro, como nomes de tabela ou catálogo, 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 inserir credenciais no painel publicado.

Concatenar vários parâmetros

Você pode incluir parâmetros em outras funções SQL. Este exemplo permite que o visualizador selecione um título de funcionário e uma ID de número. A consulta usa a função format_string para concatenar as duas cadeias de caracteres e filtrar as linhas que correspondem. Consulte a Função format_string.

SELECT
  o_orderkey,
  o_clerk
FROM
  samples.tpch.orders
WHERE
  o_clerk LIKE format_string('%s%s', :title, :emp_number)

Parâmetros de painel versus Parâmetros de consulta SQL do Databricks

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 SQL do Databricks.