Чтение из топика

Командой topic read выполняется чтение сообщений из топика с выводом их в файл или в терминал командной строки:

ydb [connection options] topic read <topic-path> --consumer STR \
  [--format STR] [--wait] [--limit INT] \
  [--transform STR] [--file STR] [--commit BOOL] \
  [дополнительные параметры...]

, где [connection options] — опции соединения с БД

Поддерживается три режима работы команды:

Одно сообщение. Из топика считывается не более одного сообщения.
Пакетный режим. Сообщения из топика считываются до того момента, пока в топике не закончатся сообщения для обработки, или количество сообщений не превысит устанавливаемое обязательно ограничение.
Потоковый режим. Сообщения из топика считываются по мере их появления, с ожиданием появления новых, до момента пока исполнение команды не будет прервано нажатием Ctrl+C, или количество сообщений не превысит опционально задаваемое ограничение.

Параметры

Обязательные параметры

Имя Описание

<topic-path> Путь топика

-c VAL, --consumer VAL Имя читателя топика.
Чтение сообщений будет начато с текущей рабочей позиции (offset) для данного читателя (если не указан параметр --timestamp).
Текущая рабочая позиция будет передвигаться по мере чтения и вывода сообщений (если не указано значение параметра --commit=false).

Имя	Описание
`<topic-path>`	Путь топика
`-c VAL`, `--consumer VAL`	Имя читателя топика. Чтение сообщений будет начато с текущей рабочей позиции (offset) для данного читателя (если не указан параметр `--timestamp`). Текущая рабочая позиция будет передвигаться по мере чтения и вывода сообщений (если не указано значение параметра `--commit=false`).

Основные опциональные параметры

--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
none — не выполнять преобразований, передать на выход содержимое сообщения побайтово

--file VAL (-f VAL): Записывать читаемые сообщения в указанный файл. Если параметр не задан, то сообщения выводятся в stdout.

--commit BOOL: Подтверждение чтения.

Если установлено значение true (по умолчанию), то текущая рабочая позиция (offset) читателя в топике будет передвигаться по мере чтения сообщений из топика.
Возможные значения: true, false.

Другие опциональные параметры

Имя	Описание
`--idle-timeout VAL`	Таймаут принятия решения о том что топик пуст, то есть новые сообщения для обработки отсутствуют. Замеряется время с момента установки соединения при запуске команды, или получения последнего сообщения. Если в течение заданного таймаута с сервера не приходит новых сообщений, топик считается пустым. Значение по умолчанию — `1s` (1 секунда).
`--timestamp VAL`	Чтение с заданного в формате UNIX timestamp времени. Если параметр не указан, то чтение выполняется с текущей рабочей позиции читателя в топике. Если параметр указан, то чтение начнется с первого сообщения, полученного после указанного времени.
`--metadata-fields VAL`	Список атрибутов сообщения, значения которых нужно выводить в колонках с метаинформацией в формате `pretty`. Если параметр не указан, то выводятся колонки со всеми атрибутами. Возможные значения: `write_time` — время записи сообщения на сервер в формате UNIX timestamp; `meta` — метаданные сообщения; `create_time` — время создания сообщения источником в формате UNIX timestamp; `seq_no` — порядковый номер сообщения; `offset` — порядковый номер сообщения внутри партиции; `message_group_id` — идентификатор группы сообщений; `body` — тело сообщения.
`--partition-ids VAL`	Идентификаторы (порядковые номера) партиций, из которых будет производиться чтение. Если параметр не указан, то чтение производится из всех партиций.

Примеры

Примечание

В примерах используется профиль quickstart, подробнее смотрите в Создание профиля для соединения с тестовой БД.

Все примеры используют имя топика topic1 и имя читателя c1.

Чтение одного сообщения с выводом в терминал. Если в топике нет новых сообщения для данного читателя, исполнение команды будет завершено без какого-либо вывода:
```
ydb -p quickstart topic read topic1 -c c1
```
Ожидание появления и чтение одного сообщения с записью его в файл message.bin. До тех пор пока в топике нет новых сообщений для данного читателя, команда будет оставаться запущенной, но её можно прервать нажав Ctrl+C:
```
ydb -p quickstart topic read topic1 -c c1 -w -f message.bin
```
Просмотр информации об ожидающих обработки читателем сообщениях без их подтверждения. Будет выведено до 10 первых сообщений:
```
ydb -p quickstart topic read topic1 -c c1 --format pretty --commit false
```
Вывод в терминал сообщений по мере их появления в формате разделения символами перевода строки, с конвертацией в кодировку Base64. Команда будет исполняться до прерывания нажатием Ctrl+C:
```
ydb -p quickstart topic read topic1 -c c1 -w --format newline-delimited --transform base64
```
Отслеживание появления в топике сообщений, содержащих текст ERROR, с выводом их в терминал по мере появления:
```
ydb -p quickstart topic read topic1 -c c1 --format newline-delimited -w | grep ERROR
```
Получение следующего непустого пакета из не более 150 сообщений, преобразованных в base64, с разделением символом перевода строки, и записью в файл batch.txt:
```
ydb -p quickstart topic read topic1 -c c1 \
  --format newline-delimited -w --limit 150 \
  --transform base64 -f batch.txt
```
Примеры интеграции команд YDB CLI