KLIP-29: Явные ключи

Автор: @big-andy-coates | Целевая версия: 0.10.0; 6.0.0 | Статус: Объединено | Обсуждение: Github PR

Краткое содержание: До сих пор ksqlDB добавлял неявный ROWKEY STRING (PRIMARY) KEY в оператор CREATE TABLE или CREATE STREAM, который явно не определяет столбец ключа. Этот KLIP предлагает удалить этот неявный столбец и вместо этого требует, чтобы таблицы определяли свой PRIMARY KEY, а также изменить CREATE STREAM для создания потока без столбца KEY, если он не определён.

Мотивация и обоснование

Неявное добавление столбцов сбивает пользователей с толку. Они задаются вопросом, откуда взялся этот столбец? Например:

ksal> CREATE STREAM S (ID INT, NAME STRING) WITH (...);
Stream S Created.
ksal> CREATE STREAM S2 AS SELECT ID, NAME FROM S;
Key missing from projection. See https://cnfl.io/2LV7ouS.
The query used to build `S2` must include the key column ROWKEY in its projection.

Понятно, что пользователь может задаться вопросом, откуда появился этот столбец ROWKEY и почему его нужно добавить в проекцию.

Теперь, когда ksqlDB поддерживает больше, чем просто STRING ключевые столбцы, больше нет смысла добавлять неявный ключевой столбец по умолчанию. Лучше позволить пользователю определить, есть ли ключевой столбец, и если да, то каковы его имя и тип.

Нет семантической необходимости в том, чтобы поток имел данные в ключе, и поэтому не должно быть необходимости в определении столбца ключа. Это также может быть полезно, когда данные в ключе не находятся в формате, с которым может работать ksqlDB, например ключ Avro, JSON или Protobuf или любой другой формат. Кажется неудобным и запутанным добавлять неявную строку STRING, если фактический ключ пуст или ksqlDB не может его прочитать.

В отличие от потоков, таблицам требуется столбец PRIMARY KEY. Поэтому мы должны потребовать, чтобы пользователь предоставил его.

Что входит в объём изменений

• Операторы CREATE TABLE будут требовать определения столбца PRIMARY KEY.
• Операторы CREATE STREAM без определённого столбца KEY определят поток без столбца ключа.

Что не входит в объём изменений

• Всё остальное.

Ценность/возврат

Удаление неявно добавленных столбцов делает операторы более декларативными. Они позволяют описать поток без данных или несовместимых данных в ключе. Они заставляют пользователей думать об имени и типе столбца PRIMARY KEY своих таблиц.

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

Публичные API

Изменения CREATE TABLE

Оператор CREATE TABLE, который не определяет столбец PRIMARY KEY, теперь приведёт к ошибке:

ksql> CREATE TABLE INPUT (A INT, B STRING) WITH (...);
Tables require a PRIMARY KEY. Please define the PRIMARY KEY.

Операторы со столбцом PRIMARY KEY продолжат работать как раньше.

Там, где используется вывод схемы, сообщение об ошибке будет включать пример того, как определить частичную схему для добавления первичного ключа:

ksql> CREATE TABLE INPUT WITH (value_foramt='Avro', ...);
Tables require a PRIMARY KEY. Please define the PRIMARY KEY.
You can define just the primary key and still load the value columns from the Schema registry, for example:
  CREATE TABLE INPUT (ID INT PRIMARY KEY) WITH (value_foramt='Avro', ...);

Изменения CREATE STREAM

Оператор CREATE STREAM, который не определяет ключевой столбец, теперь приведёт к потоку без чтения данных из ключа записи Kafka.

CREATE STREAM INPUT (A INT, B STRING) WITH (...);
-- Results in INPUT with schema: A INT, B STRING, i.e. no key column.

Операторы с ключевым столбцом продолжат работать как прежде.

Дизайн

Это в основном изменение синтаксиса, как подробно описано выше.

Потоки без ключевого столбца будут работать так же, как и любые другие потоки. Однако GROUP BY, PARTITION BY и JOIN всегда будут приводить к переразбиению, поскольку выражение группировки, разбиения или соединения никогда не может быть ключевым столбцом.

Внутренне ksqlDB и библиотека Kafka Streams, которую он использует, активно используют модель «ключ-значение». Где создаётся поток... Без ключевого столбца ksqlDB будет внутренне обрабатывать ключ как тип Void, и ключ всегда будет десериализоваться в null, независимо от двоичной полезной нагрузки в ключе записи Kafka.

Аналогично, когда строка из потока без ключа сохраняется в Kafka, ключ будет сериализован как null.

План тестирования

Обеспечьте покрытие потоков без ключей в тестах QTT, особенно для GROUP BY, PARTITION BY и JOIN.

LOE и этапы поставки

Единый результат с низким уровнем LOE (прототип уже работает).

Обновления документации

Соответствующие обновления документации для операторов CREATE TABLE и CREATE STREAM будут выполнены в рамках KLIP.

Кроме того, обновления для остальных документов ksqlDB, микросайта руководств по Kafka и примеров репозитория будут выполняться вместе с другими изменениями синтаксиса.

В примечаниях к выпуску будет указано на это изменение в поведении.

Последствия для совместимости

Операторы CREATE, отправленные в предыдущих версиях ksqlDB, продолжат работать, как ожидалось.

Пользователи, отправляющие ранее написанные операторы, могут увидеть, что операторы CREATE TABLE, которые ранее выполнялись, теперь завершаются ошибкой, а операторы CREATE STREAM создают потоки без столбца ROWKEY STRING KEY.

Пользователям, получающим ошибку при сбое их операторов CREATE TABLE, необходимо обновить свои операторы, чтобы включить подходящий столбец PRIMARY KEY. Если оператор уже содержит набор столбцов, добавление столбца PRIMARY KEY должно быть простым. Однако пользователи могут быть более озадачены, если оператор использует вывод схемы, например, загружая столбцы значений из реестра схем:

-- существующий оператор создания, который загружает столбцы значений из реестра схемы: 
CREATE TABLE OUTPUT WITH (value_format='Avro', kafka_topic='input');

Поскольку ksqlDB ещё не поддерживает загрузку ключевой схемы из реестра схем, пользователь должен теперь указать PRIMARY KEY в частичной схеме. (Поддержка частичной схемы была добавлена в версии v0.9):

-- обновлённый оператор создания, который загружает столбцы значений из реестра схемы: 
CREATE TABLE OUTPUT (ID INT PRIMARY KEY) WITH (value_format='Avro', kafka_topic='input');

Сообщение об ошибке, отображаемое пользователям при отсутствии первичного ключа, будет включать информацию о частичных схемах, если в операторе используется вывод схемы.

Изменение в CREATE STREAM более тонкое, так как ничего не выйдет из строя. Однако пользователи могут либо оставить поток без ключа, либо добавить подходящий столбец KEY, в зависимости от того, что лучше соответствует их варианту использования.

Последствия для безопасности

Нет.