Skip to main content
Этот коннектор следует использовать только в том случае, если ваши данные просты и состоят из примитивных типов данных, например int. Специфичные для ClickHouse типы, такие как Map, не поддерживаются.
В наших примерах мы используем дистрибутив Confluent для Kafka Connect. Ниже описана простая установка, при которой сообщения считываются из одного топика Kafka, а строки вставляются в таблицу ClickHouse. Мы рекомендуем Confluent Cloud, который предлагает достаточно щедрый бесплатный уровень для тех, у кого нет собственной среды Kafka. Обратите внимание, что для коннектора JDBC требуется схема (с коннектором JDBC нельзя использовать обычные JSON или CSV). Хотя схема может быть закодирована в каждом сообщении, настоятельно рекомендуется использовать Schema Registry от Confluent, чтобы избежать связанных с этим накладных расходов. Предоставленный скрипт вставки автоматически определяет схему по сообщениям и регистрирует её в реестре — поэтому этот скрипт можно повторно использовать и для других датасетов. Предполагается, что ключи Kafka имеют тип String. Более подробную информацию о схемах Kafka можно найти здесь.

Лицензия

Коннектор JDBC распространяется по лицензии Confluent Community

Порядок действий

Подготовьте сведения о подключении

Чтобы подключиться к ClickHouse по HTTP(S), вам понадобится следующая информация: Сведения о подключении для вашего сервиса ClickHouse Cloud доступны в консоли ClickHouse Cloud. Выберите сервис и нажмите Connect: Выберите HTTPS. Сведения о подключении будут показаны в примере команды curl. Если вы используете самоуправляемый ClickHouse, сведения о подключении задаёт ваш администратор ClickHouse.

1. Установите Kafka Connect и коннектор

Предполагается, что вы уже скачали пакет Confluent и установили его локально. Следуйте инструкциям по установке коннектора, приведённым здесь. Если вы используете метод установки через confluent-hub, локальные конфигурационные файлы будут обновлены. Для отправки данных из Kafka в ClickHouse мы используем компонент sink коннектора.

2. Загрузите и установите JDBC-драйвер

Загрузите и установите JDBC-драйвер ClickHouse clickhouse-jdbc-<version>-shaded.jar отсюда. Установите его в Kafka Connect, следуя инструкциям здесь. Другие драйверы могут работать, но не тестировались.
Распространённая проблема: в документации рекомендуется скопировать jar-файл в share/java/kafka-connect-jdbc/. Если у вас возникают проблемы с тем, что Connect не находит драйвер, скопируйте его в share/confluent-hub-components/confluentinc-kafka-connect-jdbc/lib/. Либо измените plugin.path, чтобы он включал драйвер, — см. ниже.

3. Подготовьте конфигурацию

Следуйте этим инструкциям по настройке Connect в соответствии с типом вашей установки, учитывая различия между автономным и распределённым кластером. Если вы используете Confluent Cloud, вам подходит распределённая конфигурация. Следующие параметры важны при использовании коннектора JDBC с ClickHouse. Полный список параметров приведён здесь:
  • _connection.url_ - должен иметь вид jdbc:clickhouse://&lt;clickhouse host>:&lt;clickhouse http port>/&lt;target database>
  • connection.user - пользователь с правами на запись в целевую базу данных
  • table.name.format- таблица ClickHouse, в которую выполняется вставка данных. Она должна существовать.
  • batch.size - количество строк, отправляемых в одном батче. Убедитесь, что здесь задано достаточно большое значение. Согласно рекомендациям ClickHouse, значение 1000 следует считать минимумом.
  • tasks.max - коннектор JDBC Sink поддерживает запуск одной или нескольких задач. Это можно использовать для повышения производительности. Наряду с размером батча это ваш основной способ повысить производительность.
  • value.converter.schemas.enable - установите false, если используете Schema Registry, и true, если встраиваете схемы в сообщения.
  • value.converter - задайте в соответствии с типом данных, например для JSON: io.confluent.connect.json.JsonSchemaConverter.
  • key.converter - установите org.apache.kafka.connect.storage.StringConverter. Мы используем ключи String.
  • pk.mode - для ClickHouse неактуален. Установите none.
  • auto.create - не поддерживается и должно быть false.
  • auto.evolve - для этого параметра мы рекомендуем false, хотя в будущем он может поддерживаться.
  • insert.mode - установите значение “insert”. Другие режимы в настоящее время не поддерживаются.
  • key.converter - задайте в соответствии с типами ваших ключей.
  • value.converter - задайте в зависимости от типа данных в вашем топике. Эти данные должны иметь поддерживаемую схему — в форматах JSON, Avro или Protobuf.
Если вы используете наш пример набора данных для тестирования, убедитесь, что заданы следующие параметры:
  • value.converter.schemas.enable - установите false, так как мы используем Schema Registry. Установите true, если вы встраиваете схему в каждое сообщение.
  • key.converter - установите “org.apache.kafka.connect.storage.StringConverter”. Мы используем ключи String.
  • value.converter - установите “io.confluent.connect.json.JsonSchemaConverter”.
  • value.converter.schema.registry.url - укажите URL сервера схем вместе с учётными данными для него через параметр value.converter.schema.registry.basic.auth.user.info.
Примеры файлов конфигурации для примера данных GitHub можно найти здесь, если Connect запущен в автономном режиме, а Kafka размещён в Confluent Cloud.

4. Создайте таблицу ClickHouse

Убедитесь, что таблица создана; если она уже существует после предыдущих примеров, удалите её. Ниже приведён пример, совместимый с сокращённым набором данных GitHub. Обратите внимание, что типы Array и Map в настоящее время не поддерживаются, поэтому здесь они отсутствуют:

5. Запустите Kafka Connect

Запустите Kafka Connect в автономном или распределённом режиме.

6. Добавьте данные в Kafka

Отправьте сообщения в Kafka с помощью предоставленных скрипта и конфигурации. Вам нужно будет изменить github.config, указав в нем учетные данные Kafka. Сейчас скрипт настроен для использования с Confluent Cloud.
Этот скрипт можно использовать, чтобы загрузить любой ndjson‑файл в топик Kafka. При этом он попытается автоматически определить схему. Пример конфигурации вставляет только 10 тыс. сообщений — измените здесь при необходимости. Эта конфигурация также удаляет из набора данных все несовместимые поля типа Array при вставке в Kafka. Это необходимо, чтобы коннектор JDBC мог преобразовывать сообщения в операторы INSERT. Если вы используете собственные данные, убедитесь, что либо передаёте схему с каждым сообщением (установив _value.converter.schemas.enable _в true), либо что ваш клиент публикует сообщения со ссылкой на схему в registry. Kafka Connect должен начать читать сообщения и вставлять строки в ClickHouse. Обратите внимание, что предупреждения вида “[JDBC Compliant Mode] Transaction isn’t supported.” ожидаемы и их можно игнорировать. Простой запрос к целевой таблице “Github” должен подтвердить вставку данных.
Последнее изменение 25 июня 2026 г.