Перейти к основному содержимому
Перейти к основному содержимому

Движок NATS

Этот движок позволяет интегрировать ClickHouse с NATS.

NATS позволяет вам:

  • Публиковать или подписываться на темы сообщений.
  • Обрабатывать новые сообщения по мере их появления.

Создание таблицы​

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

  • nats_url – host:port (например, localhost:5672)..
  • nats_subjects – Список тем для таблицы NATS, на которые можно подписаться/публиковать. Поддерживаются шаблонные темы такие как foo.*.bar или baz.>.
  • nats_format – Формат сообщения. Использует ту же нотацию, что и функция SQL FORMAT, например, JSONEachRow. Для получения дополнительной информации см. раздел Форматы.

Необязательные параметры:

  • nats_schema – Параметр, который необходимо использовать, если формат требует определения схемы. Например, Cap'n Proto требует путь к файлу схемы и имя корневого объекта schema.capnp:Message.
  • nats_num_consumers – Количество потребителей на таблицу. По умолчанию: 1. Укажите больше потребителей, если пропускная способность одного потребителя недостаточна.
  • nats_queue_group – Имя группы очереди для подписчиков NATS. По умолчанию используется имя таблицы.
  • nats_max_reconnect – Устарело и не имеет эффекта, переподключение выполняется постоянно с таймаутом nats_reconnect_wait.
  • nats_reconnect_wait – Количество времени в миллисекундах для ожидания между каждой попыткой переподключения. По умолчанию: 5000.
  • nats_server_list - Список серверов для подключения. Може быть указан для подключения к кластеру NATS.
  • nats_skip_broken_messages - Толерантность парсера сообщений NATS к сообщениям, несовместимым со схемой. По умолчанию: 0. Если nats_skip_broken_messages = N, движок пропускает N сообщений NATS, которые не могут быть разобраны (сообщение равно строке данных).
  • nats_max_block_size - Количество строк, собранных по опросам для сброса данных из NATS. По умолчанию: max_insert_block_size.
  • nats_flush_interval_ms - Таймаут для сброса данных, считанных из NATS. По умолчанию: stream_flush_interval_ms.
  • nats_username - Имя пользователя NATS.
  • nats_password - Пароль NATS.
  • nats_token - Токен аутентификации NATS.
  • nats_credential_file - Путь к файлу учетных данных NATS.
  • nats_startup_connect_tries - Количество попыток подключения при запуске. По умолчанию: 5.
  • nats_max_rows_per_message — Максимальное количество строк, записанных в одном сообщении NATS для форматов на основе строк. (по умолчанию: 1).
  • nats_handle_error_mode — Способ обработки ошибок для движка NATS. Возможные значения: default (текст исключения будет выброшен, если не удалось разобрать сообщение), stream (текст сообщения исключения и необработанное сообщение будут сохранены в виртуальных колонках _error и _raw_message).

SSL соединение:

Для безопасного соединения используйте nats_secure = 1. По умолчанию библиотека, используемая для установления соединения TLS, не проверяет, является ли созданное соединение достаточно безопасным. Независимо от того, истек ли сертификат, самоподписанный, отсутствует или недействителен: соединение просто разрешается. Более строгая проверка сертификатов может быть реализована в будущем.

Запись в таблицу NATS:

Если таблица считывает только из одной темы, любое вставляемое значение будет публиковаться в ту же тему. Однако, если таблица считывает из нескольких тем, необходимо указать, в какую тему мы хотим публиковать. Поэтому всякий раз, когда вставляются данные в таблицу с несколькими темами, необходимо установить stream_like_engine_insert_queue. Вы можете выбрать одну из тем, из которых таблица считывает, и опубликовать свои данные там. Например:

Также можно добавлять настройки формата вместе с настройками, связанными с nats.

Пример:

Конфигурация сервера NATS может быть добавлена с использованием файла конфигурации ClickHouse. Более конкретно, вы можете добавить пароль Redis для движка NATS:

Описание​

SELECT не особенно полезен для чтения сообщений (за исключением отладки), так как каждое сообщение можно прочитать только один раз. Практичнее создавать потоки в реальном времени, используя материализованные представления. Для этого:

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

Когда MATERIALIZED VIEW подключается к движку, он начинает собирать данные в фоновом режиме. Это позволяет вам постоянно получать сообщения из NATS и преобразовывать их в требуемый формат с использованием SELECT. В одной таблице NATS может быть столько же материализованных представлений, сколько вам нужно, они не читают данные из таблицы напрямую, но получают новые записи (блоками), это позволяет вам записывать в несколько таблиц с разным уровнем детализации (с группировкой - агрегацией и без).

Пример:

Чтобы остановить получение данных потоков или изменить логику преобразования, отсоедините материализованное представление:

Если вы хотите изменить целевую таблицу, используя ALTER, мы рекомендуем отключить материализованное представление, чтобы избежать несоответствий между целевой таблицей и данными из представления.

Виртуальные колонки​

  • _subject - Тема сообщения NATS. Тип данных: String.

Дополнительные виртуальные колонки при nats_handle_error_mode='stream':

  • _raw_message - Необработанное сообщение, которое не удалось успешно разобрать. Тип данных: Nullable(String).
  • _error - Сообщение исключения, произошедшее во время неудачного разбора. Тип данных: Nullable(String).

Примечание: виртуальные колонки _raw_message и _error заполняются только в случае исключения во время разбора, они всегда имеют значение NULL, когда сообщение было успешно разобрано.

Поддержка форматов данных​

Движок NATS поддерживает все форматы, поддерживаемые в ClickHouse. Количество строк в одном сообщении NATS зависит от того, является ли формат основанным на строках или блоках:

  • Для форматов на основе строк количество строк в одном сообщении NATS можно контролировать с помощью установки nats_max_rows_per_message.
  • Для форматов на основе блоков мы не можем разделить блок на меньшие части, но количество строк в одном блоке можно контролировать с помощью общей настройки max_block_size.