KLIP 33 — формат ключа

Автор: @big-andy-coates | Целевая версия выпуска: 0.13.0; 6.1.0 | Статус: объединено | Обсуждение: https://github.com/confluentinc/ksql/pull/6017

Краткое содержание: ksqlDB в настоящее время поддерживает только ключи, совместимые с форматом KAFKA. Это ограничивает данные, с которыми может работать ksqlDB. Расширение набора форматов ключей, поддерживаемых ksqlDB, сразу же открывает возможность использования ksqlDB с ранее несовместимыми наборами данных.

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

Данные, хранящиеся в Kafka, имеют ключ и значение. Они могут быть сериализованы с использованием разных форматов, но обычно используют общий формат. ksqlDB поддерживает несколько форматов значений данных, но требует, чтобы формат данных ключа был KAFKA.

Это ограничение особенно проблематично для таблиц. ksqlDB не может получить доступ к темам журнала изменений в Kafka, которые имеют ключи в формате, отличном от KAFKA. Поскольку ключ записи Kafka является первичным ключом таблицы, важно, чтобы ключ можно было прочитать, если журнал изменений должен быть материализован в таблицу. Когда темы журнала изменений имеют форматы ключей, отличные от KAFKA, это ограничение исключает использование ksqlDB как решения.

Ограничение менее критично для потоков. Однако пользователь всё равно теряет возможность доступа к данным в ключе записи Kafka. Если эти данные не дублируются в значении записи, что обычно имеет место, то данные вообще недоступны. Если данные необходимы, это ограничение также исключает использование ksqlDB как решение.

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

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

Чтобы открыть ksqlDB для новых областей применения и стимулировать его принятие, ksqlDB должен поддерживать другие форматы ключей.

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

• Добавление нового необязательного свойства KEY_FORMAT в предложении WITH для установки формата ключа.
• Добавление нового необязательного свойства FORMAT в предложении WITH, чтобы установить форматы ключа и значения.
• Добавление новой конфигурации сервера для предоставления значений по умолчанию для формата ключа.
• Поддержка дополнительных типов данных столбца ключа, где формат ключа поддерживает это:
  • DECIMAL
  • BOOLEAN
• Поддержка следующих форматов ключей:
  • KAFKA: текущий формат ключа.
  • DELIMITED: отдельные столбцы ключей в виде одной строки.
  • JSON / JSON_SR: отдельный столбец ключа как анонимное значение, т. е. не внутри объекта JSON.
  • AVRO: отдельный столбец ключа как анонимное значение, т. е. не внутри записи Avro.
  • NONE: специальный формат, указывающий на отсутствие данных или игнорируемые данные, например поток без ключа.
  • Хранение и извлечение схем ключей из реестра схем для форматов, поддерживающих интеграцию.
  • Полная поддержка этих форматов ключей для всего поддерживаемого синтаксиса SQL.
  • Автоматическое переразбиение потоков и таблиц для объединений, когда форматы ключей не совпадают.
  • Поддержка чтения и записи схем ключей в реестр схем и из него.
  • Улучшения QTT и инструмента тестирования ksqlDB, позволяющие использовать ключи с форматами, отличными от KAFKA.

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

• Поддержка нескольких столбцов ключей: это будет позже.
• Поддержка отдельных столбцов ключей, обёрнутых в конверт какого-либо вида: это будет позже.
• Поддержка сложных типов данных столбцов ключа, таких как массив, структура и карта: это будет позже.
• Поддержка ключей PROTOBUF, поскольку это требует поддержки обёрнутых ключей: это будет позже.
• Улучшение DataGen для поддержки ключей, отличных от KAFKA.
• Эволюция схемы ключей (см. эволюцию схемы ключей) в разделе совместимости. Явно установите

Формат ключа на «NONE» и попытайтесь создать поток, ksqlDB попытается прочитать схему ключа из реестра схем и сообщит об ошибке, если схема не существует. Формат «NONE» позволит пользователям переопределить формат ключа по умолчанию и явно сообщить ksqlDB игнорировать ключ:

SET 'ksql.persistence.default.format.key'='AVRO';

-- Только столбцы значений CLICKS будут загружены из реестра схемы.
CREATE STREAM CLICKS 
 WITH (
   key_format='NONE',  -- Информирует ksqlDB игнорировать ключ
   value_format='AVRO',
   ...
);

Объявление таблицы с форматом ключа «NONE» приведёт к ошибке.

Определение ключевых столбцов в операторах CREATE TABLE или CREATE STREAM, где формат ключа — «NONE», приведёт к ошибке:

CREATE TABLE USER (
   ID INT PRIMARY KEY, 
   NAME STRING
 ) WITH (
   key_format='NONE'  -- Ошибка! Нельзя определять ключевые столбцы с этим форматом
   ...
)  

Операторы CREATE AS, которые устанавливают ключ, то есть содержащие GROUP BY, PARTITION BY и JOIN, где источник имеет формат ключа «NONE», и которые явно не определяют формат ключа, будут получать свой формат ключа из новой системной конфигурации ksql.persistence.default.format.key. Если этот параметр не установлен, оператор выдаст ошибку.

CREATE STREAM KEY_LESS (
   NAME STRING
 ) WITH (
   key_format='NONE',
   ...
);

-- Таблица T получит формат ключа из системной конфигурации 'ksql.persistence.default.format.key'. 
-- Если конфигурация не установлена, будет сгенерирована ошибка. 
CREATE TABLE T AS 
  SELECT 
    NAME, 
    COUNT()
  FROM KEY_LESS
  GROUP BY NAME;

Операторы CREATE AS, создающие потоки без ключей, теперь неявно установят формат ключа на NONE.

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

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

Этапы и контрольные точки

Проект KLIP будет разбит на следующие этапы:

1. Базовая поддержка JSON (5 недель): Поддержка формата ключа JSON без:

   • интеграции со схемой реестра;
   • автоматического переразбиения потоков и таблиц для объединений, где форматы ключей не совпадают: такие объединения изначально приведут к ошибке.

   Включено в этот этап:

   • Добавление нового необязательного свойства KEY_FORMAT в предложении WITH для установки формата ключа.
   • Добавление нового необязательного свойства FORMAT в предложении WITH, чтобы установить форматы ключа и значения.
   • Добавление новой конфигурации сервера для предоставления значений по умолчанию для формата ключа.
   • Поддержка дополнительных типов данных столбца ключа, поскольку JSON поддерживает их:
     • DECIMAL
     • BOOLEAN
   • Полная поддержка формата ключа для всего поддерживаемого синтаксиса SQL.
   • Улучшения в QTT и инструменте тестирования ksqlDB.
   • Конечные точки REST и HTTP2 и клиент Java для работы с новым форматом ключа.

2. Формат NONE (1 неделя): Поддерживается только для ключей. Необходимо для поддержки потоков без ключей после того, как мы получим интеграцию SR.

3. Поддержка Schema Registry (1 неделя): Добавляет поддержку чтения и записи схем в реестр схем и из него.

4. JSON_SR поддержка (1 неделя) Добавляет поддержку формата ключа JSON_SR, включая интеграцию со схемой реестра.

5. Avro поддержка (1 неделя) Добавляет поддержку формата ключа AVRO, включая интеграцию со схемой реестра.

6. Delimited поддержка (1 неделя): Добавляет поддержку формата ключа DELIMITED.

7. Автоматическое переразбиение при несовпадении форматов ключей (1,5 недели). Добавляет поддержку автоматического переразбиения потоков и таблиц при объединениях, где форматы ключей не совпадают.

8. Блог-пост (1 неделя): написать пост в блоге о новых функциях. Скорее всего, один пост обо всём, кроме автоматического переразбиения, и второй, чтобы осветить это.

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

Новая конфигурация сервера и новые свойства CREATE будут добавлены на основной сайт документации. Импликации безопасности

None.