O que são parâmetros do painel?

Os parâmetros do painel são uma maneira 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 tempo de execução. Por exemplo, os parâmetros podem filtrar dados com base em critérios como datas e categorias de produtos antes de serem agregados em uma consulta SQL, permitindo consultas mais eficientes e análises precisas.

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 de painel. Os visualizadores do painel interagem com os dados do painel selecionando valores em widgets de filtro em tempo de execução. Isso executa novamente as consultas associadas e apresenta visualizações criadas nos dados filtrados.

Os parâmetros modificam diretamente a consulta, que pode ser poderosa. Os filtros de conjunto de dados também podem oferecer interatividade de painel, mais recursos e melhor desempenho com grandes conjuntos de dados do que parâmetros. Consulte 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 do 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 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 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.
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 seu 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. 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.

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 quando o conjunto de dados é atualizado. 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)

Tipos de filtro

Os filtros do Seletor de Dados e Valor Único suportam parâmetros de configuração. Ao definir parâmetros baseados em consulta com um filtro do Seletor de Data, 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 cinza. Os usuários podem escolher datas cinza mesmo que elas não estejam incluídas 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âmetros, para que possam 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 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.

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 uma aplicação consistente dos mesmos filtros e parâmetros.

Exemplos de sintaxe de parâmetros

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

Inserir uma data

O exemplo a seguir inclui um parâmetro Date 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 Numeric que limita os resultados a registros em que o o_total_price campo é maior do 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, o field_param é usado com a IDENTIFIER função para fornecer um valor limite para a consulta em tempo de execução. 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, schemae table. Os visualizadores do painel podem usar widgets de filtro na tela para selecionar valores de parâmetro.

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

Consulte a cláusula IDENTIFIER.

Importante

Permitir que os visualizadores do painel 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.

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 um ID de número. A consulta usa a format_string função para concatenar as duas cadeias de caracteres e filtrar as linhas correspondentes. Veja format_string função.

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

Parâmetros do painel vs. parâmetros de consulta do Databricks SQL

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