Чтение из топика
Командой 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 ). |
Основные опциональные параметры
--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 времени. Если параметр не указан, то чтение выполняется с текущей рабочей позиции читателя в топике. Если параметр указан, то чтение начнется с первого сообщения, полученного после указанного времени. |
--with-metadata-fields VAL |
Список атрибутов сообщения, значения которых нужно выводить в колонках с метаинформацией в формате pretty . Если параметр не указан, то выводятся колонки со всеми атрибутами. Возможные значения:
|
--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