Uso de marcadores de parámetros con nombre

Los marcadores de parámetros con nombre permiten insertar valores de variable en consultas SQL en tiempo de ejecución. En lugar de codificar valores específicos de forma rígida, se definen marcadores de posición tipados que los usuarios rellenan cuando se ejecuta la consulta. Esto mejora la reutilización de consultas, evita la inserción de SQL y facilita la creación de consultas flexibles e interactivas.

Los marcadores de parámetros con nombre funcionan en las siguientes superficies de Databricks:

• Editor de SQL (nuevo y heredado)
• Cuadernos
• Editor de conjunto de datos de panel AI/BI
• Espacios de Genie

Adición de un marcador de parámetro con nombre

Inserte un parámetro escribiendo dos puntos seguidos de un nombre de parámetro, como :parameter_name. Al agregar un marcador de parámetro con nombre a una consulta, aparece un widget donde puede establecer el tipo de parámetro y el valor. Consulte Trabajar con widgets de parámetros.

En este ejemplo se convierte una consulta codificada de forma rígida para usar un parámetro con nombre.

Consulta de inicio:

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

1. Elimine 5 de la WHERE cláusula .
2. Escriba :fare_parameter en su lugar. La última línea debe leer fare_amount < :fare_parameter.
3. Haga clic en el icono de engranaje cerca del widget de parámetros.
4. Establezca el tipo en Decimal.
5. Escriba un valor en el widget de parámetros y haga clic en Aplicar cambios.
6. Haga clic en Guardar.

Tipos de parámetro

Establezca el tipo de parámetro en el panel de configuración de parámetros. El tipo determina cómo Databricks interpreta y controla el valor en tiempo de ejecución.

Tipo	Descripción
String	Texto de forma libre. Las barras diagonales inversas, las comillas simples y dobles se escapan automáticamente. Databricks agrega comillas alrededor del valor.
Entero	Valor de número entero.
Decimal	Valor numérico que admite valores fraccionarios.
Fecha	Valor de fecha. Usa un selector de calendario y se predetermina a la fecha actual.
Timestamp	Valor de fecha y hora. Usa un selector de calendario y se predetermina en la fecha y hora actuales.

Ejemplos de sintaxis de parámetros con nombre

En los ejemplos siguientes se muestran patrones comunes para los marcadores de parámetros con nombre.

Insertar una fecha

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

Insertar un número

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

Insertar un nombre de campo

Use la IDENTIFIER función para pasar un nombre de columna como parámetro. El valor del parámetro debe ser un nombre de columna de la tabla utilizada en la consulta.

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

Insertar objetos de base de datos

Use la IDENTIFIER función con varios parámetros para especificar un catálogo, un esquema y una tabla en tiempo de ejecución.

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

Consulte la cláusula IDENTIFIER.

Concatenar varios parámetros

Use format_string para combinar parámetros en una sola cadena con formato. Consulte la función format_string.

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

Trabajar con cadenas JSON

Use la from_json función para extraer un valor de una cadena JSON mediante un parámetro como clave. Sustituyendo a como valor para :param devuelve 1.

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

Crear un intervalo

Use CAST para convertir un valor de parámetro en un INTERVAL tipo para los cálculos basados en el tiempo. Consulte Tipo de intervalo.

SELECT CAST(:param AS INTERVAL MINUTE)

Adición de un intervalo de fechas mediante .min y .max

Los parámetros date y Timestamp admiten un widget de intervalo. Use .min y .max para acceder al inicio y al final del intervalo.

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

Establezca el tipo de parámetro en Date o Timestamp y el tipo de widget en Range.

Adición de un intervalo de fechas mediante dos parámetros

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

Parametrizar la granularidad del resumen

Use DATE_TRUNC para agregar resultados en un nivel seleccionado por el usuario de granularidad. Pase DAY, MONTHo YEAR como valor de parámetro.

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

Pasar varios valores como una cadena

Use ARRAY_CONTAINS, SPLITy TRANSFORM para filtrar por una lista separada por comas de valores pasados como un único parámetro de cadena. SPLIT analiza la cadena separada por comas en una matriz. TRANSFORM recorta el espacio en blanco de cada elemento. ARRAY_CONTAINS comprueba si el valor de la tabla aparece en la matriz resultante.

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

Nota

Este ejemplo funciona para valores de cadena. Para usar otros tipos de datos, envuelva la TRANSFORM operación con CAST para convertir los elementos en el tipo deseado.

Referencia de migración de sintaxis

Usa esta tabla al convertir consultas de sintaxis Mustache a marcadores de parámetros con nombre. Consulte Sintaxis de parámetros Mustache para obtener más información sobre la sintaxis heredada.

Caso de uso	Sintaxis de Mustache	Sintaxis de parámetros con nombre
Filtrar por fecha	WHERE date_field < '{{date_param}}'	WHERE date_field < :date_param
Filtrar por número	WHERE price < {{max_price}}	WHERE price < :max_price
Comparación de cadenas	WHERE region = '{{region_param}}'	WHERE region = :region_param
Especificar una tabla	SELECT * FROM {{table_name}}	SELECT * FROM IDENTIFIER(:table) : use el espacio de nombres completo de tres niveles.
Especificar catálogo, esquema y tabla	SELECT * FROM {{catalog}}.{{schema}}.{{table}}	SELECT * FROM IDENTIFIER(:catalog \|\| '.' \|\| :schema \|\| '.' \|\| :table)
Dar formato a una cadena de varios parámetros	"({{area_code}}) {{phone_number}}"	format_string("(%d) %d", :area_code, :phone_number)
Crear un intervalo	SELECT INTERVAL {{p}} MINUTE	SELECT CAST(format_string("INTERVAL '%s' MINUTE", :param) AS INTERVAL MINUTE)