CDC docs YCDOCS-5205

ref:a0a4fb6eca6eacf049749d290a70188f4bb1449c

9 files changed, 127 insertions, 2 deletions

diff --git a/ydb/docs/presets.yaml b/ydb/docs/presets.yaml
index 9f8785e595a..90581c0af6d 100644
--- a/ydb/docs/presets.yaml
+++ b/ydb/docs/presets.yaml
@@ -5,6 +5,7 @@ default:
   ydb: true
   example_cluster: ydbtest
   feature_secondary_index: true 
+  feature_changefeed: true 
   feature_replace: true
   feature_upsert: true
   feature_join: true
@@ -30,4 +31,4 @@ default:
   k8s: Kubernetes
   oss: true
 
-  corporate-paste: https://www.paste.example.com
\ No newline at end of file
+  corporate-paste: https://www.paste.example.com
diff --git a/ydb/docs/ru/core/concepts/_includes/cdc/guarantees.md b/ydb/docs/ru/core/concepts/_includes/cdc/guarantees.md
new file mode 100644
index 00000000000..4bea080d64d
--- /dev/null
+++ b/ydb/docs/ru/core/concepts/_includes/cdc/guarantees.md
@@ -0,0 +1,6 @@
+## Гарантии {#guarantees}
+
+* Изменения доставляются в том же порядке, в котором они происходили в таблице.
+* Каждое изменение доставляется ровно один раз (exactly-once семантика).
+* Записи об изменении шардированы между партициями персистентной очереди по первичному ключу.
+* Изменения по одному и тому же первичному ключу попадают в одну и ту же партицию персистентной очереди.
diff --git a/ydb/docs/ru/core/concepts/_includes/cdc/intro.md b/ydb/docs/ru/core/concepts/_includes/cdc/intro.md
new file mode 100644
index 00000000000..d3d17f5618e
--- /dev/null
+++ b/ydb/docs/ru/core/concepts/_includes/cdc/intro.md
@@ -0,0 +1,5 @@
+# Change Data Capture (CDC)
+
+Change Data Capture (CDC) обеспечивает захват изменений строк таблицы {{ ydb-short-name }}, формирует из них *поток изменений* (*changefeed*), записывает в распределенное хранилище и предоставляет доступ к этим записям для дальнейшей обработки. В качестве распределенного хранилища используется [персистентная очередь](../../datamodel.md#persistent-queue), которая позволяет эффективно хранить лог изменений таблицы.
+
+Когда в таблице добавляется, обновляется или удаляется строка, CDC формирует запись о произошедшем изменении с указанием [первичного ключа](../../datamodel.md#table) строки и пишет её в соответствующую данному ключу партицию персистентной очереди.
diff --git a/ydb/docs/ru/core/concepts/_includes/cdc/processing.md b/ydb/docs/ru/core/concepts/_includes/cdc/processing.md
new file mode 100644
index 00000000000..ffc1cba18d1
--- /dev/null
+++ b/ydb/docs/ru/core/concepts/_includes/cdc/processing.md
@@ -0,0 +1,34 @@
+## Чтение и обработка данных
+
+Записи потока изменений доступны для чтения по протоколу персистентных очередей. Ниже приведён фрагмент кода:
+
+```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/settings.md b/ydb/docs/ru/core/concepts/_includes/cdc/settings.md
new file mode 100644
index 00000000000..321afa958bb
--- /dev/null
+++ b/ydb/docs/ru/core/concepts/_includes/cdc/settings.md
@@ -0,0 +1,43 @@
+## Параметры {#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
new file mode 100644
index 00000000000..12057ec0a2d
--- /dev/null
+++ b/ydb/docs/ru/core/concepts/_includes/cdc/using.md
@@ -0,0 +1,6 @@
+## Создание и удаление 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`.
diff --git a/ydb/docs/ru/core/concepts/cdc.md b/ydb/docs/ru/core/concepts/cdc.md
new file mode 100644
index 00000000000..8649f87e6e1
--- /dev/null
+++ b/ydb/docs/ru/core/concepts/cdc.md
@@ -0,0 +1,9 @@
+{% include [Intro](_includes/cdc/intro.md) %}
+
+{% include [Guarantees](_includes/cdc/guarantees.md) %}
+
+{% include [Settings](_includes/cdc/settings.md) %}
+
+{% include [Using](_includes/cdc/using.md) %}
+
+{% include [Processing](_includes/cdc/processing.md) %}
diff --git a/ydb/docs/ru/core/concepts/toc_i.yaml b/ydb/docs/ru/core/concepts/toc_i.yaml
index 76991568802..1125a780bdb 100644
--- a/ydb/docs/ru/core/concepts/toc_i.yaml
+++ b/ydb/docs/ru/core/concepts/toc_i.yaml
@@ -7,6 +7,7 @@ items:
 - { name: Типы данных,                            href: datatypes.md, hidden: true } # Deprecated
 - { name: Транзакции,                             href: transactions.md }
 - { name: Вторичные индексы,                      href: secondary_indexes.md }
+- { name: Change Data Capture (CDC),              href: cdc.md }
 - { name: Time to Live (TTL),                     href: ttl.md }
 - { name: Скан запросы,                           href: scan_query.md }
 - { name: Ограничения базы данных,                href: limits-ydb.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 87254812086..b773b7e25b0 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
@@ -43,6 +43,26 @@ ALTER TABLE `series` ADD INDEX `title_index` GLOBAL ON (`title`);
 ALTER TABLE `series` DROP INDEX `title_index`;
 ```
 {% endif %}
+
+{% 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.
+
+```sql
+ALTER TABLE `series` ADD CHANGEFEED `updates_feed` WITH (
+    FORMAT = 'JSON',
+    MODE = 'UPDATES'
+);
+```
+
+```DROP CHANGEFEED``` — удаляет changefeed с указанным именем. Приведенный ниже код удалит changefeed с именем ```updates_feed```.
+
+```sql
+ALTER TABLE `series` DROP CHANGEFEED `updates_feed`;
+```
+{% endif %}
+
 {% if feature_map_tables %}
 
 ## Переименование таблицы {#rename}
@@ -133,4 +153,4 @@ ALTER TABLE table_name RESET (key);
 ```sql
 ALTER TABLE series RESET (TTL);
 ```
-{% endif %}
\ No newline at end of file
+{% endif %}