PR from branch users/alexv-smirnov/fix/-topics-write-cli-docs

ydb docs topic write

ydb docs topic read

10 files changed, 431 insertions, 298 deletions

diff --git a/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md b/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md
index 353fb2f4067..1f0645562d1 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md
@@ -60,12 +60,19 @@ table drop | Удаление таблицы
 [table query execute](../commands/query.md) | Исполнение YQL-запроса
 [table query explain](../commands/explain-plan.md) | План исполнения YQL-запроса
 [table readtable](../commands/readtable.md) | Потоковое чтение таблицы
-table ttl drop  | Удаление параметров TTL
-table ttl set  | Установка параметров TTL
+table ttl drop | Удаление параметров TTL
+table ttl set | Установка параметров TTL
 tools copy | Копирование таблиц
 [tools dump](../export_import/tools_dump.md) | Выгрузка директории или таблицы в файловую систему
 [tools rename](../commands/tools/rename.md) | Переименование таблиц
 [tools restore](../export_import/tools_restore.md) | Восстановление из файловой системы
+[topic alter](../topic/scheme.md#alter) | Модификация параметров топика и перечня читателей
+[topic consumer add](../topic/scheme.md#consumer-add) | Добавление читателя в топик
+[topic consumer drop](../topic/scheme.md#consumer-drop) | Удаление читателя из топика
+[topic create](../topic/scheme.md#create) | Создание топика
+[topic drop](../topic/scheme.md#drop) | Удаление топика
+[topic read](../topic/read.md) | Чтение сообщений из топика
+[topic write](../topic/write.md) | Запись сообщений в топик
 {% if ydb-cli == "ydb" %}
 [update](../commands/service.md) | Обновление {{ ydb-short-name }} CLI
 [version](../commands/service.md) | Вывод информации о версии {{ ydb-short-name }} CLI
diff --git a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
index 53bc06a6005..1c754ba94df 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
+++ b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
@@ -1,7 +1,7 @@
 items:
   - name: Установка
     href: install.md
-  - name: Структура команд YDB CLI
+  - name: Все команды по алфавиту
     href: commands.md
   - name: Сервисные команды
     href: commands/service.md
@@ -34,7 +34,7 @@ items:
   - name: Загрузка и выгрузка данных
     include: { mode: link, path: export_import/toc_p.yaml }
   - name: Работа с топиками
-    href: topic.md
+    include: { mode: link, path: topic/toc_i.yaml }
 #  - name: Утилиты
 #    items:
     # - name: Копирование таблиц
diff --git a/ydb/docs/ru/core/reference/ydb-cli/topic.md b/ydb/docs/ru/core/reference/ydb-cli/topic.md
deleted file mode 100644
index 8539cb8c98c..00000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/topic.md
+++ /dev/null
@@ -1,293 +0,0 @@
-# Работа с топиками
-
-С помощью подкоманды `topic` вы можете создать, изменить или удалить [топик](../../concepts/topic.md), а также создать или удалить [читателя](../../concepts/topic.md#consumer).
-
-В примерах используется профиль `db1`, подробнее смотрите в [{#T}](../../getting_started/cli.md#profile).
-
-## Создание топика {#topic-create}
-
-С помощью подкоманды `topic create` вы можете создать новый топик.
-
-Общий вид команды:
-
-```bash
-{{ ydb-cli }} [global options...] topic create [options...] <topic-path>
-```
-
-* `global options` — [глобальные параметры](commands/global-options.md).
-* `options` — [параметры подкоманды](#options).
-* `topic-path` — путь топика.
-
-Посмотрите описание команды создания топика:
-
-```bash
-{{ ydb-cli }} topic create --help
-```
-
-### Параметры подкоманды {#topic-create-options}
-
-Имя | Описание
----|---
-`--partitions-count VAL`| Количество [партиций](../../concepts/topic.md#partitioning) топика.<br>Значение по умолчанию — `1`.
-`--retention-period-hours VAL` | Время хранения данных в топике, задается в часах.<br>Значение по умолчанию — `18`.
-`--supported-codecs STRING` | Поддерживаемые метод сжатия данных.<br>Значение по умолчанию — `raw,zstd,gzip,lzop`.<br>Возможные значения:<ul><li>`RAW` — без сжатия;</li><li>`ZSTD` — сжатие [zstd](https://ru.wikipedia.org/wiki/Zstandard);</li><li>`GZIP` — сжатие [gzip](https://ru.wikipedia.org/wiki/Gzip);</li><li>`LZOP` — сжатие [lzop](https://ru.wikipedia.org/wiki/Lzop).</li></ul>
-
-### Примеры {#topic-create-examples}
-
-Создайте топик с 2 партициями, методами сжатия `RAW` и `GZIP`, временем хранения сообщений 2 часа и путем `my-topic`:
-
-```bash
-{{ ydb-cli }} -p db1 topic create \
-  --partitions-count 2 \
-  --supported-codecs raw,gzip \
-  --retention-period-hours 2 \
-  my-topic
-```
-
-Посмотрите параметры созданного топика:
-
-```bash
-{{ ydb-cli }} -p db1 scheme describe my-topic
-```
-
-Результат:
-
-```text
-RetentionPeriod: 2 hours
-PartitionsCount: 2
-SupportedCodecs: RAW, GZIP
-```
-
-## Изменение топика {#topic-alter}
-
-С помощью подкоманды `topic alter` вы можете изменить [созданный ранее](#topic-create) топик.
-
-Общий вид команды:
-
-```bash
-{{ ydb-cli }} [global options...] topic alter [options...] <topic-path>
-```
-
-* `global options` — [глобальные параметры](commands/global-options.md).
-* `options` — [параметры подкоманды](#options).
-* `topic-path` — путь топика.
-
-Посмотрите описание команды изменения топика:
-
-```bash
-{{ ydb-cli }} topic alter --help
-```
-
-### Параметры подкоманды {#topic-alter-options}
-
-Имя | Описание
----|---
-`--partitions-count VAL`| Количество [партиций](../../concepts/topic.md#partitioning) топика.<br>Значение по умолчанию — `1`.
-`--retention-period-hours VAL` | Время хранения данных в топике, задается в часах.<br>Значение по умолчанию — `18`.
-`--supported-codecs STRING` | Поддерживаемые метод сжатия данных.<br>Значение по умолчанию — `raw,zstd,gzip,lzop`.<br>Возможные значения:<ul><li>`RAW` — без сжатия;</li><li>`ZSTD` — сжатие [zstd](https://ru.wikipedia.org/wiki/Zstandard);</li><li>`GZIP` — сжатие [gzip](https://ru.wikipedia.org/wiki/Gzip);</li><li>`LZOP` — сжатие [lzop](https://ru.wikipedia.org/wiki/Lzop).</li></ul>
-
-### Примеры {#topic-alter-examples}
-
-Добавьте партицию и метод сжатия `lzop` [созданному ранее](#topic-create) топику:
-
-```bash
-{{ ydb-cli }} -p db1 topic alter \
-  --partitions-count 3 \
-  --supported-codecs raw,gzip,lzop \
-  my-topic
-```
-
-Убедитесь, что параметры топика изменились:
-
-```bash
-{{ ydb-cli }} -p db1 scheme describe my-topic
-```
-
-Результат:
-
-```text
-RetentionPeriod: 2 hours
-PartitionsCount: 3
-SupportedCodecs: RAW, GZIP, LZOP
-```
-
-## Удаление топика {#topic-drop}
-
-С помощью подкоманды `topic drop` вы можете удалить [созданный ранее](#topic-create) топик.
-
-Общий вид команды:
-
-```bash
-{{ ydb-cli }} [global options...] topic drop <topic-path>
-```
-
-* `global options` — [глобальные параметры](commands/global-options.md).
-* `topic-path` — путь топика.
-
-Посмотрите описание команды удаления топика:
-
-```bash
-{{ ydb-cli }} topic drop --help
-```
-
-### Примеры {#topic-drop-examples}
-
-Удалите [созданный ранее](#topic-create) топик:
-
-```bash
-{{ ydb-cli }} -p db1 topic drop my-topic
-```
-
-## Добавление читателя для топика {#consumer-add}
-
-С помощью подкоманды `topic consumer add` вы можете создать читателя для [созданного ранее](#topic-create) топика.
-
-Общий вид команды:
-
-```bash
-{{ ydb-cli }} [global options...] topic consumer add [options...] <topic-path>
-```
-
-* `global options` — [глобальные параметры](commands/global-options.md).
-* `options` — [параметры подкоманды](#options).
-* `topic-path` — путь топика.
-
-Посмотрите описание команды добавления читателя:
-
-```bash
-{{ ydb-cli }} topic consumer add --help
-```
-
-### Параметры подкоманды {#consumer-add-options}
-
-Имя | Описание
----|---
-`--consumer-name VAL` | Имя читателя, которого нужно создать.
-`--starting-message-timestamp VAL` | Время в формате [UNIX timestamp](https://ru.wikipedia.org/wiki/Unix-время). Чтение начнется с первого [сообщения](../../concepts/topic.md#message), полученного после указанного времени. Если время не задано, то чтение начнется с самой старого сообщения в топике.
-
-### Примеры {#consumer-add-examples}
-
-Создайте читателя с именем `my-consumer` для [созданного ранее](#topic-create) топика `my-topic`, чтение начнется с первого сообщения, полученного после 15 августа 2022 13:00:00 GMT:
-
-```bash
-{{ ydb-cli }} -p db1 topic consumer add \
-  --consumer-name my-consumer \
-  --starting-message-timestamp 1660568400 \
-  my-topic 
-```
-
-Убедитесь, что читатель создан:
-
-```bash
-{{ ydb-cli }} -p db1 scheme describe my-topic
-```
-
-Результат:
-
-```text
-RetentionPeriod: 2 hours
-PartitionsCount: 2
-SupportedCodecs: RAW, GZIP
-
-Consumers: 
-┌──────────────┬─────────────────┬───────────────────────────────┬───────────┐
-| ConsumerName | SupportedCodecs | ReadFrom                      | Important |
-├──────────────┼─────────────────┼───────────────────────────────┼───────────┤
-| my-consumer  | RAW, GZIP       | Mon, 15 Aug 2022 16:00:00 MSK | 0         |
-└──────────────┴─────────────────┴───────────────────────────────┴───────────┘
-```
-
-## Удаление читателя {#consumer-drop}
-
-С помощью подкоманды `topic consumer drop` вы можете удалить [созданного ранее](#consumer-add) читателя.
-
-Общий вид команды:
-
-```bash
-{{ ydb-cli }} [global options...] topic consumer drop [options...] <topic-path>
-```
-
-* `global options` — [глобальные параметры](commands/global-options.md).
-* `options` — [параметры подкоманды](#options).
-* `topic-path` — путь топика.
-
-Посмотрите описание команды удаления читателя:
-
-```bash
-{{ ydb-cli }} topic consumer drop --help
-```
-
-### Параметры подкоманды {#consumer-drop-options}
-
-Имя | Описание
----|---
-`--consumer-name VAL` | Имя читателя, которого нужно удалить.
-
-### Примеры {#consumer-drop-examples}
-
-Удалите [ранее созданного](#consumer-add) читателя с именем `my-consumer` для топика `my-topic`:
-
-```bash
-{{ ydb-cli }} -p db1 topic consumer drop \
-  --consumer-name my-consumer \
-  my-topic
-```
-
-## Чтение из топика {#topic-read}
-
-С помощью подкоманды `topic read` вы можете прочитать сообщения из топика.
-
-Перед чтением нужно [создать топик](#topic-create) и [добавить читателя](#consumer-add).
-
-Общий вид команды:
-
-```bash
-{{ ydb-cli }} [global options...] topic read [options...] <topic-path>
-```
-
-* `global options` — [глобальные параметры](commands/global-options.md).
-* `options` — [параметры подкоманды](#options).
-* `topic-path` — путь топика.
-
-Посмотрите описание команды чтения из топика:
-
-```bash
-{{ ydb-cli }} topic read --help
-```
-
-### Параметры подкоманды {#topic-read}
-
-Имя | Описание
----|---
-`-c VAL`, `--consumer-name VAL` | Имя читателя топика.
-`--format STRING` | Формат вывода.<br>Возможные значения:<ul><li>`pretty` — вывод в псевдографическую таблицу;</li><li>`newline-delimited` — в конце каждого сообщения выводится управляющий символ `0x0A`;</li><li>`concatenated` — вывод без разделителей.</li></ul>
-`-f VAL`, `--file VAL` | Записывать читаемые данные в указанный файл.<br>Если параметр не задан, то сообщения выводятся в `stdout`.
-`--idle-timeout VAL` | Максимальное время ожидания нового сообщения.<br>Если за время ожидания сообщения не поступают, чтение останавливается.<br>Значение по умолчанию — `1s` (1 секунда).
-`--commit VAL` | Отправка подтверждения обработки сообщений.<br>Значение по умолчанию — `true`.<br>Возможные значения: `true`, `false`.
-`--limit VAL` | Количество сообщений, которое нужно прочитать.<br>Значение по умолчанию — `0` (нет ограничений).
-`-w`, `--wait` | Бесконечно ожидать первого сообщения.<br>Если параметр не задан, то первое сообщение ожидается не более `--idle-timeout`.
-`--timestamp VAL` | Время в формате [UNIX timestamp](https://ru.wikipedia.org/wiki/Unix-время). Чтение начнется с первого [сообщения](../../concepts/topic.md#message), полученного после указанного времени.
-`--with-metadata-fields VAL` | Список [атрибутов сообщения](../../concepts/topic.md#message), значения которых нужно выводить.<br>Возможные значения:<ul><li>`write_time` — время записи сообщения на сервер в формате [UNIX timestamp](https://ru.wikipedia.org/wiki/Unix-время);</li><li>`meta` — метаданные сообщения;</li><li>`create_time` — время создания сообщения источником в формате [UNIX timestamp](https://ru.wikipedia.org/wiki/Unix-время);</li><li>`seq_no` — [порядковый номер](../../concepts/topic.md#seqno) сообщения;</li><li>`offset` — [порядковый номер сообщения внутри партиции](../../concepts/topic.md#offset);</li><li>`message_group_id` — [идентификатор группы сообщений](../../concepts/topic.md#producer-id);</li><li>`body` — тело сообщения.</li></ul>
-`--transform VAL` | Указать формат тела читаемого сообщения для преобразования.<br>Значение по умолчанию — `none`.<br>Возможные значения:<ul><li>`base64` — преобразовать в кодировку [Base64](https://ru.wikipedia.org/wiki/Base64);</li><li>`none` — не преобразовывать.</li></ul>
-
-### Примеры {#topic-read}
-
-Прочитайте через читателя `my-consumer` все сообщения из топика `my-topic` и выведите каждое в отдельной строке:
-
-```bash
-{{ ydb-cli }} topic read \
-  --consumer-name my-consumer \
-  --format newline-delimited \
-  my-topic
-```
-
-Следующая команда прочитает первые 10 сообщений топика `my-topic` через читателя `my-consumer` и выведет каждое в отдельной строке. Также перед выводом тело сообщения будет преобразовано в Base64:
-
-```bash
-{{ ydb-cli }} topic read \
-  --consumer-name my-consumer \
-  --format newline-delimited
-  --limit 10 \
-  --transform base64 \
-  my-topic
-```
diff --git a/ydb/docs/ru/core/reference/ydb-cli/topic/index.md b/ydb/docs/ru/core/reference/ydb-cli/topic/index.md
new file mode 100644
index 00000000000..80182da74ac
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/topic/index.md
@@ -0,0 +1,10 @@
+# Работа с топиками
+
+YDB CLI содержит набор команд, предназначенных для работы с [топиками](../../../concepts/topic.md).
+
+- [Управление схемой топиков](scheme.md)
+- [Чтение сообщений из топика](read.md)
+- [Запись сообщений в топик](write.md)
+- [Интеграция чтения и записи](integration.md)
+
+
diff --git a/ydb/docs/ru/core/reference/ydb-cli/topic/integration.md b/ydb/docs/ru/core/reference/ydb-cli/topic/integration.md
new file mode 100644
index 00000000000..04db92dd3de
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/topic/integration.md
@@ -0,0 +1,33 @@
+# Интеграция чтения и записи
+
+Возможности работы команд `topic read` и `topic write` со стандартными устройствами ввода/вывода, а также поддержка потокового режима на чтении, позволяет выстраивать полноценные сценарии интеграции с передачей сообщений между топиками и их преобразованиями. В данном разделе собраны несколько примеров подобных сценариев.
+
+* Перекладывание одного сообщения из `topic1` в базе данных `db1` в `topic2` в базе данных `db2`, с ожиданием его появления в топике-источнике
+  ```bash
+  {{ ydb-cli }} -p db1 topic read topic1 -c c1 -w | {{ ydb-cli }} -p db2 topic write topic2 
+  ```
+
+* Фоновая передача всех появляющихся однострочных сообщений в топике `topic1` в базе данных `db1`, в топик `topic2` в базе данных `db2`. Данный сценарий можно использовать в случае, если гарантируется отсутствие байтов `0x0A` (перевод строки) в исходных сообщениях.
+  ```bash
+  {{ ydb-cli }} -p db1 topic read topic1 -c c1 --format newline-delimited -w | \
+  {{ ydb-cli }} -p db2 topic write topic2 --format newline-delimited
+  ```
+
+* Фоновая передача точной бинарной копии всех появляющихся сообщений в топике `topic1` в базе данных `db1`, в топик `topic2` в базе данных `db2`, с использованием кодировки сообщений base64 на потоке передачи.
+  ```bash
+  {{ ydb-cli }} -p db1 topic read topic1 -c c1 --format newline-delimited -w --transform base64 | \
+  {{ ydb-cli }} -p db2 topic write topic2 --format newline-delimited --transform base64
+  ```
+
+* Передача ограниченного пакета однострочных сообщений с фильтрацией по подстроке `ERROR`
+  ```bash
+  {{ ydb-cli }} -p db1 topic read topic1 -c c1 --format newline-delimited | \
+  grep ERROR | \
+  {{ ydb-cli }} -p db2 topic write topic2 --format newline-delimited
+  ```
+
+* Запись результата исполнения YQL-запроса в виде сообщений в топик `topic1`
+  ```bash
+  {{ ydb-cli }} -p db1 yql -s "select * from series" --format json-unicode | \
+  {{ ydb-cli }} -p db1 topic write topic1 --format newline-delimited
+  ```
diff --git a/ydb/docs/ru/core/reference/ydb-cli/topic/read.md b/ydb/docs/ru/core/reference/ydb-cli/topic/read.md
new file mode 100644
index 00000000000..376b2567633
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/topic/read.md
@@ -0,0 +1,117 @@
+# Чтение из топика
+
+Командой `topic read` выполняется чтение сообщений из топика с выводом их в файл или в терминал командной строки: 
+
+```bash
+{{ ydb-cli }} [connection options] topic read <topic-path> --consumer-name STR \
+  [--format STR] [--wait] [--limit INT] \
+  [--transform STR] [--file STR] [--commit BOOL] \
+  [дополнительные параметры...] 
+```
+
+{% include [conn_options_ref.md](../commands/_includes/conn_options_ref.md) %}
+
+Поддерживается три режима работы команды:
+
+1. **Одно сообщение**. Из топика считывается не более одного сообщения.
+2. **Пакетный режим**. Сообщения из топика считываются до того момента, пока в топике не закончатся сообщения для обработки, или количество сообщений не превысит устанавливаемое обязательно ограничение.
+3. **Потоковый режим**. Сообщения из топика считываются по мере их появления, с ожиданием появления новых, до момента пока исполнение команды не будет прервано нажатием `Ctrl+C`, или количество сообщений не превысит опционально задаваемое ограничение.
+
+## Параметры {#options}
+
+### Обязательные параметры
+
+Имя | Описание
+---|---
+`<topic-path>` | Путь топика
+`-c VAL`, `--consumer-name VAL` | Имя читателя топика.<br>Чтение сообщений будет начато с текущей рабочей позиции (offset) для данного читателя (если не указан параметр `--timestamp`).<br>Текущая рабочая позиция будет передвигаться по мере чтения и вывода сообщений (если не указано значение параметра `--commit=false`). 
+
+### Основные опциональные параметры
+
+`--format STR`: Формат вывода
+
+- Задает правило оформления сообщений на выходе. Не все форматы могут работать в потоковом режиме.
+- Перечень поддерживаемых форматов:
+
+  Имя | Описание | Поддерживает<br>потоковый режим?
+  ---|---|---
+  `single-message`<br>(по умолчанию)|Вывод содержимого не более одного сообщения без оформления.|-|
+  `pretty`|Вывод в псевдографическую таблицу с колонками, содержащими метаинформацию о сообщениях. В колонке `body` выводится само сообщение.|Нет
+  `newline-delimited`|Вывод сообщений с добавлением после каждого сообщения разделителя - символа перевода строки `0x0A`|Да
+  `concatenated`|Вывод сообщений одного за другим без добавления какого-либо разделителя|Да 
+
+`--wait` (`-w`): Ожидание появления сообщений
+
+- Включает ожидание появления первого сообщения в топике. Если он не задан, и в топике нет сообщений для обработки, то исполнение команды будет завершено сразу после старта. Если он задан, то запущенная команда чтения будет ожидать появления первого сообщения для обработки.
+- Включает потоковый режим отбора для форматов, которые его поддерживают, иначе используется пакетный режим.
+
+`--limit INT`: Максимальное количество считываемых из топика сообщений
+
+- Значения по умолчанию и допустимые значения зависят от выбранного формата вывода:
+
+  Поддерживает ли формат<br>потоковый режим отбора | Значение лимита по умолчанию | Допустимые значения
+  ---|---|---
+  Нет|10|1-500
+  Да|0 (без ограничений)|0-500
+
+`--transform VAL`: Метод преобразования сообщений
+
+- Значение по умолчанию — `none`
+- Возможные значения:
+  `base64` — преобразовать в кодировку [Base64](https://ru.wikipedia.org/wiki/Base64)
+  `none` — не выполнять преобразований, передать на выход содержимое сообщения побайтово
+
+`--file VAL` (`-f VAL`): Записывать читаемые сообщения в указанный файл. Если параметр не задан, то сообщения выводятся в `stdout`.
+
+`--commit BOOL`: Подтверждение чтения. 
+
+1. Если установлено значение `true` (по умолчанию), то текущая рабочая позиция (offset) читателя в топике будет передвигаться по мере чтения сообщений из топика. 
+2. Возможные значения: `true`, `false`.
+
+### Другие опциональные параметры
+
+Имя | Описание
+---|---
+`--idle-timeout VAL` | Таймаут принятия решения о том что топик пуст, то есть новые сообщения для обработки отсутствуют. <br>Замеряется время с момента установки соединения при запуске команды, или получения последнего сообщения. Если в течение заданного таймаута с сервера не приходит новых сообщений, топик считается пустым.<br>Значение по умолчанию — `1s` (1 секунда).
+`--timestamp VAL` | Чтение с заданного в формате [UNIX timestamp](https://ru.wikipedia.org/wiki/Unix-время) времени.<br>Если параметр не указан, то чтение выполняется с текущей рабочей позиции читателя в топике.<br>Если параметр указан, то чтение начнется с первого [сообщения](../../../concepts/topic.md#message), полученного после указанного времени.
+`--with-metadata-fields VAL` | Список [атрибутов сообщения](../../../concepts/topic.md#message), значения которых нужно выводить в колонках с метаинформацией в формате `pretty`. Если параметр не указан, то выводятся колонки со всеми атрибутами. <br>Возможные значения:<ul><li>`write_time` — время записи сообщения на сервер в формате [UNIX timestamp](https://ru.wikipedia.org/wiki/Unix-время);</li><li>`meta` — метаданные сообщения;</li><li>`create_time` — время создания сообщения источником в формате [UNIX timestamp](https://ru.wikipedia.org/wiki/Unix-время);</li><li>`seq_no` — [порядковый номер](../../../concepts/topic.md#seqno) сообщения;</li><li>`offset` — [порядковый номер сообщения внутри партиции](../../../concepts/topic.md#offset);</li><li>`message_group_id` — [идентификатор группы сообщений](../../../concepts/topic.md#producer-id);</li><li>`body` — тело сообщения.</li></ul>
+
+## Примеры {#examples}
+
+{% include [example_db1.md](../_includes/example_db1.md) %}
+
+Все примеры используют имя топика `topic1` и имя читателя `c1`.
+
+* Чтение одного сообщения с выводом в терминал. Если в топике нет новых сообщения для данного читателя, исполнение команды будет завершено без какого-либо вывода:
+  ```bash
+  {{ ydb-cli }} -p db1 topic read topic1 -c c1
+  ```
+
+* Ожидание появления и чтение одного сообщения с записью его в файл `message.bin`. До тех пор пока в топике нет новых сообщений для данного читателя, команда будет оставаться запущенной, но её можно прервать нажав `Ctrl+C`:
+  ```bash
+  {{ ydb-cli }} -p db1 topic read topic1 -c c1 -w -f message.bin
+  ```
+
+* Просмотр информации об ожидающих обработки читателем сообщениях без их подтверждения. Будет выведено до 10 первых сообщений:
+  ```bash
+  {{ ydb-cli }} -p db1 topic read topic1 -c c1 --format pretty --commit false
+  ```
+
+* Вывод в терминал сообщений по мере их появления в формате разделения символами перевода строки, с конвертацией в кодировку Base64. Команда будет исполняться до прерывания нажатием `Ctrl+C`:
+  ```bash
+  {{ ydb-cli }} -p db1 topic read topic1 -c c1 -w --format newline-delimited --transform base64
+  ```
+
+* Отслеживание появления в топике сообщений, содержащих текст `ERROR`, с выводом их в терминал по мере появления:
+  ```bash
+  {{ ydb-cli }} -p db1 topic read topic1 -c c1 --format newline-delimited -w | grep ERROR
+  ```
+
+* Получение следующего непустого пакета из не более 150 сообщений, преобразованных в base64, с разделением символом перевода строки, и записью в файл `batch.txt`:
+  ```bash
+  {{ ydb-cli }} -p db1 topic read topic1 -c c1 \
+    --format newline-delimited -w --limit 150 \
+    --transform base64 -f batch.txt
+  ```
+
+* [Примеры интеграции команд YDB CLI](integration.md)
\ No newline at end of file
diff --git a/ydb/docs/ru/core/reference/ydb-cli/topic/scheme.md b/ydb/docs/ru/core/reference/ydb-cli/topic/scheme.md
new file mode 100644
index 00000000000..f8381d214cb
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/topic/scheme.md
@@ -0,0 +1,178 @@
+# Команды работы со схемой топиков
+
+YDB CLI поддерживает следующие команды для управления объектами схемы типа "топик":
+
+* [topic create](#create) - Создание топика
+* [topic alter](#alter) - Изменение параметров существующего топика
+* [topic consumer add](#consumer-add) - Добавление читателя в топик
+* [scheme describe](#describe) - Получение информации о параметрах топика
+* [topic consumer drop](#consumer-drop) - Удаление читателя из топика
+* [topic drop](#drop) - Удаление топика
+
+В примерах используется профиль `db1`, подробнее смотрите в [{#T}](../../../getting_started/cli.md#profile).
+
+## Создание топика {#create}
+
+Общий вид команды:
+
+```bash
+{{ ydb-cli }} [global options...] topic create <topic-path> [options...]
+```
+
+* `global options` — [глобальные параметры](../commands/global-options.md).
+* `topic-path` — путь топика.
+* `options` — [параметры](#create-options).
+
+### Параметры {#create-options}
+
+Имя | Описание
+---|---
+`--partitions-count VAL`| Количество [партиций](../../../concepts/topic.md#partitioning) топика.<br>Значение по умолчанию — `1`.
+`--retention-period-hours VAL` | Время хранения данных в топике, задается в часах.<br>Значение по умолчанию — `18`.
+`--supported-codecs STRING` | Поддерживаемые методы сжатия данных.<br>Значение по умолчанию — `raw,zstd,gzip,lzop`.<br>Возможные значения:<ul><li>`RAW` — без сжатия;</li><li>`ZSTD` — сжатие [zstd](https://ru.wikipedia.org/wiki/Zstandard);</li><li>`GZIP` — сжатие [gzip](https://ru.wikipedia.org/wiki/Gzip);</li><li>`LZOP` — сжатие [lzop](https://ru.wikipedia.org/wiki/Lzop).</li></ul>
+
+### Примеры {#create-examples}
+
+Создание топика с 2 партициями, методами сжатия `RAW` и `GZIP`, временем хранения сообщений 2 часа и путем `my-topic`:
+
+```bash
+{{ ydb-cli }} -p db1 topic create my-topic \
+  --partitions-count 2 \
+  --supported-codecs raw,gzip \
+  --retention-period-hours 2
+```
+
+## Изменение топика {#alter}
+
+С помощью подкоманды `topic alter` вы можете изменить [созданный ранее](#topic-create) топик.
+
+Общий вид команды:
+
+```bash
+{{ ydb-cli }} [global options...] topic alter <topic-path> [options...]
+```
+
+* `global options` — [глобальные параметры](../commands/global-options.md).
+* `topic-path` — путь топика.
+* `options` — [параметры](#alter-options).
+
+### Параметры {#alter-options}
+
+При исполнении команды будут изменены значения тех параметров, которые заданы в командной строке. Значения остальных параметров останутся без изменений.
+
+Имя | Описание
+---|---
+`--partitions-count VAL`| Количество [партиций](../../../concepts/topic.md#partitioning) топика. Возможно только увеличение количества партиций.
+`--retention-period-hours VAL` | Время хранения данных в топике в часах.
+`--supported-codecs STRING` | Поддерживаемые метод сжатия данных. <br>Возможные значения:<ul><li>`RAW` — без сжатия;</li><li>`ZSTD` — сжатие [zstd](https://ru.wikipedia.org/wiki/Zstandard);</li><li>`GZIP` — сжатие [gzip](https://ru.wikipedia.org/wiki/Gzip);</li><li>`LZOP` — сжатие [lzop](https://ru.wikipedia.org/wiki/Lzop).</li></ul>
+
+### Примеры {#alter-examples}
+
+Добавьте партицию и метод сжатия `lzop` [созданному ранее](#create-examples) топику:
+
+```bash
+{{ ydb-cli }} -p db1 topic alter my-topic \
+  --partitions-count 3 \
+  --supported-codecs raw,gzip,lzop
+```
+
+## Добавление читателя для топика {#consumer-add}
+
+С помощью команды `topic consumer add` вы можете добавить читателя для [созданного ранее](#create) топика.
+
+Общий вид команды:
+
+```bash
+{{ ydb-cli }} [global options...] topic consumer add <topic-path> [options...]
+```
+
+* `global options` — [глобальные параметры](../commands/global-options.md).
+* `topic-path` — путь топика.
+* `options` — [параметры подкоманды](#consumer-add-options).
+
+
+### Параметры {#consumer-add-options}
+
+Имя | Описание
+---|---
+`--consumer-name VAL` | Имя читателя, которого нужно добавить.
+`--starting-message-timestamp VAL` | Время в формате [UNIX timestamp](https://ru.wikipedia.org/wiki/Unix-время). Чтение начнется с первого [сообщения](../../../concepts/topic.md#message), полученного после указанного времени. Если время не задано, то чтение начнется с самого старого сообщения в топике.
+
+### Примеры {#consumer-add-examples}
+
+Создайте читателя с именем `c1` для [созданного ранее](#create-examples) топика `my-topic`:
+
+```bash
+{{ ydb-cli }} -p db1 topic consumer add my-topic --consumer-name c1  
+```
+
+## Получение информации о параметрах топика {#describe}
+
+Для получения информации о параметрах топика используется единая команда получения информации об объекте схемы [scheme describe](../commands/scheme-describe.md). Для топика данная команда выводит значения его параметров, а также перечень существующих читателей топика с их параметрами.
+
+### Примеры {#describe-examples}
+
+```bash
+{{ ydb-cli }} -p db1 scheme describe my-topic
+```
+
+Результат:
+
+```text
+RetentionPeriod: 2 hours
+PartitionsCount: 3
+SupportedCodecs: RAW, GZIP, LZOP
+
+Consumers: 
+┌──────────────┬─────────────────┬───────────────────────────────┬───────────┐
+| ConsumerName | SupportedCodecs | ReadFrom                      | Important |
+├──────────────┼─────────────────┼───────────────────────────────┼───────────┤
+| c1           | RAW, GZIP       | Mon, 15 Aug 2022 16:00:00 MSK | 0         |
+└──────────────┴─────────────────┴───────────────────────────────┴───────────┘
+```
+
+## Удаление читателя {#consumer-drop}
+
+С помощью команды `topic consumer drop` вы можете удалить [добавленного ранее](#consumer-add) читателя.
+
+Общий вид команды:
+
+```bash
+{{ ydb-cli }} [global options...] topic consumer drop <topic-path> [options...] 
+```
+
+* `global options` — [глобальные параметры](../commands/global-options.md).
+* `topic-path` — путь топика.
+* `options` — [параметры подкоманды](#consumer-drop-options).
+
+### Параметры {#consumer-drop-options}
+
+Имя | Описание
+---|---
+`--consumer-name VAL` | Имя читателя, которого нужно удалить.
+
+### Примеры {#consumer-drop-examples}
+
+Удалите [ранее добавленного](#consumer-add) читателя с именем `c1` для топика `my-topic`:
+
+```bash
+{{ ydb-cli }} -p db1 topic consumer drop my-topic --consumer-name c1
+```
+
+## Удаление топика {#drop}
+
+Общий вид команды:
+
+```bash
+{{ ydb-cli }} [global options...] topic drop <topic-path>
+```
+
+* `global options` — [глобальные параметры](../commands/global-options.md).
+* `topic-path` — путь топика.
+
+### Примеры {#drop-examples}
+
+```bash
+{{ ydb-cli }} -p db1 topic drop my-topic
+```
+
diff --git a/ydb/docs/ru/core/reference/ydb-cli/topic/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-cli/topic/toc_i.yaml
new file mode 100644
index 00000000000..803557788a5
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/topic/toc_i.yaml
@@ -0,0 +1,11 @@
+items:
+- name: Обзор
+  href: index.md
+- name: Схема топиков
+  href: scheme.md
+- name: Чтение сообщений
+  href: read.md
+- name: Запись сообщений
+  href: write.md
+- name: Интеграция чтения и записи
+  href: integration.md
\ No newline at end of file
diff --git a/ydb/docs/ru/core/reference/ydb-cli/topic/write.md b/ydb/docs/ru/core/reference/ydb-cli/topic/write.md
new file mode 100644
index 00000000000..c3cea9d20a4
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/topic/write.md
@@ -0,0 +1,70 @@
+# Запись в топик
+
+Командой `topic write` выполняется запись сообщений в топик из файла или `stdin`: 
+
+```bash
+{{ ydb-cli }} [connection options] topic write <topic-path> \
+  [--file STR] [--format STR] [--transform STR] \
+  [дополнительные параметры...] 
+```
+
+{% include [conn_options_ref.md](../commands/_includes/conn_options_ref.md) %}
+
+## Параметры {#options}
+
+### Основные параметры
+
+`<topic-path>` : Путь топика, единственный обязательный параметр
+
+`--file VAL` (`-f VAL`): Читать поток входящих сообщений для записи в топик из указанного файла. Если не указан -- чтение производится из `stdin`.
+
+`--format STR`: Формат потока входящих сообщений
+* Поддерживаемые форматы
+
+  Имя | Описание
+  ---|---
+  `single-message`<br>(по умолчанию)|Все содержимого потока на входе рассматривается как одно сообщение для записи в топик
+  `newline-delimited`|Поток на входе содержит множество сообщений, разделенных символом перевода строки `0x0A`
+
+`--transform VAL`: Метод преобразования сообщений
+
+- Значение по умолчанию — `none`
+- Возможные значения:
+  `base64` — выполнить декодирование каждого сообщения из [Base64](https://ru.wikipedia.org/wiki/Base64) на входном потоке, записать результат декодирования в топик. Если декодирование не удалось, исполнение команды будет прервано с ошибкой.
+  `none` — не выполнять преобразований, записать в топик содержимое сообщения из входного потока побайтово
+
+### Дополнительные параметры
+
+Имя | Описание
+---|---
+`--delimiter STR` | Байт-разделитель. Поток на входе разделяется на сообщения указанным байтом. Может быть задан только в случае, если не указан `--format`. Задается в виде экранированной строки.
+`--message-group-id STR` | Строковой идентификатор группы сообщений. Если не указан, то все сгенерированные из входного потока сообщения получат одинаковое значение идентификатора, представляющее собой шестнадцатеричное строковое представление случайного трехбайтового целого числа.
+`--codec STR` | Кодек, используемый для сжатия сообщений на клиенте перед отправкой на сервер. Возможные варианты: `RAW` (по умолчанию) - без сжатия, `GZIP`, `ZSTD`. Сжатие увеличивает затраты CPU на клиенте при записи и чтении сообщений, но обычно позволяет уменьшить объем передаваемых по сети и хранимых данных. При последующем чтении сообщений подписчиками они автоматически расжимаются использованным при записи кодеком, не требуя указания каких-либо специальных опций. Указанный кодек должен быть перечислен среди допустимых в [параметрах топика](scheme.md#create-options).
+
+## Примеры {#examples}
+
+{% include [example_db1.md](../_includes/example_db1.md) %}
+
+Все примеры используют имя топика `topic1`.
+
+* Запись ввода с терминала в одно сообщение. После запуска команды можно ввести произвольный многострочный текст, завершив ввод нажатием `Ctrl+D`.
+  ```bash
+  {{ ydb-cli }} -p db1 topic write topic1
+  ```
+
+* Запись содержимого бинарного файла `message.bin` в одно сообщение с использованием сжатия кодеком GZIP
+  ```bash
+  {{ ydb-cli }} -p db1 topic write topic1 -f message.bin --codec GZIP
+  ```
+
+* Запись содержимого строкового файла `example.txt` с разделением на сообщения по строкам
+  ```bash
+  {{ ydb-cli }} -p db1 topic write topic1 -f example.txt --format newline-delimited
+  ```
+
+* Запись скачивамого по протоколу HTTP ресурса с разделением на сообщения символами табуляции
+  ```bash
+  curl http://example.com/resource | {{ ydb-cli }} -p db1 topic write topic1 --delimiter "\t"
+  ```
+
+* [Примеры интеграции команд YDB CLI](integration.md)
\ No newline at end of file
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/topic.md b/ydb/docs/ru/core/reference/ydb-sdk/topic.md
index 9cf237caf5f..95f7cd9f186 100644
--- a/ydb/docs/ru/core/reference/ydb-sdk/topic.md
+++ b/ydb/docs/ru/core/reference/ydb-sdk/topic.md
@@ -2,7 +2,7 @@
 
 В этой статье приведены примеры использования {{ ydb-short-name }} SDK для работы с [топиками](../../concepts/topic.md).
 
-Перед выполнением примеров [создайте топик](../ydb-cli/topic.md#topic-create) и [добавьте читателя](../ydb-cli/topic.md#consumer-add).
+Перед выполнением примеров [создайте топик](../ydb-cli/topic/scheme.md#create) и [добавьте читателя](../ydb-cli/topic/scheme.md#consumer-add).
 
 ## Подключение к топику {#start-reader}