KLIP 38 — Подстановка переменных

Автор: Серхио Пенья (@spena) | Целевая версия выпуска: 0.14.0; 6.1.0 | Статус: объединено | Обсуждение: https://github.com/confluentinc/ksql/pull/6259

Краткое описание: разрешить пользователям использовать подстановку переменных в операторах SQL. Подстановка переменных позволяет пользователям писать сценарии SQL с настраиваемым выводом в соответствии с потребностями их среды.

Мотивация и предпосылки

Текущий план по предоставлению инструментов и синтаксиса для миграций ksqlDB позволяет пользователям создавать сценарии SQL, которые можно запускать в средах CI/CD для проверки ожидаемой работы схемы. Также очень часто пользователи запускают свои сценарии SQL в различных средах (QA, разработка, производство и т. д.), чтобы проверить функциональность ksqlDB. Чтобы предоставить больше гибкости при настройке вывода SQL, мы можем поддержать подстановку переменных, чтобы помочь отделить специфичные для среды переменные конфигурации от кода SQL.

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

Проблема: https://github.com/confluentinc/ksql/issues/6199

Что входит в рамки

• Определить новый синтаксис для объявления и взаимодействия с пользовательскими переменными.
• Разрешить подстановку переменных в командах SQL.
• Обсудить контекст и область применения подстановки переменных.
• Предоставить конфигурацию для включения/отключения подстановки переменных.
• Поддерживать подстановку переменных на стороне сервера.

Что не входит в рамки

• Не запрашивать у пользователей ввод значений. Oracle SQL*Plus запрашивает у пользователей ввод значения переменной, если она не определена. Это полезно, но необязательно, и будет поддерживаться только ограниченно (например, CLI и UI, но не Java API или другие клиенты).

• Не предоставлять список предопределённых переменных. Некоторые базы данных предоставляют список предопределённых переменных, которые пользователи могут использовать сразу же. В настоящее время у нас нет переменных, которые мы хотели бы добавить.

• Не поддерживать UDF при определении переменных. Было бы неплохо использовать функции, такие как set var = now();, set var = uppercase('a'); и т.д. Но это требует от клиентов (CLI, UI, Java API и т. д.) наличия более совершенного механизма анализа для обнаружения UDF, отправки запроса на сервер и последующего присвоения значения переменной. Кроме того, существуют функции, которые могут выполняться в контексте CLI, например NOW(), которая должна возвращать текущее время CLI. Мы могли бы определить набор функций, которые можно использовать вместо них, и просто выполнять их в локальном контексте, но это потребует поддержки каждого клиента, что усложнит ситуацию (например, интерфейс ksqlDB).

Результат/возврат

Пользователи смогут создавать более насыщенные сценарии SQL с настроенным выводом на основе пользовательских переменных. Эти сценарии SQL могут работать с использованием определённых настроек (имена тем/формат, реплики/разделы, выражения), позволяя пользователям легко тестировать поведение в различных средах (CI/CD, кластеры QA, среды разработки/производства и т. д.).

Общедоступные API

• Будет добавлен новый синтаксис для взаимодействия с пользовательскими переменными.
• Будут добавлены новая команда CLI и/или конфигурация для отключения/включения подстановки переменных.
• Синтаксис SQL будет изменён для поддержки ссылок на переменные.

Дизайн

1. Синтаксис

Предпосылки

В ksqlDB есть синтаксис для установки свойств сервера и CLI. Используется SET для свойств сервера и SET CLI для настроек CLI. Например:

ksql> SET 'auto.offset.reset' = 'earliest';
ksql> SET CLI WRAP OFF;

Самое быстрое предположение заключается в том, что мы можем использовать SET и для пользовательских переменных. Однако мы не можем повторно использовать любой из вышеперечисленных синтаксисов из-за конфликтов с текущими именами настроек сервера и CLI. Поэтому необходимо использовать новое ключевое слово.

Некоторые идеи:

SET LOCAL   var1 = 'val1';
SET SESSION var1 = 'val1';
SET VAR     var1 = 'val1';

LOCAL может сбивать с толку пользователей, пришедших из других сред БД. LOCAL используется для сохранения области действия для каждой транзакции. После выполнения оператора переменная уничтожается. SESSION также может сбивать с толку. SESSION используется в других базах данных для переопределения системных переменных только для этого сеанса. Системные переменные похожи на свойства сервера ksqlDB. VAR кажется лучшим названием. Однако теперь мы перегружаем использование. Использование команд SET и DEFINE для работы с переменными в ksqlDB

Команды SET используются для управления различными аспектами работы сервера. Например, в будущем мы можем захотеть использовать команду SET ROLE для установки текущей роли пользователя при взаимодействии с сервером RBAC. Но как нам вывести информацию о переменных?

SET VAR var1;  # выводит имя переменной var1
SET VAR;       # перечисляет все переменные
SET;           # что делать? перечисляет всё: сервер, cli, переменные и т. д.?

Также использование одинарных кавычек в настройках SET утомительно. После их удаления у нас будет два разных набора:

• SET 'server_property' = 'server_value'
• SET VAR variable = 'variable_value'

Это тоже выглядит запутанно. Поэтому мы должны выбрать новый синтаксис для подстановки переменных.

Другие БД используют другой синтаксис для создания пользовательских переменных (DECLARE, DEFINE, \set, SET). Для ksqlDB я выберу использование DEFINE и UNDEFINE, которые использует Oracle SQL*plus (https://blogs.oracle.com/opal/sqlplus-101-substitution-variables). Любой пользователь, пришедший из этой БД, сразу поймёт команду. Это открыто для обсуждения, но пока продолжим с этим.

Создание переменных

Синтаксис:

DEFINE <name> = '<value>';

Где: 
  <name>     — имя переменной
  <value>    — значение переменной

Допустимые имена переменных начинаются с буквы или символа подчёркивания (_), за которыми следуют ноль или более буквенно-цифровых символов или символов подчёркивания.

Для значений нет определения типа. Все значения переменных должны быть заключены в одинарные кавычки.

Пример:

DEFINE replicas = '3';
DEFINE format = 'JSON';
DEFINE name = 'Tom Sawyer';

Одинарные кавычки удаляются во время подстановки переменной. Если вам нужно экранировать одинарные кавычки, то оберните значение тройными кавычками.

Пример:

# становится 'my_topic'
DEFINE topicName = '''my_topic''';      

Удаление переменных

Синтаксис:

UNDEFINE name;

Вы можете удалить определённые переменные с помощью синтаксиса UNDEFINE.

Вывод переменных

Синтаксис:

SHOW VARIABLES;

Пример:

ksql> DEFINE replicas = '3';
ksql> DEFINE format = 'AVRO';
ksql> DEFINE topicName = '''my_topic''';
ksql> SHOW VARIABLES;
 Variable Name | Value      
----------------------------
 replicas      | 3
 format        | AVRO         
 topicName     | 'my_topic' 
----------------------------

Определение переменных во время выполнения CLI

В команду CLI будет добавлен новый параметр для определения переменных:

$ ksql -d id=1 -d format=JSON
или
$ ksql --define id=1 --define format=JSON

Эти параметры в сочетании с -e или --file позволят пользователям динамически заменять переменные, найденные в файле сценария (--file) или строке запроса (-e).

Пример:

$ ksql -d id=1 -e 'select * from table where id = ${id}'
или
$ ksql -d id=1 --file test.sql

2. Область действия

Переменные временно доступны в различных областях. Они могут быть локальными во время HTTP-запроса или сеанса во время открытия/закрытия CLI или другого подключаемого модуля клиента ksqlDB. Только пользователь, открывший CLI или HTTP-запрос, может видеть определённые переменные. Другие пользователи не могут взаимодействовать с переменными других пользователей.

HTTP-запросы

Область: LOCAL

Переменные могут быть определены и заменены на стороне сервера. Область видимости переменной — выполнение HTTP-запроса.

Пример:

Запрос 1:
{
  "statement" : "
    DEFINE id = '5';
    SELECT name FROM table WHERE id = ${id};   
  "
}

Запрос 2:
{
  "statement" : "    
    SELECT name FROM table WHERE id = ${id};   
  "
}

Этот запрос успешно выполнит приведённый ниже запрос. Этот запрос завершится ошибкой, потому что ${id} не определён.

Примечание: это может измениться в будущем, когда мы представим сеансовые соединения с сервером. Но пока область видимости остаётся локальной для запроса. Команда SET ведёт себя аналогично.

CLI

Область: SESSION

В CLI пользователи начинают взаимодействовать с сервером при запуске CLI. В этой ситуации сеанс открывается при запуске CLI с командой ksql и уничтожается при вводе exit.

В настоящее время нет концепции сеанса между...