Связаться с намиПодключиться

Сериализация

Статья создана
Обновлена 29 апреля 2025 г.

Сериализация — процесс преобразования объекта данных в битовую последовательность во время передачи в приемники, которые работают с сырыми данными. К таким приемникам относятся:

Сериализацию можно настроить во время создания или изменения эндпоинта-приемника.

Сериализация при поставке в Object Storage

При поставке в Object Storage вы можете выбрать Выходной формат: JSON, CSV, PARQUET или Сырые данные. Для JSON доступна настройка Преобразовать комплексные значения в строки.

Выходной формат данных зависит не только от выбора настройки Выходной формат, но и от типа и настроек правил конвертации эндпоинта-источника.

Ниже представлены различия выходных данных при отсутствии правил конвертации для эндпоинта-источника.

Примечание

Примеры выходных данных для формата PARQUET не приводятся, так как это бинарный формат.

Yandex Data Streams

Входные данные — два сообщения:

Text string
{"device_id":"iv9,"speed":"5"}

Выходные данные:

<имя_потока>,<ключ_сегмента>,<порядковый_номер_сообщения>,<дата_и_время_записи_данных>,Text string
<имя_потока>,<ключ_сегмента>,<порядковый_номер_сообщения>,<дата_и_время_записи_данных>,"{""device_id"":""iv9"",""speed"":5}"

{"data":"Text string","partition":<ключ_сегмента>,"seq_no":<порядковый_номер_сообщения>,"topic":"<имя_потока>","write_time":"<дата_и_время_записи_данных>"}
{"data":"{\"device_id\":\"iv9\",\"speed\":5}","partition":<ключ_сегмента>,"seq_no":<порядковый_номер_сообщения>,"topic":"<имя_потока>","write_time":"<дата_и_время_записи_данных>"}

Text string
{"device_id":"iv9,"speed":"5"}

Managed Service for PostgreSQL

Входные данные — таблица:

device_id speed
iv9 5
rhi 10

Выходные данные:

{"device_id":"iv9","speed":5}
{"device_id":"rhi","speed":10}

iv9,5,
rhi,10,

Не поддерживается.

Сериализация при поставке в очереди сообщений

При поставке в очередь сообщений вы можете использовать сериализацию двух типов:

Auto

Автоматический выбор настроек сериализации в зависимости от типа источника.

Debezium

Сериализация Debezium с возможностью настройки ее параметров:

  • dt.add.original.type.info — определяет, добавлять ли информацию об исходных типах данных, чтобы восстановить их тип после переноса.

    Исключение — типы данных даты и времени PostgreSQL with time zone. Информацию о часовом поясе восстановить невозможно.

    Значение по умолчанию — false.

  • dt.batching.max.size — максимальный размер пакета сообщений в байтах.

    Значение по умолчанию — 0 байт (пакетирование отключено). Рекомендуемое значение — 1048576 байт (1 МБ). Ненулевое значение включает пакетирование.

    Настройка актуальна, если используется JSON-сериализация со Schema Registry (см. параметры key.converter и value.converter). При использовании Schema Registry сообщения, приходящие в очередь, могут стать очень маленькими. Пакетирование в таком случае позволяет увеличить пропускную способность очередей.

    При включенном пакетировании в одно сообщение очереди помещаются последовательно несколько логических сообщений в формате Confluent wire format. Данные, сериализованные таким образом, можно однозначно декодировать.

    При включенном пакетировании сообщения накапливаются в буфере. Если новое сообщение увеличивает размер пакета сверх установленного значения dt.batching.max.size, то текущий буфер сохраняется, а новое сообщение добавляется в пустой буфер. Если одно логическое сообщение из источника превышает значение dt.batching.max.size, то будет сформирован пакет из одного такого сообщения. Пакетирование происходит до компрессии в клиенте очереди.

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

    Важно

    Пакетированные сообщения могут быть декодированы только трансфером.

  • dt.mysql.timezone — часовой пояс для типов данных даты и времени MySQL® в формате IANA.

    Значение по умолчанию — UTC.

  • dt.unknown.types.policy — политика поведения при обработке пользовательских типов данных.

    Возможные значения:

    • skip — не прерывать трансфер и игнорировать пользовательские типы данных.
    • to_string — не прерывать трансфер и преобразовать пользовательские типы данных в текст.
    • fail — прерывать трансфер с ошибкой.

    Значение по умолчанию — skip.

  • decimal.handling.mode — режим обработки действительных чисел.

    Возможные значения:

    • precise — точное преобразование с помощью метода java.math.BigDecimal.
    • double — преобразование в тип данных double. Может привести к потере точности.
    • string — преобразование в текст.

    Значение по умолчанию — precise.

  • interval.handling.mode — режим обработки временных интервалов.

    Возможные значения:

    • numeric — приблизительное преобразование в микросекунды.
    • string — точное преобразование с использованием строкового шаблона P<years>Y<months>M<days>DT<hours>H<minutes>M<seconds>S.

    Значение по умолчанию — numeric.

  • key.converter и value.converter — конвертеры для ключей и значений.

    Возможные значения:

    • org.apache.kafka.connect.json.JsonConverter — JSON, стандартный для Debezium.
    • io.confluent.connect.json.JsonSchemaConverter — Confluent Schema Registry.

    Значение по умолчанию — org.apache.kafka.connect.json.JsonConverter.

  • key.converter.schemas.enable и value.converter.schemas.enable — определяют, добавлять ли описание схемы в каждое сообщение для ключей и значений при использовании конвертера org.apache.kafka.connect.json.JsonConverter.

    Значение по умолчанию — true.

  • key.converter.schema.registry.url и value.converter.schema.registry.url — определяют, добавлять ли описание схемы в каждое сообщение для ключей и значений при использовании конвертера io.confluent.connect.json.JsonSchemaConverter.

    Возможные значения:

    • пустая строка (значение по умолчанию) — не добавлять описание схемы;
    • строковое значение URL, определяющее путь к сервису реестра схем.

  • key.converter.dt.json.generate.closed.content.schema и value.converter.dt.json.generate.closed.content.schema — определяют, будет ли схема производителя данных для ключа и значения генерироваться в закрытой контентной модели. Это нужно для проверки совместимости через конвертацию открытой модели потребителя в закрытую и поиск аналогичной схемы среди зарегистрированных для производителя схем.

    Значение по умолчанию — false.

    Чтобы сохранять полную транзитивную совместимость при добавлении и удалении опциональных полей в схеме ключа:

    1. Выберите в пространстве имен Schema Registry политику проверки совместимости Optional-friendly.
    2. В настройках сериализации эндпоинта-приемника Managed Service for Apache Kafka® задайте настройку key.converter.dt.json.generate.closed.content.schema — true.

    Чтобы сохранять полную транзитивную совместимость при добавлении и удалении опциональных полей в схеме значения:

    1. Выберите в пространстве имен Schema Registry политику проверки совместимости Optional-friendly.
    2. В настройках сериализации эндпоинта-приемника задайте настройку value.converter.dt.json.generate.closed.content.schema — true.

  • key.converter.basic.auth.user.info и value.converter.basic.auth.user.info — имя пользователя и пароль для авторизации в Confluent Schema Registry для ключей и значений при использовании конвертера io.confluent.connect.json.JsonSchemaConverter.

    Формат значения: <имя_пользователя>:<пароль>.

  • key.converter.ssl.ca и value.converter.ssl.ca — содержимое SSL-сертификата Confluent Schema Registry для ключей и значений при использовании конвертера io.confluent.connect.json.JsonSchemaConverter.

    Если значение настройки не указано, SSL-сертификат не проверяется.

  • unavailable.value.placeholder — значение, которое устанавливается вместо данных, если их тип не поддерживается.

    Значение по умолчанию — __debezium_unavailable_value.

Примеры использования

Предыдущая
Трансформация данных
Следующая
Работа Yandex Data Transfer с источниками и приемниками