Java-клиент

v0.8+

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

Настройка

Maven Central (веб-страница проекта): https://mvnrepository.com/artifact/com.clickhouse/client-v2
Ночные сборки (ссылка на репозиторий): https://central.sonatype.com/repository/maven-snapshots/
Old Nightly builds artifactory (repository link): https://s01.oss.sonatype.org/content/repositories/snapshots/

Maven
Gradle (Kotlin)
Gradle

<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>client-v2</artifactId>
    <version>0.9.6</version>
</dependency>

// https://mvnrepository.com/artifact/com.clickhouse/client-v2
implementation("com.clickhouse:client-v2:0.9.6")

// https://mvnrepository.com/artifact/com.clickhouse/client-v2
implementation 'com.clickhouse:client-v2:0.9.6'

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

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

Пример:

 Client client = new Client.Builder()
                .addEndpoint("https://clickhouse-cloud-instance:8443/")
                .setUsername(user)
                .setPassword(password)
                .build();

Client реализует интерфейс AutoCloseable, и его следует закрывать, когда он больше не нужен.

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

Аутентификация настраивается для каждого клиента на этапе инициализации. Поддерживаются три метода аутентификации: по паролю, по токену доступа и по клиентскому SSL‑сертификату.

Для аутентификации по паролю необходимо задать имя пользователя и пароль, вызвав методы setUsername(String) и setPassword(String):

 Client client = new Client.Builder()
        .addEndpoint("https://clickhouse-cloud-instance:8443/")
        .setUsername(user)
        .setPassword(password)
        .build();

Для аутентификации по токену доступа необходимо установить токен доступа, вызвав метод setAccessToken(String):

 Client client = new Client.Builder()
        .addEndpoint("https://clickhouse-cloud-instance:8443/")
        .setAccessToken(userAccessToken)
        .build();

Аутентификация по SSL-сертификату клиента требует указания имени пользователя, включения SSL-аутентификации, указания клиентского сертификата и клиентского ключа с помощью вызова методов setUsername(String), useSSLAuthentication(boolean), setClientCertificate(String) и setClientKey(String) соответственно:

Client client = new Client.Builder()
        .useSSLAuthentication(true)
        .setUsername("some_user")
        .setClientCertificate("some_user.crt")
        .setClientKey("some_user.key")

Примечание

Аутентификацию 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"]})

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

Все настройки задаются методами экземпляра (так называемыми методами конфигурации), которые однозначно определяют область действия и контекст каждого значения. Ключевые параметры конфигурации задаются на одном уровне (клиент или операция) и не переопределяют друг друга.

Конфигурация определяется при создании клиента. См. com.clickhouse.client.api.Client.Builder.

Настройка клиента

Method	Arguments	Description	Default	Key
`addEndpoint(String endpoint)`	`endpoint` - адрес сервера в формате URL	Добавляет endpoint сервера в список доступных серверов. В настоящее время поддерживается только один endpoint.	`none`	`none`
`addEndpoint(Protocol protocol, String host, int port, boolean secure)`	`protocol` - протокол подключения `host` - IP-адрес или имя хоста `secure` - использовать HTTPS	Добавляет endpoint сервера в список доступных серверов. В настоящее время поддерживается только один endpoint.	`none`	`none`
`enableConnectionPool(boolean enable)`	`enable` - флаг включения/отключения	Устанавливает, включен ли пул соединений	`true`	`connection_pool_enabled`
`setMaxConnections(int maxConnections)`	`maxConnections` - число соединений	Устанавливает, сколько соединений клиент может открыть к каждому endpoint-у сервера.	`10`	`max_open_connections`
`setConnectionTTL(long timeout, ChronoUnit unit)`	`timeout` - значение тайм-аута `unit` - единица времени	Устанавливает TTL соединения, по истечении которого соединение будет считаться неактивным	`-1`	`connection_ttl`
`setKeepAliveTimeout(long timeout, ChronoUnit unit)`	`timeout` - значение тайм-аута `unit` - единица времени	Устанавливает тайм-аут Keep-Alive для HTTP-соединения. Установите `0`, чтобы отключить Keep-Alive.	-	`http_keep_alive_timeout`
`setConnectionReuseStrategy(ConnectionReuseStrategy strategy)`	`strategy` - `LIFO` или `FIFO`	Выбирает стратегию повторного использования соединений, которую должен применять пул соединений	`FIFO`	`connection_reuse_strategy`
`setDefaultDatabase(String database)`	`database` - имя базы данных	Устанавливает базу данных по умолчанию.	`default`	`database`

Метод	Аргументы	Описание	По умолчанию	Ключ
`setUsername(String username)`	`username` - имя пользователя для аутентификации	Задает имя пользователя для метода аутентификации, который будет выбран дальнейшей конфигурацией	`default`	`user`
`setPassword(String password)`	`password` - секретное значение	Задает секрет для аутентификации по паролю и фактически выбирает этот метод аутентификации	-	`password`
`setAccessToken(String accessToken)`	`accessToken` - строка access-токена	Задает access-токен для аутентификации и тем самым выбирает соответствующий метод аутентификации	-	`access_token`
`useSSLAuthentication(boolean useSSLAuthentication)`	`useSSLAuthentication` - флаг для включения SSL-аутентификации	Устанавливает клиентский SSL-сертификат как метод аутентификации.	-	`ssl_authentication`
`useHTTPBasicAuth(boolean useBasicAuth)`	`useBasicAuth` - флаг включения/отключения	Определяет, следует ли использовать базовую HTTP-аутентификацию для аутентификации по паре пользователь-пароль. Решает проблемы с паролями, содержащими спецсимволы.	`true`	`http_use_basic_auth`
`useBearerTokenAuth(String bearerToken)`	`bearerToken` - закодированный bearer-токен	Определяет, следует ли использовать Bearer-аутентификацию и какой токен использовать. Токен будет отправлен как есть.	-	`bearer_token`

Method	Arguments	Description	Default	Key
`setConnectTimeout(long timeout, ChronoUnit unit)`	`timeout` - значение тайм-аута `unit` - единица времени	Устанавливает тайм-аут установления соединения для любого исходящего подключения.	-	`connection_timeout`
`setConnectionRequestTimeout(long timeout, ChronoUnit unit)`	`timeout` - значение тайм-аута `unit` - единица времени	Устанавливает тайм-аут запроса соединения. Применяется только при получении соединения из пула.	`10000`	`connection_request_timeout`
`setSocketTimeout(long timeout, ChronoUnit unit)`	`timeout` - значение тайм-аута `unit` - единица времени	Устанавливает тайм-аут сокета, который влияет на операции чтения и записи.	`0`	`socket_timeout`
`setExecutionTimeout(long timeout, ChronoUnit timeUnit)`	`timeout` - значение тайм-аута `timeUnit` - единица времени	Устанавливает максимальное время выполнения запросов	`0`	`max_execution_time`
`retryOnFailures(ClientFaultCause ...causes)`	`causes` - константа перечисления `ClientFaultCause`	Задает типы ошибок, для которых будут выполняться повторные попытки.	`NoHttpResponse` `ConnectTimeout` `ConnectionRequestTimeout`	`client_retry_on_failures`
`setMaxRetries(int maxRetries)`	`maxRetries` - количество повторных попыток	Устанавливает максимальное число повторных попыток для ошибок, определенных `retryOnFailures`.	`3`	`retry`

Method	Arguments	Description	Default	Key
`setSocketRcvbuf(long size)`	`size` - размер в байтах	Устанавливает размер буфера приёма TCP-сокета. Этот буфер располагается вне памяти JVM.	`8196`	`socket_rcvbuf`
`setSocketSndbuf(long size)`	`size` - размер в байтах	Устанавливает размер буфера отправки TCP-сокета. Этот буфер располагается вне памяти JVM.	`8196`	`socket_sndbuf`
`setSocketKeepAlive(boolean value)`	`value` - флаг для включения/выключения	Устанавливает опцию `SO_KEEPALIVE` для каждого TCP-сокета. TCP Keep-Alive включает механизм проверки активности соединения.	-	`socket_keepalive`
`setSocketTcpNodelay(boolean value)`	`value` - флаг для включения/выключения	Устанавливает опцию `SO_NODELAY` для каждого TCP-сокета. Эта опция TCP заставляет сокет отправлять данные как можно скорее.	-	`socket_tcp_nodelay`
`setSocketLinger(int secondsToWait)`	`secondsToWait` - количество секунд	Устанавливает время задержки (linger) для каждого TCP-сокета, созданного клиентом.	-	`socket_linger`

Метод	Аргументы	Описание	Значение по умолчанию	Ключ
`compressServerResponse(boolean enabled)`	`enabled` — флаг включения/выключения	Определяет, должен ли сервер сжимать свои ответы.	`true`	`compress`
`compressClientRequest(boolean enabled)`	`enabled` — флаг включения/выключения	Определяет, должен ли клиент сжимать свои запросы.	`false`	`decompress`
`useHttpCompression(boolean enabled)`	`enabled` — флаг включения/выключения	Определяет, следует ли использовать HTTP‑сжатие для взаимодействия клиент/сервер, если соответствующие параметры включены.	-	-
`appCompressedData(boolean enabled)`	`enabled` — флаг включения/выключения	Сообщает клиенту, что сжатие будет обрабатываться приложением.	`false`	`app_compressed_data`
`setLZ4UncompressedBufferSize(int size)`	`size` — размер в байтах	Устанавливает размер буфера, который будет получать несжатую часть потока данных.	`65536`	`compression.lz4.uncompressed_buffer_size`
`disableNativeCompression`	`disable` — флаг отключения	Отключает нативное сжатие. Если установлено в `true`, нативное сжатие будет отключено.	`false`	`disable_native_compression`

Method	Arguments	Description	Default	Key
`setSSLTrustStore(String path)`	`path` - путь к файлу в локальной системе	Указывает, должен ли клиент использовать SSL truststore для проверки подлинности хоста сервера.	-	`trust_store`
`setSSLTrustStorePassword(String password)`	`password` - секретное значение	Указывает пароль, который будет использоваться для разблокировки SSL truststore, указанного с помощью `setSSLTrustStore`.	-	`key_store_password`
`setSSLTrustStoreType(String type)`	`type` - имя типа truststore	Указывает тип truststore, указанного с помощью `setSSLTrustStore`.	-	`key_store_type`
`setRootCertificate(String path)`	`path` - путь к файлу в локальной системе	Указывает, должен ли клиент использовать указанный корневой (CA) сертификат для проверки подлинности хоста сервера.	-	`sslrootcert`
`setClientCertificate(String path)`	`path` - путь к файлу в локальной системе	Указывает путь к клиентскому сертификату, который будет использоваться при установке SSL-соединения и для SSL-аутентификации.	-	`sslcert`
`setClientKey(String path)`	`path` - путь к файлу в локальной системе	Указывает закрытый ключ клиента, который будет использоваться для шифрования SSL-взаимодействия с сервером.	-	`ssl_key`
`sslSocketSNI(String sni)`	`sni` - строка с именем сервера	Указывает имя сервера, которое будет использоваться для SNI (Server Name Indication) в SSL/TLS-соединении.	-	`ssl_socket_sni`

Method	Arguments	Description	Default	Key
`addProxy(ProxyType type, String host, int port)`	`type` - тип прокси `host` - имя хоста или IP-адрес прокси-сервера `port` - порт прокси-сервера	Устанавливает прокси-сервер, который будет использоваться для взаимодействия с сервером.	-	`proxy_type`, `proxy_host`, `proxy_port`
`setProxyCredentials(String user, String pass)`	`user` - имя пользователя прокси `pass` - пароль	Задает учетные данные для аутентификации на прокси-сервере.	-	`proxy_user`, `proxy_password`

Method	Arguments	Description	Default	Key
`setHttpCookiesEnabled(boolean enabled)`	`enabled` - флаг включения/отключения	Определяет, должны ли HTTP‑cookie сохраняться и отправляться обратно на сервер.	-	-
`httpHeader(String key, String value)`	`key` - ключ HTTP‑заголовка `value` - строковое значение	Устанавливает значение для одного HTTP‑заголовка. Предыдущее значение перезаписывается.	`none`	`none`
`httpHeader(String key, Collection values)`	`key` - ключ HTTP‑заголовка `values` - список строковых значений	Устанавливает несколько значений одного HTTP‑заголовка. Предыдущее значение перезаписывается.	`none`	`none`
`httpHeaders(Map headers)`	`headers` - map с HTTP‑заголовками	Устанавливает несколько HTTP‑заголовков за один раз.	`none`	`none`

Method	Arguments	Description	Default	Key
`serverSetting(String name, String value)`	`name` - имя настройки `value` - значение настройки	Указывает, какие настройки передавать серверу вместе с каждым запросом. Настройки отдельных операций могут их переопределять. Список настроек	`none`	`none`
`serverSetting(String name, Collection values)`	`name` - имя настройки `values` - значения настройки	Указывает, какие настройки с множественными значениями передавать серверу, например роли	`none`	`none`

Method	Arguments	Description	Default	Key
`useServerTimeZone(boolean useServerTimeZone)`	`useServerTimeZone` - флаг включения/выключения	Определяет, должен ли клиент использовать часовой пояс сервера при декодировании значений столбцов типов DateTime и Date.	`true`	`use_server_time_zone`
`useTimeZone(String timeZone)`	`timeZone` - допустимый в Java идентификатор часового пояса	Определяет, должен ли использоваться указанный часовой пояс при декодировании значений столбцов типов DateTime и Date. Переопределяет часовой пояс сервера.	-	`use_time_zone`
`setServerTimeZone(String timeZone)`	`timeZone` - допустимый в Java идентификатор часового пояса	Задает часовой пояс на стороне сервера. По умолчанию используется часовой пояс UTC.	`UTC`	`server_time_zone`

Method	Arguments	Description	Default	Key
`setOption(String key, String value)`	`key` - ключ параметра конфигурации `value` - значение параметра	Устанавливает сырое значение параметров клиента. Полезно при чтении конфигурации из property-файлов.	-	-
`useAsyncRequests(boolean async)`	`async` - флаг включения/выключения	Определяет, должен ли клиент выполнять запросы в отдельном потоке. По умолчанию отключено, так как приложение лучше знает, как организовать многопоточные задачи.	`false`	`async`
`setSharedOperationExecutor(ExecutorService executorService)`	`executorService` - экземпляр ExecutorService	Задает ExecutorService для выполнения операционных задач.	`none`	`none`
`setClientNetworkBufferSize(int size)`	`size` - размер в байтах	Устанавливает размер буфера в адресном пространстве памяти приложения, который используется для копирования данных между сокетом и приложением.	`300000`	`client_network_buffer_size`
`allowBinaryReaderToReuseBuffers(boolean reuse)`	`reuse` - флаг включения/выключения	Если включено, двоичный читатель будет использовать заранее выделенные буферы для транскодирования чисел. Снижает нагрузку на GC для числовых данных.	-	-
`columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy)`	`strategy` - реализация стратегии сопоставления	Задает пользовательскую стратегию, используемую для сопоставления полей класса DTO и столбцов БД при регистрации DTO.	`none`	`none`
`setClientName(String clientName)`	`clientName` - строка с именем приложения	Устанавливает дополнительную информацию о вызывающем приложении. Будет передана в заголовке `User-Agent`.	-	`client_name`
`registerClientMetrics(Object registry, String name)`	`registry` - экземпляр реестра Micrometer `name` - имя группы метрик	Регистрирует метрики в экземпляре реестра Micrometer (https://micrometer.io/).	-	-
`setServerVersion(String version)`	`version` - строка с версией сервера	Устанавливает версию сервера, чтобы избежать автоматического определения версии.	-	`server_version`
`typeHintMapping(Map typeHintMapping)`	`typeHintMapping` - отображение (Map) подсказок типов	Устанавливает отображение подсказок типов для типов ClickHouse. Например, чтобы многомерные массивы представлялись в виде контейнеров Java.	-	`type_hint_mapping`

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

Настройки на стороне сервера можно задать на уровне клиента один раз при его создании (см. метод serverSetting класса Builder) и на уровне конкретной операции (см. метод serverSetting в классе настроек операции).

 try (Client client = new Client.Builder().addEndpoint(Protocol.HTTP, "localhost", mockServer.port(), false)
        .setUsername("default")
        .setPassword(ClickHouseServerForTest.getPassword())
        .compressClientRequest(true)

        // Client level
        .serverSetting("max_threads", "10")
        .serverSetting("async_insert", "1")
        .serverSetting("roles", Arrays.asList("role1", "role2"))

        .build()) {

	// Operation level
	QuerySettings querySettings = new QuerySettings();
	querySettings.serverSetting("session_timezone", "Europe/Zurich");

	...
}

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

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

Пользовательские HTTP-заголовки можно задать для всех операций (на уровне клиента) или только для отдельной операции (на уровне операции).


QuerySettings settings = new QuerySettings()
    .httpHeader(HttpHeaders.REFERER, clientReferer)
    .setQueryId(qId);

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

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

ClickHouseFormat

Перечисление поддерживаемых форматов. В него входят все форматы, поддерживаемые ClickHouse.

raw - транскодирование необработанных данных выполняется пользователем
full — клиент сам выполняет транскодирование данных и принимает сырой поток данных
- - операция не поддерживается ClickHouse для данного формата

Эта версия клиента поддерживает:

Формат	Входные данные	Выходные данные
TabSeparated	raw	raw
TabSeparatedRaw	raw	raw
TabSeparatedWithNames	raw	raw
TabSeparatedWithNamesAndTypes	raw	raw
TabSeparatedRawWithNames	raw	raw
TabSeparatedRawWithNamesAndTypes	raw	raw
Template	raw	raw
TemplateIgnoreSpaces	raw	*
CSV	raw	raw
CSVWithNames	raw	raw
CSVWithNamesAndTypes	raw	raw
CustomSeparated	raw	raw
CustomSeparatedWithNames	raw	raw
CustomSeparatedWithNamesAndTypes	raw	raw
SQLInsert	-	raw
Values	raw	raw
Vertical	*	raw
JSON	raw	raw
JSONAsString	raw	-
JSONAsObject	raw	*
JSONStrings	raw	raw
JSONColumns	raw	raw
JSONColumnsWithMetadata	raw	raw
JSONCompact	raw	raw
JSONCompactStrings	-	raw
JSONCompactColumns	raw	как есть
JSONEachRow	как есть	raw
PrettyJSONEachRow	*	как есть
JSONEachRowWithProgress	-	как есть
JSONStringsEachRow	raw	как есть
JSONStringsEachRowWithProgress	*	raw
JSONCompactEachRow	как есть	как есть
JSONCompactEachRowWithNames	raw	raw
JSONCompactEachRowWithNamesAndTypes	raw	как есть
JSONCompactStringsEachRow	raw	raw
JSONCompactStringsEachRowWithNames	raw	как есть
JSONCompactStringsEachRowWithNamesAndTypes	как есть	как есть
JSONObjectEachRow	raw	как есть
BSONEachRow	как есть	как есть
TSKV	raw	raw
Pretty	-	raw
PrettyNoEscapes	*	raw
PrettyMonoBlock	-	raw
PrettyNoEscapesMonoBlock	*	raw
PrettyCompact	-	raw
PrettyCompactNoEscapes	*	raw
PrettyCompactMonoBlock	-	raw
PrettyCompactNoEscapesMonoBlock	*	raw
PrettySpace	-	raw
PrettySpaceNoEscapes	*	raw
PrettySpaceMonoBlock	-	raw
PrettySpaceNoEscapesMonoBlock	*	raw
Prometheus	-	raw
Protobuf	raw	raw
ProtobufSingle	raw	raw
ProtobufList	raw	raw
Avro	raw	raw
AvroConfluent	raw	*
Parquet	raw	raw
ParquetMetadata	raw	-
Arrow	raw	raw
ArrowStream	raw	raw
ORC	raw	raw
One	raw	*
Npy	raw	raw
RowBinary	full	full
RowBinaryWithNames	full	полная
RowBinaryWithNamesAndTypes	полная	полный
RowBinaryWithDefaults	full	-
Native	full	необработанный
Null	*	raw
XML	-	raw
CapnProto	raw	raw
LineAsString	как есть	raw
Regexp	raw	*
RawBLOB	raw	raw
MsgPack	raw	как есть
MySQLDump	raw	-
DWARF	raw	*
Markdown	-	raw
Form	raw	*

API вставки

insert(String tableName, InputStream data, ClickHouseFormat format)

Принимает данные в виде потока байтов InputStream в указанном формате. Ожидается, что data кодированы в format.

Сигнатуры

CompletableFuture<InsertResponse> insert(String tableName, InputStream data, ClickHouseFormat format, InsertSettings settings)
CompletableFuture<InsertResponse> insert(String tableName, InputStream data, ClickHouseFormat format)

Параметры

tableName — имя целевой таблицы.

data — входной поток закодированных данных.

format — формат, в котором закодированы данные.

settings — настройки запроса.

Возвращаемое значение

Future типа InsertResponse — результат операции и дополнительная информация, например, метрики на стороне сервера.

Примеры

try (InputStream dataStream = getDataStream()) {
    try (InsertResponse response = client.insert(TABLE_NAME, dataStream, ClickHouseFormat.JSONEachRow,
            insertSettings).get(3, TimeUnit.SECONDS)) {

        log.info("Insert finished: {} rows written", response.getMetrics().getMetric(ServerMetrics.NUM_ROWS_WRITTEN).getLong());
    } catch (Exception e) {
        log.error("Failed to write JSONEachRow data", e);
        throw new RuntimeException(e);
    }
}

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

Отправляет запрос на запись в базу данных. Список объектов преобразуется в эффективный формат и затем отправляется на сервер. Класс элементов списка должен быть заранее зарегистрирован с помощью метода register(Class, TableSchema).

Подписи

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

Параметры

tableName — имя целевой таблицы.

data — коллекция объектов DTO (Data Transfer Object).

settings — настройки запроса.

Возвращаемое значение

Future типа InsertResponse — результат операции и дополнительная информация, например, метрики на стороне сервера.

Примеры

// Important step (done once) - register class to pre-compile object serializer according to the table schema.
client.register(ArticleViewEvent.class, client.getTableSchema(TABLE_NAME));

List<ArticleViewEvent> events = loadBatch();

try (InsertResponse response = client.insert(TABLE_NAME, events).get()) {
    // handle response, then it will be closed and connection that served request will be released.
}

InsertSettings

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

Методы конфигурации

Метод	Описание
`setQueryId(String queryId)`	Устанавливает идентификатор запроса, который будет присвоен операции. Значение по умолчанию: `null`.
`setDeduplicationToken(String token)`	Устанавливает токен дедупликации. Этот токен будет отправлен на сервер и может использоваться для идентификации запроса. Значение по умолчанию: `null`.
`setInputStreamCopyBufferSize(int size)`	Размер буфера копирования. Буфер используется при операциях записи для копирования данных из входного потока, предоставленного пользователем, в выходной поток. По умолчанию: `8196`.
`serverSetting(String name, String value)`	Задаёт отдельную настройку сервера для операции.
`serverSetting(String name, Collection values)`	Устанавливает отдельную серверную настройку с несколькими значениями для операции. Элементы коллекции должны быть значениями типа `String`.
`setDBRoles(Collection dbRoles)`	Указывает роли БД, которые нужно назначить перед выполнением операции. Элементы коллекции должны быть значениями типа `String`.
`setOption(String option, Object value)`	Задаёт параметр конфигурации в «сыром» виде. Это не серверная настройка.

InsertResponse

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

Примечание

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

Метод	Описание
`OperationMetrics getMetrics()`	Возвращает объект, содержащий метрики операции.
`String getQueryId()`	Возвращает идентификатор запроса, назначенный операции приложением (через настройки операции) либо сервером.

API запросов

query(String sqlQuery)

Отправляет sqlQuery как есть. Формат ответа задаётся настройками запроса. QueryResponse будет содержать ссылку на поток ответа, который должен быть прочитан ридером, поддерживающим соответствующий формат.

Подписи

CompletableFuture<QueryResponse> query(String sqlQuery, QuerySettings settings)
CompletableFuture<QueryResponse> query(String sqlQuery)

Параметры

sqlQuery — один SQL-оператор. Запрос отправляется на сервер в исходном виде.

settings — настройки запроса.

Возвращаемое значение

Future типа QueryResponse — результирующий набор данных и дополнительная информация, такая как метрики на стороне сервера. Объект Response должен быть закрыт после чтения набора данных.

Примеры

final String sql = "select * from " + TABLE_NAME + " where title <> '' limit 10";

// Default format is RowBinaryWithNamesAndTypesFormatReader so reader have all information about columns
try (QueryResponse response = client.query(sql).get(3, TimeUnit.SECONDS);) {

    // Create a reader to access the data in a convenient way
    ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);

    while (reader.hasNext()) {
        reader.next(); // Read the next record from stream and parse it

        // get values
        double id = reader.getDouble("id");
        String title = reader.getString("title");
        String url = reader.getString("url");

        // collecting data
    }
} catch (Exception e) {
    log.error("Failed to read data", e);
}

// put business logic outside of the reading block to release http connection asap.

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

Отправляет sqlQuery как есть. Дополнительно передаёт параметры запроса, чтобы сервер мог скомпилировать SQL-выражение.

Подписи

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

Параметры

sqlQuery - SQL-выражение с плейсхолдерами {}.

queryParams — словарь переменных для подстановки значений в SQL-выражение на сервере.

settings — настройки запроса.

Возвращаемое значение

Будущее типа QueryResponse — результирующий набор данных и дополнительная информация, такая как метрики на стороне сервера. Объект Response должен быть закрыт после потребления набора данных.

Примеры


// define parameters. They will be sent to the server along with the request.
Map<String, Object> queryParams = new HashMap<>();
queryParams.put("param1", 2);

try (QueryResponse response =
        client.query("SELECT * FROM " + table + " WHERE col1 >= {param1:UInt32}", queryParams, new QuerySettings()).get()) {

    // Create a reader to access the data in a convenient way
    ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);

    while (reader.hasNext()) {
        reader.next(); // Read the next record from stream and parse it

        // reading data
    }

} catch (Exception e) {
    log.error("Failed to read data", e);
}

queryAll(String sqlQuery)

Запрашивает данные в формате RowBinaryWithNamesAndTypes. Возвращает результат в виде коллекции. Производительность чтения такая же, как при использовании reader, но требуется больше памяти для хранения всего набора данных.

Подписи

List<GenericRecord> queryAll(String sqlQuery)

Параметры

sqlQuery — SQL-выражение для запроса данных с сервера.

Возвращаемое значение

Полный набор данных, представленный списком объектов GenericRecord, обеспечивающих построчный доступ к данным результата.

Примеры

try {
    log.info("Reading whole table and process record by record");
    final String sql = "select * from " + TABLE_NAME + " where title <> ''";

    // Read whole result set and process it record by record
    client.queryAll(sql).forEach(row -> {
        double id = row.getDouble("id");
        String title = row.getString("title");
        String url = row.getString("url");

        log.info("id: {}, title: {}, url: {}", id, title, url);
    });
} catch (Exception e) {
    log.error("Failed to read data", e);
}

QuerySettings

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

Методы конфигурации

Метод	Описание
`setQueryId(String queryId)`	Задаёт идентификатор запроса, который будет присвоен операции.
`setFormat(ClickHouseFormat format)`	Задаёт формат ответа. Полный список форматов см. в `RowBinaryWithNamesAndTypes`.
`setMaxExecutionTime(Integer maxExecutionTime)`	Устанавливает время выполнения операции на сервере. Не влияет на таймаут чтения.
`waitEndOfQuery(Boolean waitEndOfQuery)`	Указывает серверу дождаться завершения запроса перед отправкой ответа.
`setUseServerTimeZone(Boolean useServerTimeZone)`	Часовой пояс сервера (см. конфигурацию клиента) будет использоваться при разборе значений типов дата/время в результате операции. По умолчанию `false`.
`setUseTimeZone(String timeZone)`	Запрашивает использование сервером часового пояса `timeZone` для преобразования времени. См. session_timezone.
`serverSetting(String name, String value)`	Задаёт отдельную настройку сервера для операции.
`serverSetting(String name, Collection values)`	Устанавливает отдельную серверную настройку с несколькими значениями для операции. Элементы коллекции должны быть значениями типа `String`.
`setDBRoles(Collection dbRoles)`	Указывает роли БД, которые нужно назначить перед выполнением операции. Элементы коллекции должны быть значениями типа `String`.
`setOption(String option, Object value)`	Устанавливает параметр конфигурации в необработанном виде. Это не параметр сервера.

QueryResponse

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

Примечание

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

Метод	Описание
`ClickHouseFormat getFormat()`	Возвращает формат, в котором закодированы данные в ответе.
`InputStream getInputStream()`	Возвращает несжатый поток байтов данных в указанном формате.
`OperationMetrics getMetrics()`	Возвращает объект с метриками операции.
`String getQueryId()`	Возвращает идентификатор запроса, назначенный операции приложением (через настройки операции) или сервером.
`TimeZone getTimeZone()`	Возвращает часовой пояс, который должен использоваться при обработке типов Date/DateTime в ответе.

Примеры

Примеры кода доступны в репозитории
См. реализацию сервиса Spring: implementation

Общий API

getTableSchema(String table)

Извлекает схему таблицы table.

Подписи

TableSchema getTableSchema(String table)
TableSchema getTableSchema(String table, String database)

Параметры

table — имя таблицы, для которой нужно получить данные схемы.

database — база данных, в которой определена целевая таблица.

Возвращаемое значение

Возвращает объект TableSchema со списком столбцов таблицы.

getTableSchemaFromQuery(String sql)

Получает схему из SQL-выражения.

Сигнатуры

TableSchema getTableSchemaFromQuery(String sql)

Параметры

sql - SQL-оператор "SELECT", схема результата которого должна быть возвращена.

Возвращаемое значение

Возвращает объект TableSchema со столбцами, соответствующими выражению sql.

TableSchema

register(Class<?> clazz, TableSchema schema)

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

Сигнатуры

void register(Class<?> clazz, TableSchema schema)

Параметры

clazz — класс POJO, используемый для чтения и записи данных.

schema - Схема данных для сопоставления со свойствами POJO.

Примеры

client.register(ArticleViewEvent.class, client.getTableSchema(TABLE_NAME));

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

Полный код примеров хранится в репозитории в папке example folder:

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) (и значений enum, представленных именами).
getObjectArray(...) - универсальный метод для любого типа элементов Array(...), включая вложенные массивы. Используйте его для чтения массивов с Nullable-значениями и вложенных массивов.

Перегрузки на основе индекса и имени доступны для всех методов. Индексация начинается с 1. Методы, основанные на индексе, обеспечивают прямой доступ к столбцу. Методы, основанные на имени, при каждом вызове требуют поиска по индексу.

try (QueryResponse response = client.query("SELECT * FROM my_table").get()) {
    ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);
    while (reader.next() != null) {
        
        Object[] uint64 = reader.getObjectArray("uint64_arr"); // Array(UInt64) -> BigInteger[]
        Object[] arr2d = reader.getObjectArray("arr2d");       // Array(Array(Int64)) -> Object[]

        // nested arrays are returned as nested Object[]:
        Object[] firstInner = (Object[]) arr2d[0];
        Long firstValue = (Long) firstInner[0];
    }
}

Методы GenericRecord

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

Перегрузки по индексу и по имени доступны для всех методов. Нумерация индексов начинается с 1. Варианты, основанные на индексе, обеспечивают прямой доступ к столбцу. Методы, основанные на имени, каждый раз требуют поиска индекса.

try (QueryResponse response = client.query("SELECT * FROM my_table").get()) {
    List<GenericRecord> rows = client.queryAll(
        "SELECT int_arr, arr2d_nullable FROM test_arrays ORDER BY id");

    for (GenericRecord row : rows) {
        Object[] intArr = row.getObjectArray("int_arr");                 // Array(Int32) -> Integer[]
        Object[] arr2d = row.getObjectArray("arr2d_nullable");           // Array(Array(Nullable(Int32)))

        Object[] inner = (Object[]) arr2d[0];
        Object maybeNull = inner[1]; // may be null
    }
}


## Migration Guide                   


Old client (V1) was using `com.clickhouse.client.ClickHouseClient#builder` as start point. The new client (V2) uses similar pattern with `com.clickhouse.client.api.Client.Builder`. Main
differences are:
- no service loader is used to grab implementation. The `com.clickhouse.client.api.Client` is facade class for all kinds of implementation in the future.
- a fewer sources of configuration: one is provided to the builder and one is with operation settings (`QuerySettings`, `InsertSettings`). Previous version had configuration per node and was loading
env. variables in some cases.

### Configuration Parameters Match                            

There are 3 enum classes related to configuration in V1:
- `com.clickhouse.client.config.ClickHouseDefaults` - configuration parameters that supposed to be set in most use cases. Like `USER` and `PASSWORD`.
- `com.clickhouse.client.config.ClickHouseClientOption` - configuration parameters specific for the client. Like `HEALTH_CHECK_INTERVAL`.
- `com.clickhouse.client.http.config.ClickHouseHttpOption` - configuration parameters specific for HTTP interface. Like `RECEIVE_QUERY_PROGRESS`.

They were designed to group parameters and provide clear separation. However in some cases it lead to a confusion (is there a difference between `com.clickhouse.client.config.ClickHouseDefaults#ASYNC` and
`com.clickhouse.client.config.ClickHouseClientOption#ASYNC`). The new V2 client uses `com.clickhouse.client.api.Client.Builder` as single dictionary of all possible client configuration options.There is
`com.clickhouse.client.api.ClientConfigProperties` where all configuration parameter names are listed.

Table below shows what old options are supported in the new client and their new meaning.

**Legend:** ✔ = supported, ✗ = dropped

<Tabs groupId="v1-migration">
<TabItem value="connection-auth" label="Connection & Auth">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseDefaults#HOST` | `Client.Builder#addEndpoint` | |
| `ClickHouseDefaults#PROTOCOL` | ✗ | Only HTTP supported in V2 |
| `ClickHouseDefaults#DATABASE`<br/>`ClickHouseClientOption#DATABASE` | `Client.Builder#setDefaultDatabase` | |
| `ClickHouseDefaults#USER` | `Client.Builder#setUsername` | |
| `ClickHouseDefaults#PASSWORD` | `Client.Builder#setPassword` | |
| `ClickHouseClientOption#CONNECTION_TIMEOUT` | `Client.Builder#setConnectTimeout` | |
| `ClickHouseClientOption#CONNECTION_TTL` | `Client.Builder#setConnectionTTL` | |
| `ClickHouseHttpOption#MAX_OPEN_CONNECTIONS` | `Client.Builder#setMaxConnections` | |
| `ClickHouseHttpOption#KEEP_ALIVE`<br/>`ClickHouseHttpOption#KEEP_ALIVE_TIMEOUT` | `Client.Builder#setKeepAliveTimeout` | |
| `ClickHouseHttpOption#CONNECTION_REUSE_STRATEGY` | `Client.Builder#setConnectionReuseStrategy` | |
| `ClickHouseHttpOption#USE_BASIC_AUTHENTICATION` | `Client.Builder#useHTTPBasicAuth` | |

</TabItem>

<TabItem value="ssl" label="SSL & Security">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseDefaults#SSL_CERTIFICATE_TYPE` | ✗ | |
| `ClickHouseDefaults#SSL_KEY_ALGORITHM` | ✗ | |
| `ClickHouseDefaults#SSL_PROTOCOL` | ✗ | |
| `ClickHouseClientOption#SSL` | ✗ | See `Client.Builder#addEndpoint` |
| `ClickHouseClientOption#SSL_MODE` | ✗ | |
| `ClickHouseClientOption#SSL_ROOT_CERTIFICATE` | `Client.Builder#setRootCertificate` | SSL Auth should be enabled by `useSSLAuthentication` |
| `ClickHouseClientOption#SSL_CERTIFICATE` | `Client.Builder#setClientCertificate` | |
| `ClickHouseClientOption#SSL_KEY` | `Client.Builder#setClientKey` | |
| `ClickHouseClientOption#KEY_STORE_TYPE` | `Client.Builder#setSSLTrustStoreType` | |
| `ClickHouseClientOption#TRUST_STORE` | `Client.Builder#setSSLTrustStore` | |
| `ClickHouseClientOption#KEY_STORE_PASSWORD` | `Client.Builder#setSSLTrustStorePassword` | |
| `ClickHouseClientOption#SSL_SOCKET_SNI` | `Client.Builder#sslSocketSNI` | |
| `ClickHouseClientOption#CUSTOM_SOCKET_FACTORY` | ✗ | |
| `ClickHouseClientOption#CUSTOM_SOCKET_FACTORY_OPTIONS` | ✗ | See `Client.Builder#sslSocketSNI` to set SNI |

</TabItem>

<TabItem value="socket" label="Socket Options">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseClientOption#SOCKET_TIMEOUT` | `Client.Builder#setSocketTimeout` | |
| `ClickHouseClientOption#SOCKET_REUSEADDR` | `Client.Builder#setSocketReuseAddress` | |
| `ClickHouseClientOption#SOCKET_KEEPALIVE` | `Client.Builder#setSocketKeepAlive` | |
| `ClickHouseClientOption#SOCKET_LINGER` | `Client.Builder#setSocketLinger` | |
| `ClickHouseClientOption#SOCKET_IP_TOS` | ✗ | |
| `ClickHouseClientOption#SOCKET_TCP_NODELAY` | `Client.Builder#setSocketTcpNodelay` | |
| `ClickHouseClientOption#SOCKET_RCVBUF` | `Client.Builder#setSocketRcvbuf` | |
| `ClickHouseClientOption#SOCKET_SNDBUF` | `Client.Builder#setSocketSndbuf` | |

</TabItem>

<TabItem value="compression" label="Compression">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseClientOption#COMPRESS` | `Client.Builder#compressServerResponse` | See also `useHttpCompression` |
| `ClickHouseClientOption#DECOMPRESS` | `Client.Builder#compressClientRequest` | See also `useHttpCompression` |
| `ClickHouseClientOption#COMPRESS_ALGORITHM` | ✗ | `LZ4` for non-http. Http uses `Accept-Encoding` |
| `ClickHouseClientOption#DECOMPRESS_ALGORITHM` | ✗ | `LZ4` for non-http. Http uses `Content-Encoding` |
| `ClickHouseClientOption#COMPRESS_LEVEL` | ✗ | |
| `ClickHouseClientOption#DECOMPRESS_LEVEL` | ✗ | |

</TabItem>

<TabItem value="proxy" label="Proxy">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseClientOption#PROXY_TYPE` | `Client.Builder#addProxy` | |
| `ClickHouseClientOption#PROXY_HOST` | `Client.Builder#addProxy` | |
| `ClickHouseClientOption#PROXY_PORT` | `Client.Builder#addProxy` | |
| `ClickHouseClientOption#PROXY_USERNAME` | `Client.Builder#setProxyCredentials` | |
| `ClickHouseClientOption#PROXY_PASSWORD` | `Client.Builder#setProxyCredentials` | |

</TabItem>

<TabItem value="timeouts-retry" label="Timeouts & Retry">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseClientOption#MAX_EXECUTION_TIME` | `Client.Builder#setExecutionTimeout` | |
| `ClickHouseClientOption#RETRY` | `Client.Builder#setMaxRetries` | See also `retryOnFailures` |
| `ClickHouseHttpOption#AHC_RETRY_ON_FAILURE` | `Client.Builder#retryOnFailures` | |
| `ClickHouseClientOption#FAILOVER` | ✗ | |
| `ClickHouseClientOption#REPEAT_ON_SESSION_LOCK` | ✗ | |
| `ClickHouseClientOption#SESSION_ID` | ✗ | |
| `ClickHouseClientOption#SESSION_CHECK` | ✗ | |
| `ClickHouseClientOption#SESSION_TIMEOUT` | ✗ | |

</TabItem>

<TabItem value="timezone" label="Timezone">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseDefaults#SERVER_TIME_ZONE`<br/>`ClickHouseClientOption#SERVER_TIME_ZONE` | `Client.Builder#setServerTimeZone` | |
| `ClickHouseClientOption#USE_SERVER_TIME_ZONE` | `Client.Builder#useServerTimeZone` | |
| `ClickHouseClientOption#USE_SERVER_TIME_ZONE_FOR_DATES` | | |
| `ClickHouseClientOption#USE_TIME_ZONE` | `Client.Builder#useTimeZone` | |

</TabItem>

<TabItem value="buffers" label="Buffers & Performance">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseClientOption#BUFFER_SIZE` | `Client.Builder#setClientNetworkBufferSize` | |
| `ClickHouseClientOption#BUFFER_QUEUE_VARIATION` | ✗ | |
| `ClickHouseClientOption#READ_BUFFER_SIZE` | ✗ | |
| `ClickHouseClientOption#WRITE_BUFFER_SIZE` | ✗ | |
| `ClickHouseClientOption#REQUEST_CHUNK_SIZE` | ✗ | |
| `ClickHouseClientOption#REQUEST_BUFFERING` | ✗ | |
| `ClickHouseClientOption#RESPONSE_BUFFERING` | ✗ | |
| `ClickHouseClientOption#MAX_BUFFER_SIZE` | ✗ | |
| `ClickHouseClientOption#MAX_QUEUED_BUFFERS` | ✗ | |
| `ClickHouseClientOption#MAX_QUEUED_REQUESTS` | ✗ | |
| `ClickHouseClientOption#REUSE_VALUE_WRAPPER` | ✗ | |

</TabItem>

<TabItem value="threading" label="Threading & Async">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseDefaults#ASYNC`<br/>`ClickHouseClientOption#ASYNC` | `Client.Builder#useAsyncRequests` | |
| `ClickHouseDefaults#MAX_SCHEDULER_THREADS` | ✗ | see `setSharedOperationExecutor` |
| `ClickHouseDefaults#MAX_THREADS` | ✗ | see `setSharedOperationExecutor` |
| `ClickHouseDefaults#THREAD_KEEPALIVE_TIMEOUT` | see `setSharedOperationExecutor` | |
| `ClickHouseClientOption#MAX_THREADS_PER_CLIENT` | ✗ | |
| `ClickHouseClientOption#MAX_CORE_THREAD_TTL` | ✗ | |

</TabItem>

<TabItem value="http-headers" label="HTTP & Headers">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseHttpOption#CUSTOM_HEADERS` | `Client.Builder#httpHeaders` | |
| `ClickHouseHttpOption#CUSTOM_PARAMS` | ✗ | See `Client.Builder#serverSetting` |
| `ClickHouseClientOption#CLIENT_NAME` | `Client.Builder#setClientName` | |
| `ClickHouseHttpOption#CONNECTION_PROVIDER` | ✗ | |
| `ClickHouseHttpOption#DEFAULT_RESPONSE` | ✗ | |
| `ClickHouseHttpOption#SEND_HTTP_CLIENT_ID` | ✗ | |
| `ClickHouseHttpOption#AHC_VALIDATE_AFTER_INACTIVITY` | ✗ | Always enabled when Apache Http Client is used |

</TabItem>

<TabItem value="format-query" label="Format & Query">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseDefaults#FORMAT`<br/>`ClickHouseClientOption#FORMAT` | ✗ | Moved to operation settings (`QuerySettings` and `InsertSettings`) |
| `ClickHouseClientOption#QUERY_ID` | ✗ | See `QuerySettings` and `InsertSettings` |
| `ClickHouseClientOption#LOG_LEADING_COMMENT` | ✗ | See `QuerySettings#logComment` and `InsertSettings#logComment` |
| `ClickHouseClientOption#MAX_RESULT_ROWS` | ✗ | Is server side setting |
| `ClickHouseClientOption#RESULT_OVERFLOW_MODE` | ✗ | Is server side setting |
| `ClickHouseHttpOption#RECEIVE_QUERY_PROGRESS` | ✗ | Server side setting |
| `ClickHouseHttpOption#WAIT_END_OF_QUERY` | ✗ | Server side setting |
| `ClickHouseHttpOption#REMEMBER_LAST_SET_ROLES` | `Client#setDBRoles` | Runtime config now. See also `QuerySettings#setDBRoles` and `InsertSettings#setDBRoles` |

</TabItem>

<TabItem value="node-discovery" label="Node Discovery & Load Balancing">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseClientOption#AUTO_DISCOVERY` | ✗ | |
| `ClickHouseClientOption#LOAD_BALANCING_POLICY` | ✗ | |
| `ClickHouseClientOption#LOAD_BALANCING_TAGS` | ✗ | |
| `ClickHouseClientOption#HEALTH_CHECK_INTERVAL` | ✗ | |
| `ClickHouseClientOption#HEALTH_CHECK_METHOD` | ✗ | |
| `ClickHouseClientOption#NODE_DISCOVERY_INTERVAL` | ✗ | |
| `ClickHouseClientOption#NODE_DISCOVERY_LIMIT` | ✗ | |
| `ClickHouseClientOption#NODE_CHECK_INTERVAL` | ✗ | |
| `ClickHouseClientOption#NODE_GROUP_SIZE` | ✗ | |
| `ClickHouseClientOption#CHECK_ALL_NODES` | ✗ | |

</TabItem>

<TabItem value="misc" label="Miscellaneous">

| V1 Configuration | V2 Builder Method | Comments |
|------------------|-------------------|----------|
| `ClickHouseDefaults#AUTO_SESSION` | ✗ | Session support will be reviewed |
| `ClickHouseDefaults#BUFFERING` | ✗ | |
| `ClickHouseDefaults#MAX_REQUESTS` | ✗ | |
| `ClickHouseDefaults#ROUNDING_MODE` | | |
| `ClickHouseDefaults#SERVER_VERSION`<br/>`ClickHouseClientOption#SERVER_VERSION` | `Client.Builder#setServerVersion` | |
| `ClickHouseDefaults#SRV_RESOLVE` | ✗ | |
| `ClickHouseClientOption#CUSTOM_SETTINGS` | | |
| `ClickHouseClientOption#PRODUCT_NAME` | ✗ | Use client name |
| `ClickHouseClientOption#RENAME_RESPONSE_COLUMN` | ✗ | |
| `ClickHouseClientOption#SERVER_REVISION` | ✗ | |
| `ClickHouseClientOption#TRANSACTION_TIMEOUT` | ✗ | |
| `ClickHouseClientOption#WIDEN_UNSIGNED_TYPES` | ✗ | |
| `ClickHouseClientOption#USE_BINARY_STRING` | ✗ | |
| `ClickHouseClientOption#USE_BLOCKING_QUEUE` | ✗ | |
| `ClickHouseClientOption#USE_COMPILATION` | ✗ | |
| `ClickHouseClientOption#USE_OBJECTS_IN_ARRAYS` | ✗ | |
| `ClickHouseClientOption#MAX_MAPPER_CACHE` | ✗ | |
| `ClickHouseClientOption#MEASURE_REQUEST_TIME` | ✗ | |

</TabItem>
</Tabs>


### General Differences

- Client V2 uses less proprietary classes to increase portability. For example, V2 works with any implementation of `java.io.InputStream` for
writing data to a server.
- Client V2 `async` settings is `off` by default. It means no extra threads and more application control over client. This setting should be `off` for majority of use cases. Enabling `async` will create a separate thread for a request. It only make sense when using application controlled
executor (see `com.clickhouse.client.api.Client.Builder#setSharedOperationExecutor`)

### Writing Data

- use any implementation of `java.io.InputStream`. V1 `com.clickhouse.data.ClickHouseInputStream` is supported but NOT recommended.
- once end of input stream is detected it handled accordingly. Previously output stream of a request should be closed.

__V1 Insert TSV formatted data.__
```java
InputStream inData = getInData();
ClickHouseRequest.Mutation request = client.read(server)
        .write()
        .table(tableName)
        .format(ClickHouseFormat.TSV);
ClickHouseConfig config = request.getConfig();
CompletableFuture<ClickHouseResponse> future;
try (ClickHousePipedOutputStream requestBody = ClickHouseDataStreamFactory.getInstance()
        .createPipedOutputStream(config)) {
    // start the worker thread which transfer data from the input into ClickHouse
    future = request.data(requestBody.getInputStream()).execute();

    // Copy data from inData stream to requestBody stream

    // We need to close the stream before getting a response
    requestBody.close();

    try (ClickHouseResponse response = future.get()) {
        ClickHouseResponseSummary summary = response.getSummary();
        Assert.assertEquals(summary.getWrittenRows(), numRows, "Num of written rows");
    }
}

V2 Вставьте данные в формате TSV.

InputStream inData = getInData();
InsertSettings settings = new InsertSettings().setInputStreamCopyBufferSize(8198 * 2); // set copy buffer size
try (InsertResponse response = client.insert(tableName, inData, ClickHouseFormat.TSV, settings).get(30, TimeUnit.SECONDS)) {

  // Insert is complete at this point

} catch (Exception e) {
 // Handle exception
}

достаточно одного вызова метода — нет необходимости создавать дополнительный объект запроса.
Поток тела запроса автоматически закрывается после копирования всех данных.
Теперь доступен новый низкоуровневый 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 предоставляет доступ к данным и выполняет некоторые преобразования.

Collection<GenericRecord> records = client.queryAll("SELECT * FROM table");
for (GenericRecord record : records) {
    int rowId = record.getInteger("rowID");
    String name = record.getString("name");
    LocalDateTime ts = record.getLocalDateTime("ts");
}

Параметр	Значение по умолчанию	Описание
auto_discovery	`false`	Определяет, должен ли клиент автоматически обнаруживать дополнительные узлы в системных таблицах и/или через clickhouse-keeper/ZooKeeper.
node_discovery_interval	`0`	Интервал обнаружения узлов в миллисекундах; нулевое или отрицательное значение означает однократное обнаружение.
node_discovery_limit	`100`	Максимальное количество узлов, которые могут быть обнаружены за один раз; нулевое или отрицательное значение означает отсутствие ограничения.

Параметр	Значение по умолчанию	Описание
load_balancing_policy	`""`	Политика балансировки нагрузки может иметь одно из следующих значений: `firstAlive` — запрос отправляется первому работоспособному узлу из списка управляемых узлов `random` — запрос отправляется случайному узлу из списка управляемых узлов `roundRobin` — запросы по очереди отправляются каждому узлу из списка управляемых узлов полное имя класса, реализующего `ClickHouseLoadBalancingPolicy`, — пользовательская политика балансировки нагрузки Если политика не указана, запрос отправляется на первый узел из списка управляемых узлов
load_balancing_tags	`""`	Теги балансировки нагрузки, используемые для фильтрации узлов. Запросы отправляются только на узлы с указанными тегами.
health_check_interval	`0`	Интервал проверки работоспособности в миллисекундах; нулевое или отрицательное значение означает однократную проверку.
health_check_method	`ClickHouseHealthCheckMethod.SELECT_ONE`	Метод проверки работоспособности. Может быть одним из следующих: `ClickHouseHealthCheckMethod.SELECT_ONE` - проверка с помощью запроса `select 1` `ClickHouseHealthCheckMethod.PING` - проверка на уровне протокола, как правило, более быстрая
node_check_interval	`0`	Интервал проверки узла в миллисекундах, отрицательное значение рассматривается как ноль. Статус узла проверяется, если с момента последней проверки прошло указанное количество времени. Разница между `health_check_interval` и `node_check_interval` заключается в том, что опция `health_check_interval` планирует фоновое задание, которое проверяет статус узлов в списке (всех или только проблемных), а `node_check_interval` задаёт минимальный интервал времени, который должен пройти с момента последней проверки конкретного узла.
check_all_nodes	`false`	Выполнять проверку работоспособности для всех узлов или только для проблемных узлов.

Параметр	Значение по умолчанию	Описание
failover	`0`	Максимальное число переключений (failover) для одного запроса. Нулевое или отрицательное значение означает, что failover отключён. При failover неуспешный запрос отправляется на другой узел (в соответствии с политикой балансировки нагрузки) для восстановления после сбоя.
retry	`0`	Максимальное число повторных попыток выполнения запроса. Нулевое или отрицательное значение означает отсутствие повторных попыток. Повторная попытка выполняется для того же узла и только в том случае, если сервер ClickHouse возвращает код ошибки `NETWORK_ERROR`.
repeat_on_session_lock	`true`	Следует ли повторять выполнение, если сеанс заблокирован до истечения времени ожидания (в соответствии с `session_timeout` или `connect_timeout`). Неудачный запрос повторяется, если сервер ClickHouse возвращает код ошибки `SESSION_IS_LOCKED`.

Настройка​

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

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

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

Настройка клиента​

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

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

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

ClickHouseFormat​

API вставки​

insert(String tableName, InputStream data, ClickHouseFormat format)​

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

InsertSettings​

InsertResponse​

API запросов​

query(String sqlQuery)​

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

queryAll(String sqlQuery)​

QuerySettings​

QueryResponse​

Примеры​

Общий API​

getTableSchema(String table)​

getTableSchemaFromQuery(String sql)​

TableSchema​

register(Class<?> clazz, TableSchema schema)​

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

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

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

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

Настройка​

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

API запросов​

API потоковых запросов​

API вставки​

Функции​

Сжатие​

Несколько запросов​

Именованные параметры​

Обнаружение узлов​

Балансировка нагрузки​

Отказоустойчивость и повторные попытки​

Добавление пользовательских HTTP-заголовков​

Поддержка Java-клиента​

Драйвер JDBC​

Настройка

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

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

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

Настройка клиента

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

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

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

ClickHouseFormat

API вставки

insert(String tableName, InputStream data, ClickHouseFormat format)

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

InsertSettings

InsertResponse

API запросов

query(String sqlQuery)

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

queryAll(String sqlQuery)

QuerySettings

QueryResponse

Примеры

Общий API

getTableSchema(String table)

getTableSchemaFromQuery(String sql)

TableSchema

register(Class<?> clazz, TableSchema schema)

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

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

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

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

Настройка

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

API запросов

API потоковых запросов

API вставки

Функции

Сжатие

Несколько запросов

Именованные параметры

Обнаружение узлов

Балансировка нагрузки

Отказоустойчивость и повторные попытки

Добавление пользовательских HTTP-заголовков

Поддержка Java-клиента

Драйвер JDBC