Virtual timestamps

2 files changed, 41 insertions, 1 deletions

diff --git a/ydb/docs/ru/core/concepts/cdc.md b/ydb/docs/ru/core/concepts/cdc.md
index 3c9e54c3dba..ec62343b01f 100644
--- a/ydb/docs/ru/core/concepts/cdc.md
+++ b/ydb/docs/ru/core/concepts/cdc.md
@@ -19,6 +19,21 @@ Change Data Capture (CDC) обеспечивает захват изменени
 
   Таким образом, добавление строки является частным случаем обновления, и в потоке изменений запись о добавлении строки будет выглядеть аналогично записи об обновлении.
 
+## Виртуальные метки времени {#virtual-timestamps}
+
+Все изменения в таблицах {{ ydb-short-name }} упорядочены в соответствии с порядком выполнения транзакций. Каждое изменение маркируется виртуальной меткой времени, являющейся кортежем из двух элементов:
+
+1. Глобального времени координатора.
+2. Уникального идентификатора транзакции.
+
+Используя эти метки, можно упорядочить записи из разных партиций топика относительного друг друга или использовать их для фильтрации (например, чтобы исключить записи о старых изменениях).
+
+{% note info %}
+
+По умолчанию виртуальные метки времени не выгружаются в поток изменений. Для их включения используйте [соответствующий параметр](../yql/reference/syntax/alter_table.md#changefeed-options) при создании потока.
+
+{% endnote %}
+
 ## Структура записи {#record-structure}
 
 В зависимости от [параметров потока](../yql/reference/syntax/alter_table.md#changefeed-options) структура записи может отличаться.
@@ -31,7 +46,8 @@ Change Data Capture (CDC) обеспечивает захват изменени
     "update": {<columns>},
     "erase": {},
     "newImage": {<columns>},
-    "oldImage": {<columns>}
+    "oldImage": {<columns>},
+    "ts": [<step>, <txId>]
 }
 ```
 
@@ -40,6 +56,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`).
 
 >Например, запись об обновлении в режиме `UPDATES`:
 >
@@ -78,6 +95,18 @@ Change Data Capture (CDC) обеспечивает захват изменени
 >    }
 >}
 >```
+>
+>Запись с виртуальными метками времени:
+>```json
+>{
+>    "key": [1],
+>    "update": {
+>        "created": "2022-12-12T00:00:00.000000Z",
+>        "customer": "Name123"
+>    },
+>    "ts": [1670792400, 562949953607163]
+>}
+>```
 
 {% note info %}
 
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 100b4ca438b..eebe240a6be 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
@@ -64,6 +64,7 @@ ALTER TABLE `series` DROP INDEX `title_index`;
   * `NEW_AND_OLD_IMAGES` - комбинация режимов `NEW_IMAGE` и `OLD_IMAGE`. Будут записаны значения всех столбцов _до_ и _в результате_ изменения.
 * `FORMAT` — формат данных, в котором будут записаны данные.
   * `JSON` — структура записи приведена на странице [описания changefeed](../../../../concepts/cdc#record-structure).
+* `VIRTUAL_TIMESTAMPS` — включение-выключение [виртуальных меток времени](../../../../concepts/cdc#virtual-timestamps). По умолчанию выключено.
 * `RETENTION_PERIOD` — [время хранения записей](../../../../concepts/cdc#retention-period). Тип значения — `Interval`, значение по умолчанию — 24 часа (`Interval('PT24H')`).
 
 Приведенный ниже код добавит поток изменений с именем `updates_feed`, в который будут выгружаться значения изменившихся столбцов таблицы в формате JSON:
@@ -85,6 +86,16 @@ ALTER TABLE `series` ADD CHANGEFEED `updates_feed` WITH (
 );
 ```
 
+Пример создания потока изменений с включенными виртуальными метками времени:
+
+```sql
+ALTER TABLE `series` ADD CHANGEFEED `updates_feed` WITH (
+    FORMAT = 'JSON',
+    MODE = 'UPDATES',
+    VIRTUAL_TIMESTAMPS = TRUE
+);
+```
+
 `DROP CHANGEFEED` — удаляет поток изменений с указанным именем. Приведенный ниже код удалит changefeed с именем `updates_feed`:
 
 ```sql