Pular para o conteúdo principal
Última atualização em

Trabalhar com widgets de parâmetros

Ao adicionar um marcador de parâmetro nomeado a uma consulta, o Databricks exibe um widget de parâmetro na interface do usuário. Os widgets permitem que os usuários definam valores de parâmetros sem editar a consulta diretamente. Você pode configurar o tipo, o título e o valor default de cada widget.

Os widgets de parâmetros são suportados no editor SQL , no Notebook, nos painéis de AI/BI e Genie spaces, mas se comportam de maneira diferente em cada uma dessas interfaces. Esta página descreve os widgets de parâmetros no editor SQL. Para outras superfícies, veja:

No editor SQL , qualquer tipo de parâmetro (strings, inteiro, decimal, data, timestamp) pode usar qualquer tipo de widget.

Configure um widget de parâmetros​

  1. Adicione um marcador de parâmetro nomeado à sua consulta. Um widget aparece na interface do usuário.

  2. Clique no ícone de engrenagem ao lado do widget para abrir a caixa de diálogo do widget. caixa de diálogo para criar widget

  3. Configure os seguintes campos:

    • Nome do parâmetro : O nome do parâmetro tal como aparece na consulta. Se você alterar o nome do parâmetro na caixa de diálogo do widget, também deverá alterá-lo na consulta.
    • Rótulo do widget : Uma string que descreve o widget.
    • Tipo de widget : Controla como os usuários inserem o valor. Veja os tipos de widgets abaixo.
    • Tipo de parâmetro : O tipo de dados do parâmetro. Consulte Tipos de parâmetros.

  4. Clique fora da caixa de diálogo do widget para salvar as alterações.

Editar, remover e reordenar widgets​

Editar : Clique no ícone de engrenagem ao lado do widget para reabrir o painel de configurações.

Remover : Exclui o marcador de parâmetro da consulta. O widget é removido automaticamente.

Reordenar : Use a alça de arrastar à esquerda de um widget para reordená-lo.

Tipos de widgets​

O Databricks suporta os seguintes tipos de widgets para parâmetros de consulta:

Tipo de widget

Descrição

Dropdown

Os usuários devem escolher em uma lista predefinida.

Caixa de combinação

Os usuários podem escolher em uma lista predefinida ou digitar um valor personalizado.

Entrada de texto

Aceita qualquer valor de formato livre, sem sugestões.

Seleção múltipla

Os usuários podem selecionar mais de um valor de uma lista predefinida.

dropdowndinâmico

Preenche as opções a partir de uma consulta salva em vez de uma lista estática.

Intervalo de data e hora

Define um intervalo inicial e final usando os parâmetros .min e .max .

Entrada de texto​

Aceita um valor de formato livre diretamente do usuário. Use este widget quando não forem necessárias opções predefinidas.

SQL
SELECT * FROM samples.tpch.region WHERE r_name = :region_param

Apresenta uma lista predefinida de valores. Os usuários devem selecionar uma opção da lista — não é permitido inserir opções livremente. Insira os valores permitidos no painel de configurações, um por linha.

SQL
SELECT * FROM samples.tpch.orders WHERE o_orderstatus = :status_param

Para criar um widget dropdown digite:

  1. Clique no ícone de engrenagem ao lado do widget :status_param .
  2. Defina o tipo de widget como lista suspensa .
  3. Defina o tipo de parâmetro como strings .
  4. Insira valores no campo de entrada de texto "Opções para valor do parâmetro ". Clique em Adicionar ou pressione Enter entre cada valor.

Caixa de combinação​

Apresenta uma lista predefinida de valores sugeridos, mas também permite que os usuários digitem um valor personalizado que não esteja na lista. Use uma caixa de combinação quando opções comuns forem úteis por conveniência, mas você quiser permitir a entrada de dados em formato livre.

SQL
SELECT * FROM samples.tpch.part WHERE p_brand = :brand_param

Seleção múltipla​

Permite que os usuários selecionem mais de um valor de uma lista predefinida. Os valores selecionados são passados para a consulta como uma coleção.

SQL
SELECT * FROM samples.nyctaxi.trips WHERE
  array_contains(
    TRANSFORM(SPLIT(:list_parameter, ','), s -> TRIM(s)),
    CAST(dropoff_zip AS STRING)
  )

Para adicionar opções a uma lista dropdown múltipla:

  1. Clique no ícone de engrenagem ao lado do widget list_parameter .
  2. Defina o tipo de widget como Seleção múltipla .
  3. Defina o tipo de parâmetro como strings .
  4. Insira valores no campo de entrada de texto "Opções para valor do parâmetro ". Clique em Adicionar ou pressione Enter entre cada valor.

dropdowndinâmico​

nota

Os widgets dinâmicos dropdown estão disponíveis apenas no editor SQL , não no Notebook.

Preenche a lista de opções a partir de uma consulta salva, em vez de uma lista estática. À medida que os dados subjacentes mudam, as opções disponíveis são atualizadas automaticamente.

Para usar um dropdown dinâmico:

  1. Crie e salve uma consulta que retorne os valores desejados na dropdown:

    SQL
    SELECT DISTINCT c_mktsegment FROM samples.tpch.customer ORDER BY c_mktsegment

  2. Em uma consulta nova ou existente, adicione um marcador de parâmetro nomeado:

    SQL
    SELECT c_custkey, c_name, c_acctbal
    FROM samples.tpch.customer
    WHERE c_mktsegment = :segment_param

  3. Clique no ícone de engrenagem ao lado do widget segment_param .

  4. Defina o tipo de widget como dropdowndinâmica .

  5. Clique no campo Consulta para abrir a caixa de diálogo Selecionar consulta existente . Selecione a consulta salva na etapa 1 e clique em Selecionar .

  6. Escolha um valor padrão para o parâmetro .

  7. Clique em Aplicar alterações .

Intervalo de data e hora​

Os parâmetros de data e hora são compatíveis com o widget do tipo Intervalo . Quando selecionado, Databricks cria dois parâmetros usando os sufixos .min e .max para definir o início e o fim do intervalo.

SQL
SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN CAST(:date_range_min AS TIMESTAMP) AND CAST(:date_range_max AS TIMESTAMP)

Clique no ícone azul de raio para selecionar valores dinâmicos como today, yesterday, this week, last week, last month ou last year. Esses valores são atualizados automaticamente.

importante

Valores de data dinâmicos não são compatíveis com consultas agendadas.