Parâmetros de consultas

Um parâmetro de consulta permite substituir valores em uma consulta em tempo de execução. Qualquer cadeia de caracteres entre chaves duplas {{ }} é tratada como um parâmetro de consulta. Um widget aparece acima do painel de resultados onde você define o valor do parâmetro. Os parâmetros de consulta são mais flexíveis do que os filtros de consulta e só devem ser usados nos casos em que os filtros de consulta não são suficientes.

Adicionar um parâmetro de consulta

1. Escreva Cmd + I. O parâmetro é inserido no cursor do texto e a caixa de diálogo Adicionar parâmetro é exibida.
   • Palavra-chave: A palavra-chave que representa o parâmetro na consulta.
   • Título: O título que aparece sobre o widget. Por padrão, o título é o mesmo que a palavra-chave.
   • Tipo: Os tipos suportados são Texto, Número, Data, Data e Hora, Data e Hora (com Segundos), Lista Suspensa e Lista Suspensa Baseada em Consulta. O padrão é Text.
2. Digite a palavra-chave, opcionalmente substitua o título e selecione o tipo de parâmetro.
3. Clique em Adicionar parâmetro.
4. No widget de parâmetro, defina o valor do parâmetro.
5. Clique em Aplicar alterações.
6. Clique em Guardar.

Como alternativa, digite chaves duplas e clique no ícone de {{ }} engrenagem perto do widget de parâmetros para editar as configurações.

Para executar novamente a consulta com um valor de parâmetro diferente, insira o valor no widget e clique em Aplicar alterações.

Editar um parâmetro de consulta

Para editar um parâmetro, clique no ícone de engrenagem ao lado do widget de parâmetro. Para impedir que os usuários que não são proprietários da consulta alterem o parâmetro, clique em Mostrar Somente Resultados. A <Keyword> caixa de diálogo do parâmetro é exibida.

Remover um parâmetro de consulta

Para remover um parâmetro de consulta, exclua-o da consulta. O widget de parâmetros desaparece e você pode reescrever sua consulta usando valores estáticos.

Alterar a ordem dos parâmetros

Para alterar a ordem em que os parâmetros são mostrados, você pode clicar e arrastar cada parâmetro para a posição desejada.

Tipos de parâmetros de consulta

• Texto
• Número
• Lista suspensa
• Lista suspensa baseada em consulta
• Data e Hora

Texto

Usa uma cadeia de caracteres como entrada. Barras invertidas, aspas simples e duplas são escapadas, e o Azure Databricks adiciona aspas a esse parâmetro. Por exemplo, uma cadeia de caracteres como mr's Li"s é transformada em 'mr\'s Li\"s' Um exemplo de uso disso pode ser

SELECT * FROM users WHERE name={{ text_param }}

Número

Usa um número como entrada. Um exemplo de utilização desta medida poderia ser:

SELECT * FROM users WHERE age={{ number_param }}

Lista suspensa

Para restringir o escopo de possíveis valores de parâmetro ao executar uma consulta, use o tipo de parâmetro Lista suspensa. Um exemplo seria SELECT * FROM users WHERE name='{{ dropdown_param }}'. Quando selecionado no painel de configurações de parâmetros, uma caixa de texto aparece onde você insere os valores permitidos, cada valor separado por uma nova linha. As listas suspensas são parâmetros de texto. Para usar datas ou datas e horas na sua Lista Suspensa, insira-as no formato exigido pela fonte de dados. As cadeias de caracteres não são escapadas. Você pode escolher entre uma lista suspensa de valor único ou de vários valores.

• Valor único: aspas simples ao redor do parâmetro são necessárias.
• Vários valores: alterne a opção Permitir vários valores . Na lista suspensa Citações, escolha se deseja deixar os parâmetros como inseridos (sem aspas) ou envolver os parâmetros com aspas simples ou duplas. Você não precisa adicionar aspas ao redor do parâmetro se escolher aspas.

Altere sua WHERE cláusula para usar a IN palavra-chave em sua consulta.

SELECT ...
FROM   ...
WHERE field IN ( {{ Multi Select Parameter }} )

O widget de seleção múltipla de parâmetros permite que você passe vários valores para o banco de dados. Se você selecionar a opção Aspas duplas para o parâmetro Quotation , sua consulta refletirá o seguinte formato: WHERE IN ("value1", "value2", "value3")

Lista suspensa baseada em consulta

Toma o resultado de uma consulta como sua entrada. Ele tem o mesmo comportamento que o parâmetro Dropdown List . Você deve salvar a consulta da lista suspensa Databricks SQL para usá-la como uma entrada em outra consulta.

1. Clique em Lista suspensa baseada em consulta em Tipo no painel de configurações.
2. Clique no campo Consulta e selecione uma consulta. Se a consulta de destino retornar um grande número de registros, o desempenho será prejudicado.

Se sua consulta de destino retornar mais de uma coluna, o Databricks SQL usará a primeira . Se sua consulta de destino retornar name e value colunas, o Databricks SQL preencherá o widget de seleção de parâmetros com a name coluna, mas executará a consulta com o .value

Por exemplo, suponha que a consulta a seguir retorna os dados na tabela.

SELECT user_uuid AS 'value', username AS 'name'
FROM users

Quando o Azure Databricks executa a consulta, o valor passado para o banco de dados seria 1001, 1002 ou 1003.

Data e Hora

O Azure Databricks tem várias opções para parametrizar valores de carimbo de data e hora, incluindo opções para simplificar a parametrização de intervalos de tempo. Selecione entre três opções de precisão variável:

Ao escolher uma opção de parâmetro Range , você cria dois parâmetros designados por .start e .end sufixos. Todas as opções passam parâmetros para sua consulta como literais de cadeia de caracteres; O Azure Databricks requer que você envolva valores de data e hora entre aspas simples ('). Por exemplo:

-- Date parameter
SELECT *
FROM usage_logs
WHERE date = '{{ date_param }}'

-- Date and Time Range parameter
SELECT *
FROM usage_logs
WHERE modified_time > '{{ date_range.start }}' and modified_time < '{{ date_range.end }}'

Os parâmetros de data usam uma interface de seleção de calendário e usam como padrão a data e hora atuais.

Valores dinâmicos de data e intervalo de datas

Quando você adiciona um parâmetro de data ou intervalo de datas à sua consulta, o widget de seleção mostra um ícone de raio azul. Clique nele para exibir valores dinâmicos como today, yesterday, , last weekthis week, last monthou last year. Esses valores são atualizados dinamicamente.

Usando parâmetros de consulta em painéis

Opcionalmente, as consultas podem usar parâmetros ou valores estáticos. Quando uma visualização baseada em uma consulta parametrizada é adicionada a um painel, a visualização pode ser configurada para usar um:

• Parâmetro do widget

  Os parâmetros do widget são específicos para uma única visualização em um painel, aparecem no painel de visualização e os valores de parâmetro especificados se aplicam somente à consulta subjacente à visualização.

• Parâmetro do painel

  Os parâmetros do painel podem ser aplicados a várias visualizações. Quando você adiciona uma visualização com base em uma consulta parametrizada a um painel, o parâmetro será adicionado como um parâmetro de painel por padrão. Os parâmetros do painel são configurados para uma ou mais visualizações em um painel e aparecem na parte superior do painel. Os valores de parâmetro especificados para um parâmetro dashboard aplicam-se a visualizações que reutilizam esse parâmetro específico do dashboard. Um painel pode ter vários parâmetros, cada um dos quais pode ser aplicado a algumas visualizações e não a outras.

• Valor estático

  Os valores estáticos são usados no lugar de um parâmetro que responde às alterações. Os valores estáticos permitem codificar um valor no lugar de um parâmetro e farão com que o parâmetro "desapareça" do painel ou widget onde aparecia anteriormente.

Ao adicionar uma visualização contendo uma consulta parametrizada, você pode escolher o título e a origem do parâmetro na consulta de visualização clicando no ícone de lápis apropriado. Você também pode selecionar a palavra-chave e um valor padrão. Consulte Propriedades do parâmetro.

Depois de adicionar uma visualização a um painel, acesse a interface de mapeamento de parâmetros clicando no menu kebab no canto superior direito de um widget de painel e, em seguida, clicando em Alterar configurações do widget.

Propriedades do parâmetro

• Título: O nome para exibição que aparece ao lado do seletor de valores no painel. O padrão é o parâmetro Keyword. Para editá-lo, clique no ícone de lápis . Os títulos não são exibidos para parâmetros estáticos do painel porque o seletor de valores está oculto. Se você selecionar Valor estático como Fonte de valor, o campo Título ficará acinzentado.

• Palavra-chave: A cadeia de caracteres literal para este parâmetro na consulta subjacente. Isso é útil para depuração se o painel não retornar os resultados esperados.

• Valor padrão: o valor usado se nenhum outro valor for especificado. Para alterar isso na tela de consulta, execute a consulta com o valor de parâmetro desejado e clique no botão Salvar .

• Fonte do valor: A origem do valor do parâmetro. Clique no ícone de lápis para escolher uma fonte.

  • Novo parâmetro do painel: crie um novo parâmetro no nível do painel. Isso permite definir um valor de parâmetro em um só lugar no painel e mapeá-lo para várias visualizações.
  • Parâmetro do painel existente: mapeie o parâmetro para um parâmetro do painel existente. Você deve especificar qual parâmetro de painel pré-existente.
  • Parâmetro do widget: exibe um seletor de valor dentro do widget do painel. Isso é útil para parâmetros únicos que não são compartilhados entre widgets.
  • Valor estático: escolha um valor estático para o widget, independentemente dos valores usados em outros widgets. Os valores de parâmetros mapeados estaticamente não exibem um seletor de valores em nenhum lugar do painel, que é mais compacto. Isso permite que você aproveite a flexibilidade dos parâmetros de consulta sem sobrecarregar a interface do usuário em um painel quando não se espera que determinados parâmetros sejam alterados com frequência.

  

Perguntas Mais Frequentes (FAQ)

• Posso reutilizar o mesmo parâmetro várias vezes em uma única consulta?
• Posso usar vários parâmetros em uma única consulta?

Posso reutilizar o mesmo parâmetro várias vezes em uma única consulta?

Sim. Use o mesmo identificador entre parênteses. Este exemplo usa o {{org_id}} parâmetro duas vezes.

SELECT {{org_id}}, count(0)
FROM queries
WHERE org_id = {{org_id}}

Posso usar vários parâmetros em uma única consulta?

Sim. Use um nome exclusivo para cada parâmetro. Este exemplo usa dois parâmetros: {{org_id}} e {{start_date}}.

SELECT count(0)
FROM queries
WHERE org_id = {{org_id}} AND created_at > '{{start_date}}'