Клиентская библиотека Java для взаимодействия с сервером базы данных через его протоколы. Текущая реализация поддерживает только HTTP-интерфейс.
Библиотека предоставляет собственный API для отправки запросов на сервер. Также библиотека содержит инструменты для работы с различными бинарными форматами данных (RowBinary* & Native*).
Для аутентификации с помощью токена доступа или Bearer-токена (например, JWT) необходимо задать токен, вызвав Аутентификация с помощью SSL-сертификата клиента требует указания имени пользователя, включения SSL-аутентификации, а также задания клиентского сертификата и клиентского ключа посредством вызовов
приведёт к следующему значению Приложение может задать собственный HTTP-заголовок ⚠️ Если параметры задаются через метод Важно: если параметры задаются через Чтобы настроить заголовок для отдельной операции, задайте его в Все последующие запросы через экземпляр ПараметрыПараметрыПараметрыПараметрыПараметрыПараметрыПараметрыПараметрыМетоды Подходы к интеграцииОбсервабилити можно интегрировать в приложения двумя основными способами:V2: вставка данных в формате TSV.
Setup
- Maven Central (веб-страница проекта): https://mvnrepository.com/artifact/com.clickhouse/client-v2
- Ночные сборки (ссылка на репозиторий): https://central.sonatype.com/repository/maven-snapshots/
- Maven
- Gradle (Kotlin)
- Gradle
Инициализация
Объект Client инициализируется с помощьюcom.clickhouse.client.api.Client.Builder#build(). Каждый клиент имеет собственный контекст, и между клиентами не разделяются объекты.
Builder предоставляет методы конфигурации для удобной настройки.Пример:showLineNumbers
Client реализует AutoCloseable и должен быть закрыт, когда больше не нужен.Аутентификация
Аутентификация настраивается для каждого клиента на этапе инициализации. Поддерживаются три метода аутентификации: по паролю, по токену доступа, по SSL-сертификату клиента.Аутентификация по паролю требует указания имени пользователя и пароля через вызовыsetUsername(String) и setPassword(String):showLineNumbers
useBearerTokenAuth(String) (или setAccessToken(String) для необработанных токенов доступа):showLineNumbers
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"]})
- получить CN из сертификата пользователя —
Пул соединений
Client использует Apache HttpClient 5 с внутренним пулом HTTP-соединений. Каждая операция берёт соединение из пула, отправляет запрос, получает ответ в потоковом режиме и возвращает соединение в пул.Основные настройки пула соединений в Client.Builder:Рекомендуемая конфигурация пула соединений
showLineNumbers
Конфигурация
Все настройки определяются методами экземпляра (они же методы конфигурации), которые чётко задают область видимости и контекст каждого значения. Основные параметры конфигурации определяются в одной области видимости (клиента или операции) и не переопределяют друг друга.Конфигурация задаётся при создании клиента. См.com.clickhouse.client.api.Client.Builder.Конфигурация клиента
- Подключение & конечные точки
- Аутентификация
- Тайм-ауты & повторные попытки
- Параметры сокета
- Сжатие
- SSL/Безопасность
- Прокси
- HTTP & заголовки
- Настройки сервера
- Часовой пояс
- Дополнительно
Идентификация клиента
В журнале запросов есть два поля, по которым можно определить приложение, из которого был отправлен запрос: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: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)
- 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
Объект ответа, содержащий результат выполнения запроса. Доступен только в том случае, если клиент получил ответ от сервера.Этот объект следует закрыть как можно скорее, чтобы освободить соединение, поскольку его нельзя использовать повторно, пока не будут полностью прочитаны все данные из предыдущего ответа.
Примеры
- Пример кода доступен в репозитории
- Справочник по Spring Service реализации
Общий 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для доступа к данным.
Чтение массивов
МетодыClickHouseBinaryFormatReadergetList(...)— читает любойArray(...)какList<T>. Хороший вариант по умолчанию для чтения с гибкой типизацией. Поддерживает вложенные массивы.getByteArray(...),getShortArray(...),getIntArray(...),getLongArray(...),getFloatArray(...),getDoubleArray(...),getBooleanArray(...)— лучше всего подходят для одномерных массивов значений, совместимых с примитивными типами.getStringArray(...)— дляArray(String)(и значений перечисления, представленных в виде имён).getObjectArray(...)— универсальный вариант дляArray(...)с любым типом элементов, включая вложенные массивы. Используйте для чтения массивов с Nullable-значениями и вложенных массивов.
GenericRecordgetList(...)— читает любойArray(...)какList<T>. Хороший вариант по умолчанию для чтения с гибкой типизацией. Поддерживает вложенные массивы.getByteArray(...),getShortArray(...),getIntArray(...),getLongArray(...),getFloatArray(...),getDoubleArray(...),getBooleanArray(...)— лучше всего подходят для одномерных массивов значений, совместимых с примитивными типами.getStringArray(...)— дляArray(String)(и значенийenum, представленных в виде имён).getObjectArray(...)— универсальный вариант дляArray(...)с любым типом элементов, включая вложенные массивы. Используйте для чтения массивов с Nullable-значениями и вложенных массивов.
Обсервабилити и мониторинг
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 (например, число доступных и арендованных соединений, число запросов в ожидании и время создания соединения) кMeterRegistryMicrometer.
OpenTelemetrySpanRecorder и MicrometerMetricsRecorder входят в пакет client-v2. Однако для их работы библиотеки OpenTelemetry API (io.opentelemetry:opentelemetry-api) и Micrometer (io.micrometer:micrometer-core) должны присутствовать в пути поиска классов приложения во время выполнения. Основной артефакт клиента не включает эти сторонние зависимости и не подключает их транзитивно. Приложения, использующие трассировку OpenTelemetry или метрики Micrometer, должны явно объявлять эти зависимости в конфигурации сборки проекта (pom.xml или build.gradle).Пример конфигурации Builder- Агент OpenTelemetry и глобальная автоконфигурация:
- Для приложений, использующих Java-агент OpenTelemetry или глобальную автоконфигурацию SDK, создавайте экземпляры
OpenTelemetrySpanRecorderиMicrometerMetricsRecorderс помощью конструкторов по умолчанию (без аргументов). - Конструкторы по умолчанию автоматически привязываются к
GlobalOpenTelemetry.get()и кMetrics.globalRegistryиз Micrometer.
- Для приложений, использующих Java-агент OpenTelemetry или глобальную автоконфигурацию SDK, создавайте экземпляры
- Явная интеграция на уровне клиента:
- Передавайте явно созданные экземпляры
OpenTelemetry,Tracerили MicrometerMeterRegistryнапрямую в конструкторы рекордеров. - Оптимальный вариант для работы с несколькими изолированными клиентами или мультитенантными сервисами, у которых свои, независимые приёмники телеметрии.
- Передавайте явно созданные экземпляры
Отправляемые метрики
Операционные метрики
Метрики, экспортируемые через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 создаёт спаны двух типов, организованные в иерархию «родитель — дочерний элемент»:- Спан операции: представляет высокоуровневую операцию клиента (
QUERY <database>илиINSERT <database>.<table_name>). Запускается в контексте трассировки текущего потока (Context.current()), благодаря чему операции с базой данных встраиваются в активный спан трассировки вызывающего кода. - Спан транспортного запроса: представляет отдельную попытку выполнения транспортного 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 перечислены все имена параметров конфигурации.В таблице ниже показано, какие старые параметры поддерживаются в новом клиенте и что они означают теперь.Обозначения: ✔ = поддерживается, ✗ = удалено- Подключение и аутентификация
- SSL и безопасность
- Параметры сокета
- Сжатие
- Прокси
- Тайм-ауты & повторные попытки
- Часовой пояс
- Буферы & производительность
- Потоки & асинхронность
- HTTP & заголовки
- Формат & запрос
- Обнаружение узлов & балансировка нагрузки
- Прочее
Общие различия
- Клиент V2 использует меньше проприетарных классов, что повышает переносимость. Например, V2 работает с любой реализацией
java.io.InputStreamдля записи данных на сервер. - Настройка
asyncв Client V2 по умолчанию имеет значениеoff. Это означает отсутствие дополнительных потоков и больший контроль приложения над клиентом. Для большинства сценариев использования эта настройка должна оставатьсяoff. При включенииasyncдля запроса создаётся отдельный поток. Это имеет смысл только при использовании исполнителя, управляемого приложением (см.com.clickhouse.client.api.Client.Builder#setSharedOperationExecutor)
Запись данных
- используйте любую реализацию
java.io.InputStream. V1com.clickhouse.data.ClickHouseInputStreamподдерживается, но использовать её НЕ рекомендуется. - Как только обнаруживается конец входного потока, он обрабатывается соответствующим образом. Перед этим необходимо закрыть выходной поток запроса.
- нужно вызвать только один метод. Нет необходимости создавать дополнительный объект запроса.
- Поток с телом запроса автоматически закрывается после копирования всех данных.
- Доступен новый низкоуровневый 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предоставляет доступ к данным и поддерживает некоторые преобразования.