DEBEZIUM_JSON (#7052)

CyberROFL · web-flow · commit 3c55951e2856 · 2024-07-29T12:21:43.000+03:00
diff --git a/ydb/docs/en/core/concepts/cdc.md b/ydb/docs/en/core/concepts/cdc.md
@@ -78,7 +78,7 @@ A [JSON](https://en.wikipedia.org/wiki/JSON) record has the following structure:
 * `erase`: Erase flag. Present if a record matches the erase operation.
 * `newImage`: Row snapshot that results from its being changed. Present in `NEW_IMAGE` and `NEW_AND_OLD_IMAGES` modes. Contains column names and values.
 * `oldImage`: Row snapshot before the change. Present in `OLD_IMAGE` and `NEW_AND_OLD_IMAGES` modes. Contains column names and values.
-* `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`).
+* `ts`: [Virtual timestamp](#virtual-timestamps). Present if the `VIRTUAL_TIMESTAMPS` setting is enabled. Contains the value of the global coordinator time (`step`) and the unique transaction ID (`txId`).
 
 > Sample record of an update in `UPDATES` mode:
 >
@@ -155,63 +155,52 @@ 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>,
+            "version": <version>,
             "ts_ms": <ts_ms>,
-            "txId": <txId>
+            "step": <step>,
+            "txId": <txId>,
+            "snapshot": <bool>
         }
     }
 }
 ```
 
 * `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.
+  * `c` — create. Applicable only in `NEW_AND_OLD_IMAGES` mode.
+  * `u` — update.
+  * `d` — delete.
+  * `r` — read from [snapshot](#initial-scan).
+* `before`: Row snapshot before the change. Present in `OLD_IMAGE` and `NEW_AND_OLD_IMAGES` modes. Contains column names and values.
+* `after`: Row snapshot after the change. Present in `NEW_IMAGE` and `NEW_AND_OLD_IMAGES` modes. Contains column names and values.
 * `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`.
+  * `connector`: Connector name. Current name is `ydb`.
+  * `version`: Connector version that was used to generate the record. Current version is `1.0.0`.
   * `ts_ms`: Approximate time when the change was applied, in milliseconds.
-  * `txId`: Unique transaction ID.
+  * `step`: Global coordinator time. Part of the [virtual timestamp](#virtual-timestamps).
+  * `txId`: Unique transaction ID. Part of the [virtual timestamp](#virtual-timestamps).
+  * `snapshot`: Whether the event is part of a snapshot.
 
-{% note warning %}
-
-Currently debezium json format doesn't have `schema` field. Other Debezium connectors have it.
+When reading using Kafka API, the Debezium-compatible primary key of the modified row is specified as the message key:
 
-{% 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": {<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 %}
+* `payload`: Key of a row that was changed. Contains names and values of the columns that are components of the primary key.
 
 ## Record retention period {#retention-period}
 
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
@@ -140,9 +140,9 @@ ALTER TABLE `series` RENAME INDEX `title_index` TO `title_index_new`;
    * `NEW_AND_OLD_IMAGES`: A combination of `NEW_IMAGE` and `OLD_IMAGE` modes. Any column values _prior to_ and _resulting from_ updates are written.
 * `FORMAT`: Data write format.
    * `JSON`: Write data in [JSON](../../../../concepts/cdc.md#json-record-structure) format.
+   * `DEBEZIUM_JSON`: Write data in the [Debezium-like JSON format](../../../../concepts/cdc.md#debezium-json-record-structure).
 {% if audience == "tech" %}
    * `DYNAMODB_STREAMS_JSON`: Write data in the [JSON format compatible with Amazon DynamoDB Streams](../../../../concepts/cdc.md#dynamodb-streams-json-record-structure).
-   * `DEBEZIUM_JSON`: Write data in the [Debezium-like JSON format](../../../../concepts/cdc.md#debezium-json-record-structure).
 {% endif %}
 * `VIRTUAL_TIMESTAMPS`: Enabling/disabling [virtual timestamps](../../../../concepts/cdc.md#virtual-timestamps). Disabled by default.
 * `RETENTION_PERIOD`: [Record retention period](../../../../concepts/cdc.md#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
@@ -78,7 +78,7 @@ Change Data Capture (CDC) обеспечивает захват изменени
 * `erase` — признак удаления. Присутствует, если запись соответствует операции удаления.
 * `newImage` — снимок состояния строки, получившегося в результате изменения. Присутствует в режимах `NEW_IMAGE` и `NEW_AND_OLD_IMAGES`. Содержит названия и значения столбцов.
 * `oldImage` — снимок состояния строки, предшествовавшего изменению. Присутствует в режимах `OLD_IMAGE` и `NEW_AND_OLD_IMAGES`. Содержит названия и значения столбцов.
-* `ts` — виртуальная метка времени. Присутствует, если включена настройка `VIRTUAL_TIMESTAMPS`. Содержит значение глобального времени координатора (`step`) и уникальный идентификатор транзакции (`txId`).
+* `ts` — [виртуальная метка времени](#virtual-timestamps). Присутствует, если включена настройка `VIRTUAL_TIMESTAMPS`. Содержит значение глобального времени координатора (`step`) и уникальный идентификатор транзакции (`txId`).
 
 >Например, запись об обновлении в режиме `UPDATES`:
 >
@@ -155,63 +155,52 @@ 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>,
+            "version": <version>,
             "ts_ms": <ts_ms>,
-            "txId": <txId>
+            "step": <step>,
+            "txId": <txId>,
+            "snapshot": <bool>
         }
     }
 }
 ```
 
-* `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 коннекторы это поддерживают.
+* `op` — операция, которая была произведена над строкой в таблице:
+  * `c` — вставка. Допустимо только в режиме `NEW_AND_OLD_IMAGES`.
+  * `u` — обновление.
+  * `d` — удаление.
+  * `r` — чтение из [снапшота](#initial-scan).
+* `before` — снимок состояния строки, предшествовавшего изменению. Присутствует в режимах `OLD_IMAGE` и `NEW_AND_OLD_IMAGES`. Содержит названия и значения столбцов.
+* `after` — снимок состояния строки, получившегося в результате изменения. Присутствует в режимах `NEW_IMAGE` и `NEW_AND_OLD_IMAGES`. Содержит названия и значения столбцов.
+* `source` — метаданные записи.
+  * `connector` — название коннектора. Текущее название: `ydb`.
+  * `version` — версия коннектора, используемая для генерации записи. Текущая версия: `1.0.0`.
+  * `ts_ms` — примерное время применения изменения в {{ ydb-short-name }}, в миллисекундах.
+  * `step` — глобальное время координатора. Компонент [виртуальных меток времени](#virtual-timestamps).
+  * `txId` — уникальный идентификатор транзакции. Компонент [виртуальных меток времени](#virtual-timestamps).
+  * `snapshot` — признак чтения из снапшота.
+
+При чтении с использованием [Kafka API](../reference/kafka-api/index.md) в качестве ключа сообщения указывается Debezium-совместимый первичный ключ измененной строки:
 
-{% endnote %}
-
-При использовании kafka API для чтения топика, вы увидите Debezium-совместимый kafka ключ в следующем формате:
 ```json
 {
-    "payload": {
-        <columns>
-    }
+    "payload": {<columns>}
 }
 ```
 
-* `payload`: Первичный ключ строки, которая была изменена
-
-Информацию о том, как это сохранено в сообщении, и как можно получить информацию о ключе без использования kafka API, читайте в [документации об интеграции с kafka](../reference/kafka-api/index.md)
-
-{% endif %}
+* `payload` — первичный ключ строки, которая была изменена. Содержит названия и значения столбцов, являющихся компонентами первичного ключа.
 
 ## Время хранения записей {#retention-period}
 
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
@@ -140,9 +140,9 @@ ALTER TABLE `series` RENAME INDEX `title_index` TO `title_index_new`;
   * `NEW_AND_OLD_IMAGES` - комбинация режимов `NEW_IMAGE` и `OLD_IMAGE`. Будут записаны значения всех столбцов _до_ и _в результате_ изменения.
 * `FORMAT` — формат данных, в котором будут записаны данные.
   * `JSON` — записывать данные в формате {% if oss == "true" %}[JSON](../../../../concepts/cdc.md#json-record-structure){% else %}JSON{% endif %}.
+  * `DEBEZIUM_JSON` — записывать данные в {% if oss == "true" %}[JSON-формате, аналогичном Debezium формату](../../../../concepts/cdc.md#debezium-json-record-structure){% else %}JSON-формате, аналогичном Debezium формату{% endif %}.
 {% if audience == "tech" %}
   * `DYNAMODB_STREAMS_JSON` — записывать данные в {% if oss == "true" %}[JSON-формате, совместимом с Amazon DynamoDB Streams](../../../../concepts/cdc#dynamodb-streams-json-record-structure){% else %}JSON-формате, совместимом с Amazon DynamoDB Streams{% endif %}.
-  * `DEBEZIUM_JSON` — записывать данные в {% if oss == "true" %}[JSON-формате, аналогичном Debezium формату](../../../../concepts/cdc.md#debezium-json-record-structure){% else %}JSON-формате, аналогичном Debezium формату{% endif %}.
 {% endif %}
 * `VIRTUAL_TIMESTAMPS` — включение-выключение {% if oss == "true" %}[виртуальных меток времени](../../../../concepts/cdc.md#virtual-timestamps){% else %}виртуальных меток времени{% endif %}. По умолчанию выключено.
 * `RETENTION_PERIOD` — {% if oss == "true" %}[время хранения записей](../../../../concepts/cdc.md#retention-period){% else %}время хранения записей{% endif %}. Тип значения — `Interval`, значение по умолчанию — 24 часа (`Interval('PT24H')`).
