--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://ydb.tech/docs/en/reference/ydb-cli/topic-read.md?version=v26.1 - https://ydb.tech/docs/ru/reference/ydb-cli/topic-read.md?version=v26.1 - href: ru/reference/ydb-cli/topic-read.md type: text/markdown title: Markdown version - href: ../../llms.txt type: text/markdown title: llms.txt sourcePath: ru/core/reference/ydb-cli/topic-read.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt # Чтение из топика Командой `topic read` выполняется чтение сообщений из топика с выводом их в файл или в терминал командной строки: ```bash ydb [connection options] topic read [--consumer STR] \ [--format STR] [--wait] [--limit INT] \ [--transform STR] [--file STR] [--commit BOOL] \ [дополнительные параметры...] ``` , где `[connection options]` — опции [соединения с БД](https://ydb.tech/docs/ru/reference/ydb-cli/connect.md?version=v26.1#command-line-pars) Поддерживается три режима работы команды: 1. **Одно сообщение**. Из топика считывается не более одного сообщения. 2. **Пакетный режим**. Сообщения из топика считываются до того момента, пока в топике не закончатся сообщения для обработки, или количество сообщений не превысит устанавливаемое обязательно ограничение. 3. **Потоковый режим**. Сообщения из топика считываются по мере их появления, с ожиданием появления новых, до момента пока исполнение команды не будет прервано нажатием `Ctrl+C`, или количество сообщений не превысит опционально задаваемое ограничение. ## Параметры {#options} ### Обязательные параметры ``: Путь топика ### Основные опциональные параметры `-c VAL`, `--consumer VAL`: Имя читателя топика. - Если имя читателя не задано, то необходимо указать значение параметра `--partition-ids`. Только в этом случае возможно чтение из топика без указания имени читателя. - Чтение сообщений будет начато с текущей рабочей позиции (offset) для данного читателя (если не указан параметр `--timestamp`). Если не указать имя читателя, то чтение сообщений начнется с первого сообщения в партиции `--format STR`: Формат вывода - Задает правило оформления сообщений на выходе. Не все форматы могут работать в потоковом режиме. - Перечень поддерживаемых форматов: | Имя | Описание | Поддерживает
потоковый режим? | |-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------| | `single-message`
(по умолчанию) | Вывод содержимого не более одного сообщения без оформления. | - | | `pretty` | Вывод в псевдографическую таблицу с колонками, содержащими метаинформацию о сообщениях. В колонке `body` выводится само сообщение. | Нет | | `newline-delimited` | Вывод сообщений с добавлением после каждого сообщения разделителя - символа перевода строки `0x0A` | Да | | `concatenated` | Вывод сообщений одного за другим без добавления какого-либо разделителя | Да | `--wait` (`-w`): Ожидание появления сообщений - Включает ожидание появления первого сообщения в топике. Если он не задан, и в топике нет сообщений для обработки, то исполнение команды будет завершено сразу после старта. Если он задан, то запущенная команда чтения будет ожидать появления первого сообщения для обработки. - Включает потоковый режим отбора для форматов, которые его поддерживают, иначе используется пакетный режим. `--limit INT`: Максимальное количество считываемых из топика сообщений - Значения по умолчанию и допустимые значения зависят от выбранного формата вывода: | Поддерживает ли формат
потоковый режим отбора | Значение лимита по умолчанию | Допустимые значения | |---------------------------------------------------|------------------------------|---------------------| | Нет | 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`: Подтверждение чтения. Значение по умолчанию - `false` - Возможные значения: `true`, `false`. - Если установлено значение `true`, то текущая рабочая позиция (offset) читателя в топике будет сохраняться по мере чтения сообщений из топика. - Если установлено значение `false`, то сообщения будут вычитываться, но прогресс чтения не будет сохраняться и при перезапуске сообщения будут вычитаны заново. Эта функциональность полезна при дебаге: для вычитывания сообщений без влияния на продуктовую систему (без смещение offset). ### Другие опциональные параметры | Имя | Описание | |-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--idle-timeout VAL` | Таймаут принятия решения о том что топик пуст, то есть новые сообщения для обработки отсутствуют.
Замеряется время с момента установки соединения при запуске команды, или получения последнего сообщения. Если в течение заданного таймаута с сервера не приходит новых сообщений, топик считается пустым.
Значение по умолчанию — `1s` (1 секунда). | | `--timestamp VAL` | Чтение с заданного в формате [UNIX timestamp](https://ru.wikipedia.org/wiki/Unix-время) времени.
Если параметр не указан, то чтение выполняется с текущей рабочей позиции читателя в топике.
Если параметр указан, то чтение начнется с первого [сообщения](../../concepts/datamodel/topic.md#message), полученного после указанного времени. | | `--metadata-fields VAL` | Список [атрибутов сообщения](../../concepts/datamodel/topic.md#message), значения которых нужно выводить в колонках с метаинформацией в формате `pretty`. Если параметр не указан, то выводятся колонки со всеми атрибутами.
Возможные значения: | | `--partition-ids VAL` | Идентификаторы (порядковые номера) [партиций](../../concepts/datamodel/topic.md#partitioning), из которых будет производиться чтение.
Если параметр не указан, то чтение производится из всех партиций. | ## Примеры {#examples} {% note info %} В примерах используется профиль `quickstart`, подробнее смотрите в [Создание профиля для соединения с тестовой БД](https://ydb.tech/docs/ru/reference/ydb-cli/profile/create.md?version=v26.1#quickstart). {% endnote %} Все примеры используют имя топика `topic1` и имя читателя `c1`. * Чтение одного сообщения с выводом в терминал. Если в топике нет новых сообщения для данного читателя, исполнение команды будет завершено без какого-либо вывода: ```bash ydb -p quickstart topic read topic1 -c c1 ``` * Ожидание появления и чтение одного сообщения с записью его в файл `message.bin`. До тех пор пока в топике нет новых сообщений для данного читателя, команда будет оставаться запущенной, но её можно прервать нажав `Ctrl+C`: ```bash ydb -p quickstart topic read topic1 -c c1 -w -f message.bin ``` * Просмотр информации об ожидающих обработки читателем сообщениях без их подтверждения. Будет выведено до 10 первых сообщений: ```bash ydb -p quickstart topic read topic1 -c c1 --format pretty --commit false ``` * Вывод в терминал сообщений по мере их появления в формате разделения символами перевода строки, с конвертацией в кодировку Base64. Команда будет исполняться до прерывания нажатием `Ctrl+C`: ```bash ydb -p quickstart topic read topic1 -c c1 -w --format newline-delimited --transform base64 ``` * Отслеживание появления в топике сообщений, содержащих текст `ERROR`, с выводом их в терминал по мере появления: ```bash ydb -p quickstart topic read topic1 -c c1 --format newline-delimited -w | grep ERROR ``` * Получение следующего непустого пакета из не более 150 сообщений, преобразованных в base64, с разделением символом перевода строки, и записью в файл `batch.txt`: ```bash ydb -p quickstart topic read topic1 -c c1 \ --format newline-delimited -w --limit 150 \ --transform base64 -f batch.txt ``` * [Примеры интеграции команд YDB CLI](https://ydb.tech/docs/ru/reference/ydb-cli/topic-pipeline.md?version=v26.1)