Improved CDC docs YCDOCS-5205

ref:ad784a1ff250541b7c957b3f45d342899f7a7354

6 files changed, 53 insertions, 85 deletions

diff --git a/ydb/docs/ru/core/concepts/_includes/cdc/processing.md b/ydb/docs/ru/core/concepts/_includes/cdc/processing.md
deleted file mode 100644
index ffc1cba18d1..00000000000
--- a/ydb/docs/ru/core/concepts/_includes/cdc/processing.md
+++ /dev/null
@@ -1,34 +0,0 @@
-## Чтение и обработка данных
-
-Записи потока изменений доступны для чтения по протоколу персистентных очередей. Ниже приведён фрагмент кода:
-
-```c++
-// Create client
-TPersQueueClient client(driver, TPersQueueClientSettings().Database("/path/to/database"));
-
-// Add consumer
-client.AddReadRule("/path/to/table/feed_name", TAddReadRuleSettings()
-    .ReadRule(TReadRuleSettings().ConsumerName("consumer_name")));
-
-// Create read session
-auto reader = client.CreateReadSession(TReadSessionSettings()
-    .AppendTopics(TString("/path/to/table/feed_name"))
-    .ConsumerName("consumer_name")
-);
-
-// Read records
-while (true) {
-    auto ev = reader->GetEvent(true);
-    if (auto* data = std::get_if<TReadSessionEvent::TDataReceivedEvent>(&*ev)) {
-        for (const auto& item : data->GetMessages()) {
-            // Process record
-        }
-    } else if (auto* create = std::get_if<TReadSessionEvent::TCreatePartitionStreamEvent>(&*ev)) {
-        create->Confirm();
-    } else if (auto* destroy = std::get_if<TReadSessionEvent::TDestroyPartitionStreamEvent>(&*ev)) {
-        destroy->Confirm();
-    } else if (std::get_if<TSessionClosedEvent>(&*ev)) {
-        break;
-    }
-}
-```
diff --git a/ydb/docs/ru/core/concepts/_includes/cdc/record_structure.md b/ydb/docs/ru/core/concepts/_includes/cdc/record_structure.md
new file mode 100644
index 00000000000..c9a718d9a7f
--- /dev/null
+++ b/ydb/docs/ru/core/concepts/_includes/cdc/record_structure.md
@@ -0,0 +1,38 @@
+## Структура записи {#record-structure}
+
+В зависимости от [параметров потока](../../../yql/reference/syntax/alter_table.md#changefeed-options) структура записи может отличаться.
+
+Запись в формате json будет иметь следующую структуру:
+```json
+{
+    "key": [<key components>],
+    "update": {<columns>},
+    "erase": {},
+    "newImage": {<columns>},
+    "oldImage": {<columns>}
+}
+```
+Где `<key components>` — массив значений компонент первичного ключа, а `<columns>` — словарь из названий столбцов (ключ) и их значений (значение). Например:
+```json
+{
+    "key": [1, "one"],
+    "update": {
+        "payload": "lorem ipsum",
+        "date": "2022-02-22"
+    }
+}
+```
+
+В некоторых режимах часть ключей может быть опущена:
+
+| Ключ | `KEYS_ONLY` | `UPDATES` | `NEW_IMAGE` | `OLD_IMAGE` | `NEW_AND_OLD_IMAGES` |
+| ---- | ----------- | --------- | ----------- | ----------- | -------------------- |
+| `"key"` | + | + | + | + | + |
+| `"update"` | пустой | + | пустой | пустой | пустой |
+| `"erase"` | пустой | пустой | пустой | пустой | пустой |
+| `"newImage"` | - | - | + | - | + |
+| `"oldImage"` | - | - | - | + | + |
+
+Как видно, вне зависимости от режима в записи всегда указываются:
+* Значения компонент первичного ключа таблицы (`"key"`).
+* Признак изменения (`"update"` или `"erase"`).
diff --git a/ydb/docs/ru/core/concepts/_includes/cdc/settings.md b/ydb/docs/ru/core/concepts/_includes/cdc/settings.md
deleted file mode 100644
index 321afa958bb..00000000000
--- a/ydb/docs/ru/core/concepts/_includes/cdc/settings.md
+++ /dev/null
@@ -1,43 +0,0 @@
-## Параметры {#settings}
-
-* `MODE`. Режим работы потока. Указывает, что именно будет записано в поток при каждом изменении данных в таблице.
-* `FORMAT`. Формат данных, в котором будут записаны данные в поток.
-
-### Режимы работы {#modes}
-
-{% note info %}
-
-Вне зависимости от выбранного режима в поток всегда записываются:
-  * Значения компонент первичного ключа таблицы.
-  * Признак изменения (обновление, удаление).
-
-{% endnote %}
-
-* `KEYS_ONLY`. Будут записаны только компоненты первичного ключа и признак изменения.
-* `UPDATES`. Будут записаны значения изменившихся столбцов, получившиеся в результате изменения.
-* `NEW_IMAGE`. Будут записаны значения всех столбцов, получившиеся в результате изменения.
-* `OLD_IMAGE`. Будут записаны значения всех столбцов, предшествующие изменению.
-* `NEW_AND_OLD_IMAGES`. Комбинация режимов `NEW_IMAGE` и `OLD_IMAGE` — будут записаны значения всех столбцов до и в результате изменения.
-
-### Форматы данных {#formats}
-
-* `JSON`. Структура записи:
-  ```json
-  {
-      "key": [<key components>],
-      "update": {<columns>},
-      "erase": {/* empty */},
-      "newImage": {<columns>},
-      "oldImage": {<columns>}
-  }
-  ```
-  Где `<key components>` — значения компонент первичного ключа, а `<columns>` — словарь из названий столбцов (ключ) и их значений (значение). Например:
-  ```json
-  {
-      "key": [1, "one"],
-      "update": {
-          "payload": "lorem ipsum",
-          "date": "2022-02-22"
-      }
-  }
-  ```
diff --git a/ydb/docs/ru/core/concepts/_includes/cdc/using.md b/ydb/docs/ru/core/concepts/_includes/cdc/using.md
index 12057ec0a2d..537697992a5 100644
--- a/ydb/docs/ru/core/concepts/_includes/cdc/using.md
+++ b/ydb/docs/ru/core/concepts/_includes/cdc/using.md
@@ -1,6 +1,3 @@
 ## Создание и удаление Changefeed {#ddl}
 
-Changefeed может быть:
-* Добавлен к существующей таблице командой YQL [`ALTER TABLE`](../../../yql/reference/syntax/alter_table.md#changefeed).
-* Удален у существующей таблицы командой YQL [`ALTER TABLE`](../../../yql/reference/syntax/alter_table.md#changefeed).
-* Удален вместе с таблицей командой YQL [`DROP TABLE`](../../../yql/reference/syntax/drop_table.md) или командой YDB CLI `table drop`.
+Changefeed может быть добавлен к существующей таблице или удален директивами [ADD CHANGEFEED и DROP CHANGEFEED](../../../yql/reference/syntax/alter_table.md#changefeed) операции YQL `ALTER TABLE`. При удалении таблицы добавленный к ней changefeed также будет удален.
diff --git a/ydb/docs/ru/core/concepts/cdc.md b/ydb/docs/ru/core/concepts/cdc.md
index 8649f87e6e1..7f6c264904e 100644
--- a/ydb/docs/ru/core/concepts/cdc.md
+++ b/ydb/docs/ru/core/concepts/cdc.md
@@ -2,8 +2,6 @@
 
 {% include [Guarantees](_includes/cdc/guarantees.md) %}
 
-{% include [Settings](_includes/cdc/settings.md) %}
+{% include [Settings](_includes/cdc/record_structure.md) %}
 
 {% include [Using](_includes/cdc/using.md) %}
-
-{% include [Processing](_includes/cdc/processing.md) %}
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 b773b7e25b0..2c7fe12cfdd 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
@@ -47,8 +47,20 @@ ALTER TABLE `series` DROP INDEX `title_index`;
 {% if feature_changefeed %}
 ## Добавление или удаление Changefeed {#changefeed}
 
-```ADD CHANGEFEED <name> WITH (option = value[, ...])``` — добавляет [changefeed](../../../../concepts/cdc) с указанным именем и параметрами. Могут быть указаны все параметры, описанные в разделе [Change Data Capture (CDC) — Параметры](../../../../concepts/cdc#settings). Приведенный ниже код добавит changefeed с именем ```updates_feed```, в который будут выгружаться значения изменившихся столбцов таблицы в формате json.
+```ADD CHANGEFEED <name> WITH (option = value[, ...])``` — добавляет [changefeed](../../../../concepts/cdc) с указанным именем и параметрами.
 
+### Параметры Changefeed {#changefeed-options}
+
+* `MODE`. Режим работы. Указывает, что именно будет записано в changefeed при каждом изменении данных в таблице.
+  * `KEYS_ONLY`. Будут записаны только компоненты первичного ключа и признак изменения.
+  * `UPDATES`. Будут записаны значения изменившихся столбцов, получившиеся в результате изменения.
+  * `NEW_IMAGE`. Будут записаны значения всех столбцов, получившиеся в результате изменения.
+  * `OLD_IMAGE`. Будут записаны значения всех столбцов, предшествующие изменению.
+  * `NEW_AND_OLD_IMAGES`. Комбинация режимов `NEW_IMAGE` и `OLD_IMAGE` — будут записаны значения всех столбцов *до* и *в результате* изменения.
+* `FORMAT`. Формат данных, в котором будут записаны данные.
+  * `JSON`. Структура записи приведена на странице [описания changefeed](../../../../concepts/cdc#record-structure).
+
+Приведенный ниже код добавит changefeed с именем ```updates_feed```, в который будут выгружаться значения изменившихся столбцов таблицы в формате json.
 ```sql
 ALTER TABLE `series` ADD CHANGEFEED `updates_feed` WITH (
     FORMAT = 'JSON',