Использование именованных маркеров параметров

Именованные маркеры параметров позволяют вставлять значения переменных в запросы SQL во время выполнения. Вместо жесткого написания определенных значений вы определяете типизированные заполнители, которые пользователи заполняют при выполнении запроса. Это улучшает повторное использование запросов, предотвращает внедрение SQL и упрощает создание гибких интерактивных запросов.

Именованные маркеры параметров работают на следующих поверхностях Databricks:

• Редактор SQL (новые и устаревшие версии)
• Записные книжки
• Редактор набора данных панели мониторинга ИИ/BI
• пространства Джиннов

Добавление именованного маркера параметра

Вставьте параметр, введя двоеточие, за которым следует имя параметра, например :parameter_name. При добавлении именованного маркера параметра в запрос появится мини-приложение, где можно задать тип и значение параметра. См. "Работа с виджетами параметров".

В этом примере выполняется преобразование жестко закодированного запроса для использования именованного параметра.

Запуск запроса:

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

1. Удалите 5 из WHERE предложения.
2. Введите :fare_parameter на его место. Последняя строка должна читаться fare_amount < :fare_parameter.
3. Щелкните значок шестеренки рядом с виджетом параметра.
4. Задайте для типадесятичное значение.
5. Введите значение в мини-приложении параметра и нажмите кнопку "Применить изменения".
6. Нажмите кнопку Сохранить.

Типы параметров

Задайте тип параметра на панели параметров. Тип определяет, как Databricks интерпретирует и обрабатывает значение во время выполнения.

Примеры синтаксиса именованных параметров

В следующих примерах показаны распространенные шаблоны для именованных маркеров параметров.

Вставка даты

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

Вставка числа

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

Вставка имени поля

Используйте функцию IDENTIFIER для передачи имени столбца в качестве параметра. Значение параметра должно быть именем столбца из таблицы, используемой в запросе.

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

Вставка объектов базы данных

Используйте функцию с несколькими параметрами IDENTIFIER , чтобы указать каталог, схему и таблицу во время выполнения.

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

См. пункт.

Объединение нескольких параметров

Используется format_string для объединения параметров в одну отформатированную строку. См. format_string функцию.

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

Работа со строками JSON

from_json Используйте функцию для извлечения значения из строки JSON с помощью параметра в качестве ключа. Подстановка a как значения для :param возвращает 1.

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

Создание интервала

Используйте CAST для преобразования значения параметра в тип INTERVAL, используемый для вычислений на основе времени. См. тип интервала.

SELECT CAST(:param AS INTERVAL MINUTE)

Добавление диапазона дат с помощью .min и .max

Параметры даты и метки времени поддерживают виджет диапазона. Используйте .min и .max для доступа к начальной и конечной части диапазона.

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

Установите тип параметра на Date или Timestamp, а тип виджета на Диапазон.

Добавление диапазона дат с помощью двух параметров

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

Параметризация уровня агрегирования

Используется DATE_TRUNC для агрегирования результатов на выбранном пользователем уровне детализации. Передайте DAY, MONTHили YEAR в качестве значения параметра.

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

Передача нескольких значений в виде строки

Используйте ARRAY_CONTAINS, SPLITа также TRANSFORM для фильтрации по разделенным запятыми списку значений, передаваемых в виде одного строкового параметра. SPLIT анализирует строку, разделенную запятыми, и преобразует в массив. TRANSFORM обрезает пробелы из каждого элемента. ARRAY_CONTAINS проверяет, отображается ли значение таблицы в результирующем массиве.

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

Справочник по миграции синтаксиса

Используйте эту таблицу при преобразовании запросов из синтаксиса шаблонов Mustache в именованные параметры. См. синтаксис параметров Mustache для получения дополнительной информации об устаревшем синтаксисе.