Sintaxe do parâmetro Mustache

Importante

A sintaxe dos parâmetros Mustache é suportada apenas no editor SQL legado. A Databricks recomenda o uso de marcadores de parâmetros nomeados para novas consultas. Se copiares uma consulta usando sintaxe Mustache para um caderno, editor de conjuntos de dados de dashboards de IA/BI ou espaço Genie, tens de a converter em marcadores de parâmetros nomeados antes de ser executada.

No editor SQL antigo, qualquer string enrolada em dois colchetes ({{ }}) é tratada como um parâmetro de consulta. Um widget aparece acima do painel de resultados onde você define o valor do parâmetro.

Adicionar um parâmetro de bigode

1. Pressione Cmd + I. O parâmetro é inserido na posição do cursor e aparece o diálogo Adicionar Parâmetro .
2. Introduz a palavra-chave, altere opcionalmente o título e selecione um Tipo.
3. Clique em Adicionar parâmetro.
4. Define o valor do parâmetro no widget.
5. Clique em Aplicar alterações.
6. Clique em Salvar.

Em alternativa, escreva {{ }} diretamente na consulta e clique no ícone de engrenagem no widget de parâmetros para o configurar.

Para voltar a executar a consulta com um valor diferente, atualize o widget e clique em Aplicar Alterações.

Editar, remover e reordenar parâmetros

Edit: Clica no ícone de engrenagem ao lado do widget de parâmetros. Para evitar que utilizadores que não possuem a consulta alterem o valor do parâmetro, clique em Mostrar Apenas Resultados.

Remover: Eliminar o marcador de parâmetros da consulta. O widget é removido automaticamente.

Reordenar: Clique e arraste widgets de parâmetros para a ordem desejada.

Tipos de widgets

Os seguintes tipos de widgets estão disponíveis:

Texto

Usa uma cadeia de caracteres como entrada. Barra invertida, aspas simples e duplas são escapadas automaticamente. O Azure Databricks adiciona aspas à volta do valor.

SELECT * FROM samples.tpch.customer WHERE c_name = {{ name_param }}

Número

Aceita um número como entrada.

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

Data e Hora

Parametriza valores de data e hora. Três opções estão disponíveis:

Tipo	Precisão
Date	Dia
Data e Hora	Minuto
Data e Hora (com segundos)	Segundo

Todos os valores de data e hora são passados como literais de texto e devem ser colocados entre aspas simples na sua consulta.

SELECT * FROM usage_logs WHERE date = '{{ date_param }}'

Quando seleciona uma opção Intervalo, o Azure Databricks cria dois parâmetros usando os sufixos .start e .end.

SELECT * FROM usage_logs
WHERE modified_time > '{{ date_range.start }}'
AND modified_time < '{{ date_range.end }}'

Observação

O widget Data Range retorna resultados corretos apenas para colunas do tipo DATE. Para colunas de carimbo temporal, use um widget de Data e Intervalo de Tempo.

Valores de data dinâmicos: Os widgets de data incluem um ícone azul de raio. Clique nele para selecionar valores dinâmicos como today, yesterday, this week, last week, last month, ou last year. Estes valores atualizam-se automaticamente.

Importante

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

Lista suspensa

Restringe a entrada a uma lista estática pré-definida. Suporta seleção de valor único e multivalor.

• Valor único: Envolva o parâmetro entre aspas simples na consulta.

• Multi-valor: Ativar Permitir múltiplos valores nas definições do widget. Use a opção Quotation para controlar se os valores estão envolvidos em aspas simples, duplas ou nenhuma. Atualize a sua WHERE cláusula para usar IN:

  SELECT * FROM orders WHERE status IN ( {{ status_param }} )
  

  Com aspas duplas selecionadas, a consulta resolve-se para: WHERE status IN ("value1", "value2", "value3").

Os valores da lista suspensa são cadeias de caracteres. Para usar datas ou carimbos temporais, insira-os no formato que a sua fonte de dados exigir.

Query-Based lista suspensa

Preenche as opções de menu suspenso a partir de uma consulta guardada. Comporta-se como uma lista suspensa, mas as opções são dinâmicas.

1. No campo Tipo do painel de definições, selecione Lista Suspensa Baseada em Consultas.
2. Clique no campo Consulta e selecione uma consulta guardada.

Se a consulta devolver mais do que uma coluna, o Azure Databricks utiliza a primeira coluna. Se a consulta devolver colunas nomeadas name e value, o widget mostra a name coluna mas passa o associado value à consulta em tempo de execução.

Exemplo:

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

value	Nome
1001	John Smith
1002	Jane Doe
1003	Mesas Bobby

O valor passado para a base de dados em tempo de execução é 1001, 1002, ou 1003, não o nome de visualização.

Observação

O desempenho degrada-se se a consulta de origem devolver um grande número de registos.

Usar parâmetros de bigode em dashboards antigos

Opcionalmente, as consultas podem usar parâmetros ou valores estáticos. Quando uma visualização baseada numa consulta parametrizada é adicionada a um dashboard, pode configurar cada parâmetro para usar uma de três fontes de valor:

• Parâmetro de widget: Aplica-se apenas à única visualização a que pertence. O seletor de valores aparece dentro do painel de visualização.
• Parâmetro do dashboard: Pode aplicar-se a múltiplas visualizações no dashboard. O seletor de valores aparece no topo do tablier. Adicionado por padrão quando se adiciona uma visualização parametrizada a um dashboard.
• Valor estático: Substitui o parâmetro por um valor fixo. O seletor de valores está oculto, mantendo a interface do dashboard limpa para parâmetros que não precisam de mudar.

Para aceder às definições de mapeamento de parâmetros, clique no menu kebab num widget do painel e selecione Alterar definições do widget.

Propriedades dos parâmetros do dashboard

Propriedade	Descrição
Título	O nome exibido ao lado do seletor de valores. Por defeito, a palavra-chave do parâmetro. Não é mostrado para parâmetros estáticos.
Palavra-chave	O cadeia literal para este parâmetro na consulta subjacente. Útil para depurar resultados inesperados.
Valor padrão	O valor usado quando não é especificado outro valor. Para alterar, execute a consulta com o valor desejado e clique em Guardar.
Fonte de Valor	Controla de onde vem o valor do parâmetro. Opções: Novo parâmetro de dashboard, Parâmetro de dashboard existente, Parâmetro Widget, Valor estático.