Parâmetros de consulta

Importante

Esta funcionalidade está em Pré-visualização Pública. Para pedir acesso, contacte o seu representante do Azure Databricks.

Um parâmetro de consulta permite-lhe substituir valores numa consulta em tempo de execução. Qualquer corda entre aparelhos duplos encaracolados {{ }} é tratada como um parâmetro de consulta. Um widget aparece acima do painel de resultados onde se define o valor do parâmetro.

Parâmetro de consulta

Para uma demonstração, consulte o vídeo dos parâmetros de consulta.

Adicione um parâmetro de consulta

  1. Clique no botão de novo parâmetro de adicionar novo parâmetro ou tipo  Cmd + P.

    O parâmetro é inserido no texto e nos visores de diálogo do parâmetro add.

    Novo Diálogo de Parâmetros

    • Palavra-chave: A palavra-chave que representa o parâmetro na consulta.
    • Título: O título que aparece sobre o widget. Por predefiniçã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 de downdown e lista de dropdown baseada em consulta. O padrão é Texto.
  2. Introduza a palavra-chave, substitua opcionalmente o título e selecione o tipo de parâmetro.

  3. Clique em Adicionar Parâmetro.

  4. No widget de parâmetro, desafie o valor do parâmetro.

  5. Clique em Aplicar Alterações.

  6. Clique em Guardar.

Para re-executar a consulta com um valor de parâmetro diferente, introduza 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 evitar que os utilizadores que não possuam a consulta mudem o parâmetro, clique em Mostrar Apenas Resultados.

Parâmetro de consulta

O <Keyword> diálogo do parâmetro apresenta:

Definições de parâmetros

Tipos de parâmetros de consulta

Texto

Pega uma corda como entrada. Backslash, uma citação única e uma citação dupla escapam, e a Azure Databricks adiciona aspas a este parâmetro. Por exemplo, uma corda como mr's Li"s é transformada em Um exemplo de usar isto pode 'mr\'s Li\"s' ser

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

Número

Toma um número como entrada. Um exemplo de usar isto pode ser

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

Data, Data e Hora, Data e Hora (com segundos)

Estes três parâmetros são muito semelhantes. A única diferença é a sua precisão. Demoram um tempo específico (12/11/2020 12:01) ou uma corda que representa o (Today, Yesterday) tempo. Um exemplo deste parâmetro SELECT * from usage_logs where date='{{ date_param }}' seria. Deve adicionar as marcas de citação ao parâmetro.

Os parâmetros da data utilizam uma interface de colheita de calendário familiar e podem predefinir a data e hora atuais. Pode escolher entre três níveis de precisão: Data, Data e Hora e Data e Hora com segundos.

Nota

Os parâmetros da data são passados para a sua base de dados como cordas. Deve embrulhá-las em cotações únicas ' () ou o que a sua base de dados necessitar para declarar cordas.

Intervalo de data, data e intervalo de tempo, data e intervalo de tempo (com segundos)

Os parâmetros da gama de datas têm uma data de início e uma data de fim (12/09/2020 12:01 - 12/11/2020 13:01) ou uma faixa que representa a hora (Last week, Last month) . Estes parâmetros inserem dois marcadores chamados .start e que significam o início e o fim do intervalo de .end datas escolhidos. Um exemplo deste parâmetro seria

SELECT year(birthDate) as birthYear, count(*) AS total
FROM default.people10m
WHERE firstName = {{ Name }} AND gender = 'F' and birthDate > '{{ Date Range.start }}' and birthDate < '{{ Date Range.end }}'
GROUP BY birthYear
ORDER BY birthYear

Deve adicionar as marcas de citação ao parâmetro.

Os parâmetros de intervalo de data utilizam um widget combinado para simplificar a seleção de alcance.

Parâmetro de intervalo de data

Valores dinâmicos da gama de datas e datas

Quando adiciona um parâmetro de intervalo de data ou data à sua consulta, o widget de seleção mostra um ícone de relâmpago azul. Clique nele para exibir valores dinâmicos como last month yesterday , ou last year . Estes valores atualizam-se dinamicamente todos os dias.

Datas dinâmicas

Importante

Datas dinâmicas e intervalos de datas não são compatíveis com consultas programadas.

Para restringir o âmbito de aplicação de possíveis valores de parâmetros ao executar uma consulta, pode utilizar o tipo de parâmetro Dropdown List. Um exemplo SELECT * FROM users WHERE name='{{ dropdown_param }}' seria. Quando selecionado a partir do painel de definições de parâmetros, aparece uma caixa de texto onde pode introduzir os valores permitidos, cada um separado por uma nova linha. As listas de dropdown são parâmetros de texto, por isso, se pretender utilizar datas ou datas e horas na sua Lista de Recuos, deverá inseri-las no formato que a sua fonte de dados requer. As cordas não escapam. Pode escolher entre um único valor ou uma queda de vários valores.

  • Valor único: São necessárias cotações únicas em torno do parâmetro.

  • Multi-valor: Alternar a opção Permitir vários valores. No drop-down de cotação, escolha se embrulhe ou não os parâmetros com cotações ou utilize cotações simples ou duplas. Se escolher as cotações, não precisa de adicionar citações em torno do parâmetro.

    Permitir múltiplos valores

Na sua consulta, altere a sua WHERE cláusula para usar a IN palavra-chave.

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

O widget multi-selecção de parâmetros permite-lhe passar vários valores para a base de dados.

Multi-selecção-widget

Lista de dropdown baseada em consulta

Toma o resultado de uma consulta como sua entrada. Tem o mesmo comportamento que o parâmetro da Lista de Recuo.

  1. Clique na lista de dropdown baseada em consulta sob o tipo no painel de definições.
  2. Clique no campo de consulta e selecione uma consulta. Se a consulta do seu alvo devolver um grande número de registos, o desempenho irá degradar-se.

Se a sua consulta de destino devolver mais do que uma coluna, a SQL Analytics utiliza a primeira. Se a sua consulta de destino retornar name e value colunas, a SQL Analytics povoa o widget de seleção de parâmetros com a name coluna, mas executa a consulta com o associado value .

Por exemplo, suponha que esta consulta:

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

retorna estes dados:

valor name
1001 João Silva
1002 Desconhecida
1003 Mesas de Bobby

O widget Dropdown List seria como:

John Smith, Jane Doe e Bobby Tables

Quando a SQL Analytics executa a consulta, o valor passado para a base de dados seria 1001, 1002 ou 1003.

Mapeamento de parâmetros de consulta em dashboards

Pode controlar os parâmetros de consulta dentro dos dashboards. Pode ligar parâmetros em diferentes widgets, definir valores de parâmetros estáticos ou escolher valores individualmente para cada widget.

Selecione os mapeamentos de parâmetros ao adicionar widgets de painel que dependem de um valor de parâmetro. Cada parâmetro na consulta subjacente aparece na lista de Parâmetros.

Mapeamento de parâmetros

Também pode aceder à interface de mapeamento de parâmetros clicando na elipse vertical  Elipsis vertical no canto superior direito de um widget do painel de instrumentos e, em seguida, clicando em Parâmetros de Edição. As propriedades dos parâmetros exibem:

  • Denominação: O nome do visor que aparece ao lado do seletor de valor no seu painel de instrumentos. Está em incumprimento do parâmetro Palavra-chave. Para editá-lo, clique no ícone do  lápis Ícone de Lápis. Os títulos não são apresentados para parâmetros estáticos do painel de instrumentos porque o seletor de valor está escondido. Se selecionar o valor estático como fonte de valor, o campo Título está acinzentado.
  • Palavra-chave: A corda literal para este parâmetro na consulta subjacente. Isto é útil para depurar se o seu painel de instrumentos não devolver os resultados esperados.
  • Valor predefinido: O valor utilizado se nenhum outro valor for especificado. Para alterar isto a partir do ecrã de consulta, execute a consulta com o valor do parâmetro pretendido e clique no botão Guardar.
  • Fonte de valor: A fonte do valor do parâmetro. Clique no ícone do  lápis Ícone de lápis para escolher uma fonte.
    • Novo parâmetro do painel : Criar um novo parâmetro de nível de painel. Isto permite definir um valor de parâmetro num lugar no seu painel de instrumentos e mapeá-lo para múltiplas visualizações.
    • Parâmetro do painel existente: Parâmetro do mapa para um parâmetro do painel existente. Deve especificar qual o parâmetro do painel pré-existente.
    • Parâmetro Widget: Exibe um seletor de valor dentro do widget do painel de instrumentos. Isto é útil para parâmetros pontuais que não são partilhados entre widgets.
    • Valor estático: Escolha um valor estático para o widget, independentemente dos valores utilizados em outros widgets. Os valores dos parâmetros estáticos não apresentam um seletor de valor em qualquer lugar do painel de instrumentos que seja mais compacto. Isto permite-lhe tirar partido da flexibilidade dos parâmetros de consulta sem desordenar a interface do utilizador num dashboard quando não se prevê que determinados parâmetros se alterem frequentemente.

Perguntas Mais Frequentes (FAQ)

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

Yes. Utilize o mesmo identificador nos suportes encaracolados. Este exemplo utiliza 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 numa única consulta?

Yes. Use um nome único para cada parâmetro. Este exemplo utiliza dois parâmetros: {{org_id}} e {{start_date}} .

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