Перейти к основному содержанию
Клиентская библиотека Java для взаимодействия с сервером базы данных через его протоколы. Текущая реализация поддерживает только HTTP-интерфейс. Библиотека предоставляет собственный API для отправки запросов на сервер. Также библиотека содержит инструменты для работы с различными бинарными форматами данных (RowBinary* & Native*).

Setup



Инициализация

Объект Client инициализируется с помощью com.clickhouse.client.api.Client.Builder#build(). Каждый клиент имеет собственный контекст, и между клиентами не разделяются объекты. Builder предоставляет методы конфигурации для удобной настройки.Пример:
showLineNumbers
Client реализует AutoCloseable и должен быть закрыт, когда больше не нужен.

Аутентификация

Аутентификация настраивается для каждого клиента на этапе инициализации. Поддерживаются три метода аутентификации: по паролю, по токену доступа, по SSL-сертификату клиента.Аутентификация по паролю требует указания имени пользователя и пароля через вызовы setUsername(String) и setPassword(String):
showLineNumbers
Для аутентификации с помощью токена доступа или Bearer-токена (например, JWT) необходимо задать токен, вызвав useBearerTokenAuth(String) (или setAccessToken(String) для необработанных токенов доступа):
showLineNumbers
Аутентификация с помощью SSL-сертификата клиента требует указания имени пользователя, включения SSL-аутентификации, а также задания клиентского сертификата и клиентского ключа посредством вызовов setUsername(String), useSSLAuthentication(boolean), setClientCertificate(String) и setClientKey(String) соответственно:
showLineNumbers
Аутентификацию по SSL бывает сложно диагностировать в продакшне, потому что многие ошибки из библиотек SSL дают недостаточно информации. Например, если сертификат клиента и ключ не совпадают, сервер немедленно разорвет соединение (в случае HTTP это произойдет на этапе установления соединения, когда HTTP-запросы еще не отправляются, поэтому ответ не будет отправлен).Пожалуйста, используйте такие инструменты, как openssl, чтобы проверить сертификаты и ключи:
  • проверить целостность ключа: openssl rsa -in [key-file.key] -check -noout
  • проверить, что сертификат клиента содержит CN, соответствующий пользователю:
    • получить CN из сертификата пользователя — openssl x509 -noout -subject -in [user.cert]
    • убедиться, что в базе данных задано то же значение: select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate' (запрос выведет auth_params с чем-то вроде {"common_names":["some_user"]})

Пул соединений

Client использует Apache HttpClient 5 с внутренним пулом HTTP-соединений. Каждая операция берёт соединение из пула, отправляет запрос, получает ответ в потоковом режиме и возвращает соединение в пул.Основные настройки пула соединений в Client.Builder:

Рекомендуемая конфигурация пула соединений

showLineNumbers

Конфигурация

Все настройки определяются методами экземпляра (они же методы конфигурации), которые чётко задают область видимости и контекст каждого значения. Основные параметры конфигурации определяются в одной области видимости (клиента или операции) и не переопределяют друг друга.Конфигурация задаётся при создании клиента. См. com.clickhouse.client.api.Client.Builder.

Конфигурация клиента


Идентификация клиента

В журнале запросов есть два поля, по которым можно определить приложение, из которого был отправлен запрос: client_name и http_user_agent. Нативный TCP-протокол использует client_name для идентификации приложения. HTTP-протокол использует http_user_agent для идентификации приложения. В билдере клиента есть метод setClientName, который задаёт корректные значения для обоих протоколов. Поле http_user_agent задаётся в соответствии с общепринятым форматом заголовка User-Agent: application-name[/version] [(operating-system; architecture; ...)]. Этот набор значений повторяется для каждого уровня: приложение, клиентская библиотека, HTTP-клиентская библиотека. Значение, заданное методом setClientName, идёт первым в списке.Например:
showLineNumbers
приведёт к следующему значению http_user_agent:
Приложение может задать собственный HTTP-заголовок User-Agent для идентификации. При этом строка clickhouse-java-v2/0.9.6-SNAPSHOT будет добавлена в конец заголовка.

Идентификация операции

Log запросов содержит ещё два поля — query_id и log_comment, — которые можно использовать для идентификации операции и добавления дополнительных сведений в log запросов.query_id — уникальный идентификатор операции. Его можно задать в приложении, вызвав метод setQueryId класса QuerySettings.
showLineNumbers
log_comment — это комментарий, который можно добавить в лог запросов. Его можно задать в приложении, вызвав метод logComment класса QuerySettings.
showLineNumbers

Настройки сервера

Настройки на стороне сервера можно задать на уровне клиента один раз при создании (см. метод serverSetting класса Builder) и на уровне операции (см. serverSetting для класса настроек операции).
showLineNumbers
⚠️ Если параметры задаются через метод setOption (будь то Client.Builder или класс настроек операции), имя настройки сервера должно иметь префикс clickhouse_setting_. В этом случае может пригодиться com.clickhouse.client.api.ClientConfigProperties#serverSetting().

Пользовательские HTTP-заголовки

Пользовательские HTTP-заголовки можно задать для всех операций (на уровне клиента) или для отдельной операции (на уровне операции). Настройки операции переопределяют одноимённые заголовки, заданные на уровне клиента.
showLineNumbers
Важно: если параметры задаются через setOption (в Client.Builder или в классе настроек операции), имя заголовка должно начинаться с префикса http_header_. Такой ключ формирует ClientConfigProperties.httpHeader(String). Поскольку имя заголовка — это обычный строковый ключ, оно должно быть записано в едином регистре, иначе дублирующиеся значения приведут к неопределённому поведению. ClientConfigProperties.httpHeader(String) решает эту проблему.
showLineNumbers

Возможности ClickHouse Cloud

Возможности, доступные при подключении к ClickHouse Cloud.

Маршрутизация с учётом реплик (CLOUD)

ClickHouse Cloud может закреплять связанные HTTP-запросы за одной репликой. Передайте заголовок X-ClickHouse-Replica-Tag, и прокси Cloud будет направлять все запросы с одинаковой меткой на одну и ту же реплику. Это полезно для объектов уровня сеанса, например временных таблиц, для повторного использования локального кэша реплики, а также для обеспечения согласованности чтения после записи. Подробнее: https://clickhouse.com/docs/products/cloud/features/infrastructure/replica-aware-routing.Что задать: HTTP-заголовок X-ClickHouse-Replica-Tag (com.clickhouse.client.api.http.ClickHouseHttpProto.HEADER_REPLICA_TAG). Используйте одно и то же значение метки для всех запросов, которые должны обрабатываться одной репликой.
showLineNumbers
Чтобы настроить заголовок для отдельной операции, задайте его в QuerySettings, InsertSettings или CommandSettings, а не в построителе клиента.

JWT-аутентификация (CLOUD)

JWT-аутентификация позволяет аутентифицировать пользователей с помощью JSON Web Tokens (JWT) в ClickHouse Cloud. Вместо заранее созданных пользователей базы данных ClickHouse динамически создаёт эфемерных пользователей на основе утверждений, встроенных в каждый токен.

Начальная настройка

Чтобы настроить начальную JWT-аутентификацию на клиенте, используйте useBearerTokenAuth(token) (метод автоматически добавляет префикс Bearer_. (см. документацию по HTTP-интерфейсу ) при создании экземпляра Client:
showLineNumbers
useBearerTokenAuth(token) автоматически добавляет префикс Bearer к значению HTTP-заголовка Authorization.

Обновление токена во время выполнения

Поскольку JWT недолговечны, а эфемерные пользователи существуют лишь в течение времени жизни токена, новые JWT-токены следует задавать до истечения срока действия текущего токена, чтобы ни одна операция не завершилась ошибкой.Bearer-токен можно обновить в существующем экземпляре Client во время выполнения, не пересоздавая клиент:
showLineNumbers
Все последующие запросы через экземпляр Client будут использовать обновлённый JWT-токен.

Общие определения

ClickHouseFormat

Перечисление поддерживаемых форматов. Включает все форматы, поддерживаемые ClickHouse.
  • raw - пользователь должен перекодировать необработанные данные
  • full - клиент может самостоятельно перекодировать данные и принимает поток необработанных данных
  • - - операция не поддерживается ClickHouse для этого формата
Эта версия клиента поддерживает:

API вставки

insert(String tableName, InputStream data, ClickHouseFormat format)

Принимает данные в виде InputStream байтов в указанном формате. Предполагается, что data закодированы в формате format.Сигнатуры
ПараметрыtableName — имя целевой таблицы.data — входной поток закодированных данных.format — формат, в котором закодированы данные.settings - параметры запроса.Возвращаемое значениеFuture типа InsertResponse — результат операции и дополнительная информация, например метрики на стороне сервера.Примеры
showLineNumbers

insert(String tableName, List<?> data, InsertSettings settings)

Отправляет запрос на запись в базу данных. Список объектов преобразуется в эффективный формат и затем отправляется на сервер. Класс элементов списка должен быть заранее зарегистрирован с помощью метода register(Class, TableSchema).Сигнатуры
ПараметрыtableName — имя целевой таблицы.data — коллекция объектов DTO (Data Transfer Object).settings - параметры запроса.Возвращаемое значениеFuture типа InsertResponse — результат операции и дополнительная информация, например метрики на стороне сервера.Примеры
showLineNumbers

InsertSettings

Параметры для операций вставки.Методы конфигурации

InsertResponse

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

API запросов

Выбор форматаКлиент предоставляет прозрачный доступ к потоку ответов сервера. Пользователь может указать в запросе любой формат ClickHouse и читать данные через InputStream из объекта QueryResponse. Формат можно задать следующими способами:
  • QuerySettings#setFormat() — задаёт заголовок формата в запросе.
  • В секции FORMAT в самом запросе.
  • Настройка сервера default_format (/reference/settings/session-settings/default#default_format)
Поведение различается в зависимости от версии ClickHouse и клиента:
  • Client < 0.11.0 & ClickHouse < 26.8 — предложение FORMAT имеет приоритет над заголовком формата в запросе.
  • Client > 0.11.0 & ClickHouse > 26.8 — заголовок запроса имеет приоритет над предложением FORMAT.
    • Если формат не указан в QuerySettings, клиент задаёт заголовок, из-за чего формат нельзя переопределить в запросе.
  • Начиная с версии 0.11.0, клиент задаёт значение format по умолчанию на уровне клиента, а не на уровне операции. Благодаря этому существующий код работает без изменений, а в новом коде можно использовать предложение FORMAT, установив для format на уровне клиента значение null.

query(String sqlQuery)

Отправляет sqlQuery как есть. Формат ответа задаётся настройками запроса. QueryResponse будет содержать ссылку на поток ответа, который должен быть прочитан (consumed) ридер-ом для поддерживаемого формата.Сигнатуры
ПараметрыsqlQuery — один SQL-оператор. Запрос отправляется на сервер как есть.settings - параметры запроса.Возвращаемое значениеFuture типа QueryResponse — результирующий набор данных и дополнительная информация, например метрики на стороне сервера. Объект Response следует закрыть после обработки набора данных.Примеры

query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)

Отправляет sqlQuery без изменений. Также отправляет параметры запроса, чтобы сервер мог скомпилировать SQL-выражение.Сигнатуры
ПараметрыsqlQuery — SQL-выражение с плейсхолдерами {}.queryParams — набор переменных для подстановки в SQL-выражение на сервере.settings - параметры запроса.Возвращаемое значениеFuture типа QueryResponse — результирующий набор данных и дополнительная информация, например метрики на стороне сервера. Объект Response следует закрыть после обработки набора данных.Примеры
showLineNumbers

queryAll(String sqlQuery)

Запрашивает данные в формате RowBinaryWithNamesAndTypes. Возвращает результат в виде коллекции. Производительность чтения аналогична reader, однако для хранения всего набора данных требуется больше памяти.Сигнатуры
ПараметрыsqlQuery — SQL-выражение для запроса данных на сервере.Возвращаемое значениеПолный набор данных, представленный в виде списка объектов GenericRecord, обеспечивающих построчный доступ к результирующим данным.Примеры
showLineNumbers

QuerySettings

Параметры конфигурации для операций с запросами.Методы конфигурации

QueryResponse

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

Примеры

Общий API

getTableSchema(String table)

Загружает схему таблицы для table.Сигнатуры
Параметрыtable - имя таблицы, для которой нужно получить данные схемы.database — база данных, в которой определена целевая таблица.Возвращаемое значениеВозвращает объект TableSchema со списком столбцов таблицы.

getTableSchemaFromQuery(String sql)

Извлекает схему из SQL-оператора.Сигнатуры
Параметрыsql - оператор SQL “SELECT”, схему которого необходимо вернуть.Возвращаемое значениеВозвращает объект TableSchema со столбцами, соответствующими выражению sql.

TableSchema

register(Class<?> clazz, TableSchema schema)

Компилирует слой сериализации и десериализации для Java-класса, используемого при записи/чтении данных с помощью schema. Метод создаёт сериализатор и десериализатор для пары геттер/сеттер и соответствующего столбца. Соответствие столбца определяется путём извлечения его имени из имени метода. Например, getFirstName будет соответствовать столбцу first_name или firstname.Сигнатуры
Параметрыclazz — класс, представляющий POJO, используемый для чтения/записи данных.schema — схема данных для сопоставления со свойствами POJO.Примеры
showLineNumbers

Примеры использования

Полный код примеров хранится в репозитории в папке ‘example`:
  • client-v2 — основной набор примеров.
  • demo-service — пример использования клиента в приложении Spring Boot.
  • demo-kotlin-service — пример использования клиента в приложении на Ktor (Kotlin).

Чтение данных

Есть два распространённых способа чтения данных:
  • метод query(), который возвращает низкоуровневый объект QueryResponse, содержащий InputStream с данными. Обычно используется вместе с ClickHouseBinaryFormatReader для потокового чтения, но может использоваться и с любой другой пользовательской реализацией ридера. QueryResponse также предоставляет доступ к метаданным результирующего набора и метрикам.
  • Метод queryAll() и использование GenericRecord для удобного доступа к строкам. В этом случае весь результирующий набор загружается в память.
  • Метод queryRecords(), который возвращает com.clickhouse.client.api.query.Records, — это итератор по объектам GenericRecord. Этот метод использует потоковый подход (данные не загружаются в память) и GenericRecord для доступа к данным.
Примечание: стриминговый подход требует быстрого чтения данных, иначе может возникнуть тайм-аут записи на сервере, так как данные считываются напрямую из сетевого потока.

Чтение массивов

Методы ClickHouseBinaryFormatReader
  • getList(...) — читает любой Array(...) как List<T>. Хороший вариант по умолчанию для чтения с гибкой типизацией. Поддерживает вложенные массивы.
  • getByteArray(...), getShortArray(...), getIntArray(...), getLongArray(...), getFloatArray(...), getDoubleArray(...), getBooleanArray(...) — лучше всего подходят для одномерных массивов значений, совместимых с примитивными типами.
  • getStringArray(...) — для Array(String) (и значений перечисления, представленных в виде имён).
  • getObjectArray(...) — универсальный вариант для Array(...) с любым типом элементов, включая вложенные массивы. Используйте для чтения массивов с Nullable-значениями и вложенных массивов.
Для всех методов доступны перегрузки по индексу и по имени. Индексация начинается с 1. Перегрузки по индексу обеспечивают прямой доступ к столбцу. Методы по имени требуют поиска по индексу при каждом обращении.
Методы GenericRecord
  • getList(...) — читает любой Array(...) как List<T>. Хороший вариант по умолчанию для чтения с гибкой типизацией. Поддерживает вложенные массивы.
  • getByteArray(...), getShortArray(...), getIntArray(...), getLongArray(...), getFloatArray(...), getDoubleArray(...), getBooleanArray(...) — лучше всего подходят для одномерных массивов значений, совместимых с примитивными типами.
  • getStringArray(...) — для Array(String) (и значений enum, представленных в виде имён).
  • getObjectArray(...) — универсальный вариант для Array(...) с любым типом элементов, включая вложенные массивы. Используйте для чтения массивов с Nullable-значениями и вложенных массивов.
Для всех методов доступны перегрузки по индексу и по имени. Индексация начинается с 1. Перегрузки по индексу обеспечивают прямой доступ к столбцу. Методы по имени требуют поиска по индексу при каждом обращении.

Обсервабилити и мониторинг

Java-клиент ClickHouse (V2) предоставляет встроенные возможности обсервабилити, основанные на семантических соглашениях OpenTelemetry и метриках Micrometer. Клиент позволяет отслеживать длительность операций, пропускную способность, повторные попытки, статистику выполнения на сервере, состояние пула соединений и спаны распределённой трассировки.Полноценный пример приложения Spring Boot, построенного по принципам продакшн-приложений и демонстрирующего конфигурацию Клиента V2, использование пула соединений, передачу контекста трассировки через границы @Async и полную интеграцию телеметрии, см. в модуле examples/demo-spring-service этого репозитория.

API обсервабилити в Client Builder

Client.Builder предоставляет три основных метода для настройки обсервабилити и сбора метрик:
  • setMetricsRecorder(MetricsRecorder recorder): регистрирует регистратор метрик для экспорта эксплуатационных метрик (длительность, число вхождений, повторные попытки, ошибки). Если не задан явно, по умолчанию используется DefaultMetricsRecorder.NOOP.
  • setSpanRecorder(SpanRecorder recorder): регистрирует регистратор спанов для распределённой трассировки (спаны операций и спаны транспортных запросов). Если не задан явно, по умолчанию используется DefaultSpanRecorder.NOOP.
  • registerClientMetrics(Object registry, String groupName): привязывает метрики пула соединений Apache HttpClient (например, число доступных и арендованных соединений, число запросов в ожидании и время создания соединения) к MeterRegistry Micrometer.
Требования к зависимостямВстроенные классы OpenTelemetrySpanRecorder и MicrometerMetricsRecorder входят в пакет client-v2. Однако для их работы библиотеки OpenTelemetry API (io.opentelemetry:opentelemetry-api) и Micrometer (io.micrometer:micrometer-core) должны присутствовать в пути поиска классов приложения во время выполнения. Основной артефакт клиента не включает эти сторонние зависимости и не подключает их транзитивно. Приложения, использующие трассировку OpenTelemetry или метрики Micrometer, должны явно объявлять эти зависимости в конфигурации сборки проекта (pom.xml или build.gradle).Пример конфигурации Builder
Подходы к интеграцииОбсервабилити можно интегрировать в приложения двумя основными способами:
  1. Агент OpenTelemetry и глобальная автоконфигурация:
    • Для приложений, использующих Java-агент OpenTelemetry или глобальную автоконфигурацию SDK, создавайте экземпляры OpenTelemetrySpanRecorder и MicrometerMetricsRecorder с помощью конструкторов по умолчанию (без аргументов).
    • Конструкторы по умолчанию автоматически привязываются к GlobalOpenTelemetry.get() и к Metrics.globalRegistry из Micrometer.
  2. Явная интеграция на уровне клиента:
    • Передавайте явно созданные экземпляры OpenTelemetry, Tracer или Micrometer MeterRegistry напрямую в конструкторы рекордеров.
    • Оптимальный вариант для работы с несколькими изолированными клиентами или мультитенантными сервисами, у которых свои, независимые приёмники телеметрии.

Отправляемые метрики

Операционные метрики

Метрики, экспортируемые через MetricsRecorder, соответствуют семантическим соглашениям OpenTelemetry для метрик клиентов баз данных (MetricName и MetricAttribute):

Атрибуты / метки метрик

Счётчики (meters), создаваемые MicrometerMetricsRecorder, содержат метки с низкой мощностью (MetricAttribute):

Метрики пула соединений

При вызове registerClientMetrics(meterRegistry, "groupName") в Micrometer регистрируются метрики типа Gauge для пула HTTP-соединений:
  • httpcomponents.httpclient.pool.total.max: настроенное максимально допустимое количество постоянных соединений.
  • httpcomponents.httpclient.pool.total.connections (с меткой state="available" или state="leased"): активные соединения в пуле.
  • httpcomponents.httpclient.pool.total.pending: количество запросов на соединение, ожидающих освобождения соединения.
  • httpcomponents.httpclient.pool.route.max.default: настроенное по умолчанию максимальное количество соединений на маршрут.
  • httpcomponents.httpclient.connect.time: скользящее среднее время установления соединения.

API метрик ответа

Помимо средств записи метрик, подробная статистика выполнения доступна непосредственно в объектах ответа (QueryResponse, InsertResponse) через OperationMetrics:

Регистрируемые спаны

Трассировка в Клиенте V2 создаёт спаны двух типов, организованные в иерархию «родитель — дочерний элемент»:
  1. Спан операции: представляет высокоуровневую операцию клиента (QUERY <database> или INSERT <database>.<table_name>). Запускается в контексте трассировки текущего потока (Context.current()), благодаря чему операции с базой данных встраиваются в активный спан трассировки вызывающего кода.
  2. Спан транспортного запроса: представляет отдельную попытку выполнения транспортного HTTP-запроса (POST). Создаётся как дочерний спан соответствующего спана операции. При каждой повторной попытке внутри спана операции создаётся новый спан транспортного запроса.

Атрибуты спана

Спаны содержат стандартные атрибуты OpenTelemetry (SpanAttribute):
Распространение контекста через асинхронные границы: поскольку Client V2 наследует Context.current(), операции, запущенные в потоках с активным спаном трассировки, автоматически присоединяются к трассе. При передаче задач между пулами потоков (например, через Spring @Async или пользовательский ExecutorService) явно распространяйте контекст OpenTelemetry:

Разработка пользовательских рекордеров

Приложения, использующие собственные системы обсервабилити, могут реализовать пользовательские рекордеры, расширив DefaultMetricsRecorder (для метрик) или DefaultSpanRecorder (для трассировки).
  • DefaultMetricsRecorder: базовая реализация MetricsRecorder. Переопределите нужные функции обратного вызова, например recordQuerySuccess или recordQueryFailure. С помощью MetricsSupport.DEFAULT можно получить стандартные имена метрик (MetricName), единицы измерения и словари атрибутов (MetricAttribute).
  • DefaultSpanRecorder: базовая реализация SpanRecorder. Переопределите функции обратного вызова, создающие спаны, например startQuerySpan, startInsertSpan или startRequestSpan. С помощью SpanSupport.DEFAULT можно вычислить стандартные имена спанов OpenTelemetry и их атрибуты (SpanAttribute).
Эталонные реализации для продакшна см. во встроенных классах клиентов:
  • com.clickhouse.client.api.observability.otel.OpenTelemetrySpanRecorder (интеграция с OpenTelemetry для трассировки)
  • com.clickhouse.client.api.observability.micrometer.MicrometerMetricsRecorder (интеграция с Micrometer для метрик)

Руководство по миграции

Старый клиент (V1) использовал com.clickhouse.client.ClickHouseClient#builder в качестве точки входа. Новый клиент (V2) использует аналогичный подход с com.clickhouse.client.api.Client.Builder. Основные отличия:
  • Для получения реализации service loader не используется. com.clickhouse.client.api.Client — это класс-фасад для любых реализаций, которые могут появиться в будущем.
  • меньше источников конфигурации: один передаётся билдеру, а другой — через настройки операции (QuerySettings, InsertSettings). В предыдущей версии конфигурация задавалась для каждого узла, а в некоторых случаях также загружались переменные окружения.

Соответствие параметров конфигурации

В V1 есть 3 класса enum, связанных с конфигурацией:
  • com.clickhouse.client.config.ClickHouseDefaults — параметры конфигурации, которые обычно задаются в большинстве случаев. Например, USER и PASSWORD.
  • com.clickhouse.client.config.ClickHouseClientOption — параметры конфигурации, относящиеся непосредственно к клиенту. Например, HEALTH_CHECK_INTERVAL.
  • com.clickhouse.client.http.config.ClickHouseHttpOption — параметры конфигурации, характерные для HTTP-интерфейса. Например, RECEIVE_QUERY_PROGRESS.
Они были разработаны для группировки параметров и обеспечения чёткого разделения. Однако в некоторых случаях это приводило к путанице (например, есть ли разница между com.clickhouse.client.config.ClickHouseDefaults#ASYNC и com.clickhouse.client.config.ClickHouseClientOption#ASYNC). Новый клиент V2 использует com.clickhouse.client.api.Client.Builder как единый словарь всех возможных параметров конфигурации клиента. В классе com.clickhouse.client.api.ClientConfigProperties перечислены все имена параметров конфигурации.В таблице ниже показано, какие старые параметры поддерживаются в новом клиенте и что они означают теперь.Обозначения: ✔ = поддерживается, ✗ = удалено

Общие различия

  • Клиент V2 использует меньше проприетарных классов, что повышает переносимость. Например, V2 работает с любой реализацией java.io.InputStream для записи данных на сервер.
  • Настройка async в Client V2 по умолчанию имеет значение off. Это означает отсутствие дополнительных потоков и больший контроль приложения над клиентом. Для большинства сценариев использования эта настройка должна оставаться off. При включении async для запроса создаётся отдельный поток. Это имеет смысл только при использовании исполнителя, управляемого приложением (см. com.clickhouse.client.api.Client.Builder#setSharedOperationExecutor)

Запись данных

  • используйте любую реализацию java.io.InputStream. V1 com.clickhouse.data.ClickHouseInputStream поддерживается, но использовать её НЕ рекомендуется.
  • Как только обнаруживается конец входного потока, он обрабатывается соответствующим образом. Перед этим необходимо закрыть выходной поток запроса.
V1: вставка данных в формате TSV.
V2: вставка данных в формате TSV.
  • нужно вызвать только один метод. Нет необходимости создавать дополнительный объект запроса.
  • Поток с телом запроса автоматически закрывается после копирования всех данных.
  • Доступен новый низкоуровневый API com.clickhouse.client.api.Client#insert(java.lang.String, java.util.List<java.lang.String>, com.clickhouse.client.api.DataStreamWriter, com.clickhouse.data.ClickHouseFormat, com.clickhouse.client.api.insert.InsertSettings). com.clickhouse.client.api.DataStreamWriter предназначен для реализации пользовательской логики записи данных. Например, для чтения данных из очереди.

Чтение данных

  • По умолчанию данные читаются в формате RowBinaryWithNamesAndTypes. Сейчас при необходимости привязки данных поддерживается только этот формат.
  • Данные можно считать как набор записей с помощью метода List<GenericRecord> com.clickhouse.client.api.Client#queryAll(java.lang.String). Он считывает данные в память и закрывает соединение. Никакой дополнительной обработки не требуется. GenericRecord предоставляет доступ к данным и поддерживает некоторые преобразования.