Add documentation for Debezium format in YDB CDC

4 files changed, 118 insertions, 0 deletions

diff --git a/ydb/docs/en/core/concepts/cdc.md b/ydb/docs/en/core/concepts/cdc.md
index 6c49d36af4..f395665fb9 100644
--- a/ydb/docs/en/core/concepts/cdc.md
+++ b/ydb/docs/en/core/concepts/cdc.md
@@ -154,6 +154,64 @@ The record structure is the same as for [Amazon DynamoDB Streams](https://docs.a
 
 {% endif %}
 
+{% if audience == "tech" %}
+
+### Debezium-compatible JSON format {#debezium-json-record-structure}
+
+A [Debezium](https://debezium.io)-compatible JSON record structure has the following format:
+
+Message body
+```json
+{
+    "payload": {
+        "op": <op>,
+        "before": {<columns>},
+        "after": {<columns>},
+        "ts": [<step>, <txId>],
+        "source": {
+            "version": <version>,
+            "connector": <connector>,
+            "ts_ms": <ts_ms>,
+            "txId": <txId>
+        }
+    }
+}
+```
+
+* `op`: Operation that was performed on a row:
+  * "u" means Update.
+  * "s" means reSet (to not confuse with Read).
+  * "d" means Delete.
+* `before`: Row snapshot before the change. Present in `OLD_IMAGE` and `NEW_AND_OLD_IMAGES` modes. Contains column names and values. Present only if the row existed before the change.
+* `after`: Row snapshot after the change. Present in `NEW_IMAGE` and `NEW_AND_OLD_IMAGES` modes. Contains column names and values. Present only if the row exists after the change.
+* `ts`: Virtual timestamp. Present if the `VIRTUAL_TIMESTAMPS` setting is enabled. Contains the value of the global coordinator time (`step`) and the unique transaction ID (`txId`). Note that Debezium connectors usually use a single integer `ts_ms` instead.
+* `source`: Source metadata for the event.
+  * `version`: Connector version that was used to generate the record. Current version is `0.0.1`.
+  * `connector`: Connector name. Current name is `ydb_debezium_json`.
+  * `ts_ms`: Approximate time when the change was applied, in milliseconds.
+  * `txId`: Unique transaction ID.
+
+{% note warning %}
+
+Currently debezium json format doesn't have `schema` field. Other Debezium connectors have it.
+
+{% endnote %}
+
+If you use kafka API to read a topic, you will see debezium-compatible kafka key as well, in the following format:
+```json
+{
+    "payload": {
+        <columns>
+    }
+}
+```
+
+* `payload`: Key of a row that was changed. Always present.
+
+You can read more in kafka integration documentation about details on how it is stored and how to access it directly.
+
+{% endif %}
+
 ## Record retention period {#retention-period}
 
 By default, records are stored in the changefeed for 24 hours from the time they are sent. Depending on usage scenarios, the retention period can be reduced or increased up to 30 days.
diff --git a/ydb/docs/en/core/yql/reference/yql-core/syntax/_includes/alter_table.md b/ydb/docs/en/core/yql/reference/yql-core/syntax/_includes/alter_table.md
index 9f162c647d..e10ac43abb 100644
--- a/ydb/docs/en/core/yql/reference/yql-core/syntax/_includes/alter_table.md
+++ b/ydb/docs/en/core/yql/reference/yql-core/syntax/_includes/alter_table.md
@@ -84,6 +84,7 @@ ALTER TABLE `series` RENAME INDEX `title_index` TO `title_index_new`;
    * `JSON`: Write data in [JSON](../../../../concepts/cdc#json-record-structure) format.
 {% if audience == "tech" %}
    * `DYNAMODB_STREAMS_JSON`: Write data in the [JSON format compatible with Amazon DynamoDB Streams](../../../../concepts/cdc#dynamodb-streams-json-record-structure).
+   * `DEBEZIUM_JSON`: Write data in the [Debezium-like JSON format](../../../../concepts/cdc#debezium-json-record-structure).
 {% endif %}
 * `VIRTUAL_TIMESTAMPS`: Enabling/disabling [virtual timestamps](../../../../concepts/cdc#virtual-timestamps). Disabled by default.
 * `RETENTION_PERIOD`: [Record retention period](../../../../concepts/cdc#retention-period). The value type is `Interval` and the default value is 24 hours (`Interval('PT24H')`).
diff --git a/ydb/docs/ru/core/concepts/cdc.md b/ydb/docs/ru/core/concepts/cdc.md
index 5b15894fb5..75b5298901 100644
--- a/ydb/docs/ru/core/concepts/cdc.md
+++ b/ydb/docs/ru/core/concepts/cdc.md
@@ -154,6 +154,64 @@ Change Data Capture (CDC) обеспечивает захват изменени
 
 {% endif %}
 
+{% if audience == "tech" %}
+
+### JSON-формат, совместимый с Debezium {#debezium-json-record-structure}
+
+Запись в формате [JSON](https://en.wikipedia.org/wiki/JSON), совместимого с [Debezium](https://debezium.io), имеет следующую структуру:
+
+Тело сообщения:
+```json
+{
+    "payload": {
+        "op": <op>,
+        "before": {<columns>},
+        "after": {<columns>},
+        "ts": [<step>, <txId>],
+        "source": {
+            "version": <version>,
+            "connector": <connector>,
+            "ts_ms": <ts_ms>,
+            "txId": <txId>
+        }
+    }
+}
+```
+
+* `op`: операция, которая была произведена над строкой в таблице:
+  * "u" обозначает обновление.
+  * "s" обозначает сброс (reSet).
+  * "d" обозначает удаление.
+* `before`: снимок состояния строки до изменения. Присутствует в режимах `OLD_IMAGE` и `NEW_AND_OLD_IMAGES`. Содержит названия и значения столбцов. Присутствует только если строка существовала до изменения.
+* `after`: снимок состояния строки после изменения. Присутствует в режимах `NEW_IMAGE` и `NEW_AND_OLD_IMAGES`. Содержит названия и значения столбцов. Присутствует только если строка существует после изменения.
+* `ts`: виртуальная метка времени. Присутствует, если включена настройка `VIRTUAL_TIMESTAMPS`. Содержит значение глобального времени координатора (`step`) и уникальный идентификатор транзакции (`txId`). Обратите внимание, что Debezium коннекторы обычно используют число `ts_ms`.
+* `source`: метаданные записи.
+  * `version`: версия коннектора, используемая для генерации записи. Текущая версия: `0.0.1`.
+  * `connector`: название коннектора. Текущее название: `ydb_debezium_json`.
+  * `ts_ms`: примерное время применения изменения в YDB, в миллисекундах.
+  * `txId`: уникальный идентификатор транзакции.
+
+{% note warning %}
+
+Пока Debezium JSON формат не поддерживает `schema` в сообщении. Другие Debezium коннекторы это поддерживают.
+
+{% endnote %}
+
+При использовании kafka API для чтения топика, вы увидите Debezium-совместимый kafka ключ в следующем формате:
+```json
+{
+    "payload": {
+        <columns>
+    }
+}
+```
+
+* `payload`: Первичный ключ строки, которая была изменена
+
+Информацию о том, как это сохранено в сообщении, и как можно получить информацию о ключе без использования kafka API, читайте в [документации об интеграции с kafka](../reference/kafka-api/index.md)
+
+{% endif %}
+
 ## Время хранения записей {#retention-period}
 
 По умолчанию записи хранятся в потоке изменений в течение 24 часов с момента отправки. В зависимости от сценариев использования время хранения можно уменьшить или увеличить до 30 дней.
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/alter_table.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/alter_table.md
index 9efc3c6ea6..d892fe9bb4 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/alter_table.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/_includes/alter_table.md
@@ -84,6 +84,7 @@ ALTER TABLE `series` RENAME INDEX `title_index` TO `title_index_new`;
   * `JSON` — записывать данные в формате [JSON](../../../../concepts/cdc#json-record-structure).
 {% if audience == "tech" %}
   * `DYNAMODB_STREAMS_JSON` — записывать данные в [JSON-формате, совместимом с Amazon DynamoDB Streams](../../../../concepts/cdc#dynamodb-streams-json-record-structure).
+  * `DEBEZIUM_JSON` — записывать данные в [JSON-формате, аналогичном Debezium формату](../../../../concepts/cdc#debezium-json-record-structure).
 {% endif %}
 * `VIRTUAL_TIMESTAMPS` — включение-выключение [виртуальных меток времени](../../../../concepts/cdc#virtual-timestamps). По умолчанию выключено.
 * `RETENTION_PERIOD` — [время хранения записей](../../../../concepts/cdc#retention-period). Тип значения — `Interval`, значение по умолчанию — 24 часа (`Interval('PT24H')`).