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

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

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

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

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

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

Параметры

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

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

--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: Подтверждение чтения.

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

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

Примеры

Все примеры используют имя топика 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