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

Создание интеграций с ClickHouse

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

Ингестия​

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

Вариант 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 (все клиенты) и native TCP (только клиенты Go и C++)
  • Аутентификация: по умолчанию имя пользователя и пароль передаются через TLS; mTLS и аутентификация по клиентскому SSL-сертификату поддерживаются всеми основными клиентами
  • Формат данных обычно остаётся деталью реализации. Клиенты преобразуют типы среды выполнения в формат ClickHouse Native или RowBinary. Если вы уже формируете Arrow, Parquet, JSONEachRow или другой формат, большинство клиентов предоставляют API для сырых байтов с предварительно сериализованными данными
  • Для высокой пропускной способности используйте батчи по 10K–100K строк и ориентируйтесь на одну вставку в секунду как на верхнюю границу для синхронных вставок. Если пакетирование на стороне клиента непрактично, используйте асинхронные вставки, чтобы перенести формирование батчей на сервер

См. также: Массовые вставки.

Потребление​

И HTTP, и нативный TCP передают запросы. Нативный протокол двоичный и создаёт меньше накладных расходов. 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 богатая система типов: массивы, кортежи, 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, вы можете запросить дополнительные кредиты для разработки через партнерский портал.