Use marcadores de parâmetros nomeados

Os marcadores de parâmetros nomeados permitem inserir valores de variáveis em consultas SQL em tempo de execução. Em vez de codificar valores específicos diretamente no código, você define marcadores tipados que os usuários preenchem durante a execução da consulta. Isso melhora a reutilização de consultas, previne injeções de SQL e facilita a criação de consultas flexíveis e interativas.

Os marcadores de parâmetros nomeados funcionam nas seguintes superfícies do Databricks:

• Editor SQL (novo e antigo)
• cadernos
• AI/BI dashboard dataset editor
• Genie spaces

Adicione um marcador de parâmetro nomeado

Insira um parâmetro digitando dois pontos seguidos de um nome de parâmetro, como :parameter_name. Ao adicionar um marcador de parâmetro nomeado a uma consulta, um widget aparece onde você pode definir o tipo e o valor do parâmetro. Consulte Trabalhar com widgets de parâmetros.

Este exemplo converte uma consulta codificada para usar um parâmetro nomeado.

Consulta inicial:

SQL

SELECT
  trip_distance,
  fare_amount
FROM
  samples.nyctaxi.trips
WHERE
  fare_amount < 5

1. Elimine 5 da cláusula WHERE .
2. Digite :fare_parameter em seu lugar. A última linha deve ser lida como fare_amount < :fare_parameter.
3. Clique no ícone de engrenagem próximo ao widget de parâmetros.
4. Defina o tipo como Decimal .
5. Insira um valor no widget de parâmetros e clique em Aplicar alterações .
6. Clique em Salvar .

Tipos de parâmetros

Defina o tipo de parâmetro no painel de configurações de parâmetros. O tipo determina como o Databricks interpreta e manipula o valor em tempo de execução.

Tipo	Descrição
String	Texto livre. A barra invertida, as aspas simples e as aspas duplas são escapadas automaticamente. O Databricks adiciona aspas em torno do valor.
Integer	Valor numérico inteiro.
Decimal	Valor numérico que suporta valores fracionários.
Data	Valor da data. Utiliza um seletor de calendário e define a data atual por padrão.
Carimbo de data/hora	Valor de data e hora. Utiliza um seletor de calendário e define por padrão a data e hora atuais.

Exemplos de sintaxe de parâmetros nomeados

Os exemplos a seguir mostram padrões comuns para marcadores de parâmetros nomeados.

Insira uma data

SQL

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

Insira um número

SQL

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  o_totalprice AS Price
FROM
  samples.tpch.orders
WHERE
  o_totalprice > :num_param

Insira um nome de campo

Use a função IDENTIFIER para passar um nome de coluna como parâmetro. O valor do parâmetro deve ser o nome de uma coluna da tabela usada na consulta.

SQL

SELECT * FROM samples.tpch.orders
WHERE IDENTIFIER(:field_param) < 10000

Inserir objetos de banco de dados

Use a função IDENTIFIER com vários parâmetros para especificar um catálogo, esquema e tabela em tempo de execução.

SQL

SELECT *
FROM IDENTIFIER(:catalog || '.' || :schema || '.' || :table)

Consulte a cláusula IDENTIFIER.

Concatenar múltiplos parâmetros

Use format_string para combinar parâmetros em uma única string formatada. Consulte a função format_string.

SQL

SELECT o_orderkey, o_clerk
FROM samples.tpch.orders
WHERE o_clerk LIKE format_string('%s%s', :title, :emp_number)

Trabalhar com strings JSON

Use a funçãofrom_json para extrair um valor de uma string JSON usando um parâmetro como key. Substituindo a como o valor de :param retorna 1.

SQL

SELECT from_json('{"a": 1}', 'map<string, int>') [:param]

Criar um intervalo

Use CAST para converter um valor de parâmetro para um tipo INTERVAL para cálculos baseados em tempo. Consulte Tipo de intervalo.

SQL

SELECT CAST(:param AS INTERVAL MINUTE)

Adicione um intervalo de datas usando .min e .max

Os parâmetros de data e hora suportam um widget de intervalo. Use .min e .max para acessar o início e o fim do intervalo.

SQL

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN :date_range.min AND :date_range.max

Defina o tipo de parâmetro como Date ou Timestamp e o tipo de widget como Intervalo .

Adicionar um intervalo de datas usando dois parâmetros

SQL

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

Parametrizar a granularidade do rollup

Use DATE_TRUNC para agregar resultados em um nível de granularidade selecionado pelo usuário. Passe DAY, MONTH ou YEAR como valor do parâmetro.

SQL

SELECT
  DATE_TRUNC(:date_granularity, tpep_pickup_datetime) AS date_rollup,
  COUNT(*) AS total_trips
FROM samples.nyctaxi.trips
GROUP BY date_rollup

Passe vários valores como strings.

Use ARRAY_CONTAINS, SPLIT e TRANSFORM para filtrar uma lista de valores separados por vírgulas passada como um único parâmetro de strings. SPLIT analisa as strings separadas por vírgulas em uma matriz. TRANSFORM remove espaços em branco de cada elemento. ARRAY_CONTAINS verifica se o valor da tabela aparece na matriz resultante.

SQL

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

nota

Este exemplo funciona para valores de texto (strings). Para usar outros tipos de dados, envolva as operações TRANSFORM com um CAST para converter os elementos para o tipo desejado.

Referência de migração de sintaxe

Use esta tabela ao converter consultas da sintaxe Mustache para marcadores de parâmetros nomeados. Consulte a sintaxe de parâmetros Mustache para obter mais informações sobre a sintaxe legada.

Caso de uso	Sintaxe de bigode	Sintaxe de parâmetro nomeado
Filtrar por data	WHERE date_field < '{{date_param}}'	WHERE date_field < :date_param
Filtrar por número	WHERE price < {{max_price}}	WHERE price < :max_price
Comparar strings	WHERE region = '{{region_param}}'	WHERE region = :region_param
Especifique uma tabela	SELECT * FROM {{table_name}}	SELECT * FROM IDENTIFIER(:table) — use o espaço de nomes completo de três níveis
Especifique o catálogo, o esquema e a tabela.	SELECT * FROM {{catalog}}.{{schema}}.{{table}}	SELECT * FROM IDENTIFIER(:catalog || '.' || :schema || '.' || :table)
Formatar uma string a partir de múltiplos parâmetros	"({{area_code}}) {{phone_number}}"	format_string("(%d) %d", :area_code, :phone_number)
Crie um intervalo	SELECT INTERVAL {{p}} MINUTE	SELECT CAST(format_string("INTERVAL '%s' MINUTE", :param) AS INTERVAL MINUTE)