Перейти к основному содержанию
Эта страница поможет вам сориентироваться в возможностях интеграции, чтобы вы могли определить объём работ по ингестии и потреблению. Для проверки и публикации перейдите к разделам Тестирование вашей интеграции и Документирование вашей интеграции.

​
Ингестия

Есть два способа доставки данных в ClickHouse. Выберите подходящий в зависимости от того, должен ли ваш продукт самостоятельно управлять контуром ингестии или делегировать это.

​
Path A: ClickPipes (управляемый сервис, Только в ClickHouse Cloud)

Если вы предпочитаете не создавать и не поддерживать инфраструктуру для ингестии данных, ClickPipes — это управляемый сервис, который забирает данные из источников ваших клиентов и загружает их в их сервис ClickHouse Cloud. ClickPipes берёт на себя масштабирование, распараллеливание, повторные попытки и отчётность о задержках. Сегодня поддерживаются следующие источники:
  • Стриминг: Apache Kafka (включая MSK, Confluent Cloud, Redpanda, Azure Event Hubs, WarpStream), Amazon Kinesis
  • Объектное хранилище: Amazon S3 (и S3-совместимые хранилища), Google Cloud Storage, Azure Blob Storage
  • CDC: PostgreSQL, MySQL, MongoDB, BigQuery

​
Путь B: Самостоятельная ингестия через официальный клиент для языка программирования

Если вы сами управляете конвейером, используйте один из официальных клиентов для языков программирования. Они берут на себя сериализацию, батчинг, TLS, сжатие и работу с пулом соединений. Вы передаёте примитивные типы, а клиент сам формирует формат передачи данных.
  • Официальные клиенты: Python, Go, Java, JavaScript, Rust, C#, C++
  • Оба протокола: HTTP (все клиенты) и нативный TCP (только клиенты Go и C++)
  • Аутентификация: по умолчанию — имя пользователя и пароль через TLS; mTLS и аутентификация по клиентским SSL-сертификатам поддерживаются всеми основными клиентами
  • Формат данных обычно остаётся деталью реализации. Клиенты преобразуют типы среды выполнения в формат ClickHouse Native или RowBinary. Если вы уже формируете Arrow, Parquet, JSONEachRow или другой формат, большинство клиентов предоставляют API для передачи сырых байтов с уже сериализованными данными
  • Для высокой пропускной способности объединяйте 10K–100K строк в батч и ориентируйтесь примерно на одну вставку в секунду как на верхний предел для синхронных вставок. Если батчинг на стороне клиента непрактичен, используйте асинхронные вставки, чтобы перенести батчинг на сервер
См. также: Массовые вставки.

​
Использование

И HTTP, и нативный TCP передают запросы. Native использует бинарный формат и создаёт меньшие накладные расходы. HTTP работает через балансировщики нагрузки и прокси. Оба варианта равноценны; выбирайте исходя из инфраструктуры, а не из различий в возможностях.
  • Прикладной код: используйте те же официальные клиенты для языков программирования, что и для ингестии
  • BI- и SQL-инструменты: ClickHouse поставляет официальный драйвер JDBC v2 (Java) и драйвер ODBC. Tableau, Looker, Power BI, Metabase, Apache Superset и Grafana интегрируются через эти драйверы или специализированные коннекторы, поддерживаемые ClickHouse и партнёрами
  • Формат результатов: обычно за сериализацию отвечают клиенты. Если вашему продукту это требуется, можно запрашивать Arrow, Parquet или другие столбцовые форматы при передаче данных

​
Размер результирующего набора

Большинство аналитических запросов возвращают небольшие результирующие наборы (агрегаты, сводки, top-N), и передача данных по сети редко становится узким местом. Таблицы ClickHouse могут содержать миллиарды строк, а неограниченный SELECT * по большой таблице фактов может передавать терабайты данных. Формируйте запрос на уровне приложения: используйте LIMIT, пагинацию, потоковое чтение и явные списки столбцов. Если вы разрабатываете пользовательскую аналитику, рассматривайте неограниченные результирующие наборы как проблему UX, а не передачи данных. В ClickHouse богатая система типов: Array, Tuple, Map, JSON, Nested, LowCardinality и другие. Официальные клиенты сопоставляют их с идиоматическими типами языка. Если ваш продукт показывает данные ClickHouse конечным пользователям, заранее продумайте стратегию сопоставления типов.

​
Дальнейшие шаги

Выберите подходящий путь и создайте прототип, используя пробную версию ClickHouse Cloud, затем зарегистрируйте свою интеграцию на партнёрском портале.

​
Соглашение о строке User-Agent

HTTP-клиенты должны задавать строку User-Agent, которая идентифицирует вашу интеграцию. ClickHouse разбирает её на стороне сервера, чтобы отслеживать распространение интеграции, собирать телеметрию использования и определять дальнейшее развитие продукта. Формат: 
<app_name>/<app_version> <client_name>/<client_version> (<comment>; <key1>: <value1>; <key2>: <value2>)
Примеры:
  • clickhouse-java/0.8.0
  • my-analytics-app/3.1.2 clickhouse-js/1.2.0 (env: staging; region: us-east-1; lv: node/20.10)
Правила:
  • В имени и версии клиента не должно быть пробелов
  • Если вы добавляете комментарий, он должен идти первым
  • Стандартные ключи метаданных: lv (версия языка или фреймворка), os, arch
  • Клиенты TCP и собственного протокола передают имя и версию клиента через поля протокола, а не через User-Agent
Если вы используете JDBC, см. идентификация клиента, чтобы узнать, как драйвер устанавливает User-Agent и связанные с ним поля.

​
Доступ к песочнице и пробный период

ClickHouse Cloud предлагает бесплатный пробный период для разработки и проверки интеграций. Если вы партнер House Mate, вы можете запросить дополнительные кредиты на разработку через партнерский портал.
Последнее изменение 10 июня 2026 г.