O que são parâmetros de painel?

Os parâmetros do painel são uma forma de tornar os painéis interativos, permitindo que os visualizadores usem seletores de valor único e selecionadores de data para inserir valores específicos nas consultas do site dataset 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 mais precisas.

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

Os parâmetros modificam diretamente a consulta, o que pode ser poderoso. dataset Os filtros também podem oferecer interatividade de painel, mais recursos e melhor desempenho com grandes conjuntos de dados do que os parâmetros. Veja os filtros.

Adicionar um parâmetro a uma consulta

O senhor deve ter pelo menos a permissão Can Edit 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

O senhor pode definir um valor default para o 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.

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.

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.

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.

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 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 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 do banco de dados

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

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 o senhor estiver publicando um painel com essas opções, a Databricks recomenda não incorporar credenciais no painel publicado.

Concatenar vários parâmetros

O senhor pode incluir parâmetros em outras funções SQL. Esse exemplo permite que o visualizador selecione um título de funcionário e um número de ID. A consulta usa a função format_string para concatenar os dois strings 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 do painel vs. parâmetros de consulta do site Databricks SQL

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 são compatíveis com os parâmetros de estilo do site Databricks SQL.