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

Командой 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, или количество сообщений не превысит опционально задаваемое ограничение.

Параметры

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

Имя Описание
<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: Подтверждение чтения.

  1. Если установлено значение true (по умолчанию), то текущая рабочая позиция (offset) читателя в топике будет передвигаться по мере чтения сообщений из топика.
  2. Возможные значения: 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
    
  • Примеры интеграции команд YDB CLI