> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-3a82795f.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Java ClickHouse Connector # Java client export const WideTableWrapper = ({children}) => { const containerStyle = { overflow: "auto", maxWidth: "100%" }; return
{children}
; }; Java client library to communicate with a DB server through its protocols. The current implementation only supports the [HTTP interface](/concepts/features/interfaces/http). The library provides its own API to send requests to a server. The library also provides tools to work with different binary data formats (RowBinary\* & Native\*).

Setup

* Maven Central (project web page): [https://mvnrepository.com/artifact/com.clickhouse/client-v2](https://mvnrepository.com/artifact/com.clickhouse/client-v2) * Nightly builds (repository link): [https://central.sonatype.com/repository/maven-snapshots/](https://central.sonatype.com/repository/maven-snapshots/) * Old Nightly builds artifactory (repository link): [https://s01.oss.sonatype.org/content/repositories/snapshots/](https://s01.oss.sonatype.org/content/repositories/snapshots/)
```xml theme={null} com.clickhouse client-v2 0.9.8 ``` ```kotlin theme={null} // https://mvnrepository.com/artifact/com.clickhouse/client-v2 implementation("com.clickhouse:client-v2:0.9.8") ``` ```groovy theme={null} // https://mvnrepository.com/artifact/com.clickhouse/client-v2 implementation 'com.clickhouse:client-v2:0.9.8' ```

Initialization

The Client object is initialized by `com.clickhouse.client.api.Client.Builder#build()`. Each client has its own context and no objects are shared between them. The Builder has configuration methods for convenient setup. Example: ```java showLineNumbers theme={null} Client client = new Client.Builder() .addEndpoint("https://clickhouse-cloud-instance:8443/") .setUsername(user) .setPassword(password) .build(); ``` `Client` is `AutoCloseable` and should be closed when not needed anymore.

Authentication

Authentication is configured per client at the initialization phase. There are three authentication methods supported: by password, by access token, by SSL Client Certificate. Authentication by a password requires setting user name password by calling `setUsername(String)` and `setPassword(String)`: ```java showLineNumbers theme={null} Client client = new Client.Builder() .addEndpoint("https://clickhouse-cloud-instance:8443/") .setUsername(user) .setPassword(password) .build(); ``` Authentication by an access token requires setting access token by calling `setAccessToken(String)`: ```java showLineNumbers theme={null} Client client = new Client.Builder() .addEndpoint("https://clickhouse-cloud-instance:8443/") .setAccessToken(userAccessToken) .build(); ``` Authentication by a SSL Client Certificate require setting username, enabling SSL Authentication, setting a client certificate and a client key by calling `setUsername(String)`, `useSSLAuthentication(boolean)`, `setClientCertificate(String)` and `setClientKey(String)` accordingly: ```java showLineNumbers theme={null} Client client = new Client.Builder() .useSSLAuthentication(true) .setUsername("some_user") .setClientCertificate("some_user.crt") .setClientKey("some_user.key") ``` SSL Authentication may be hard to troubleshoot on production because many errors from SSL libraries provide not enough information. For example, if client certificate and key don't match then server will terminate connection immediately (in case of HTTP it will be connection initiation stage where no HTTP requests are send so no response is sent). Please use tools like [openssl](https://docs.openssl.org/master/man1/openssl/) to verify certificates and keys: * check key integrity: `openssl rsa -in [key-file.key] -check -noout` * check client certificate has matching CN for a user: * get CN from an user certificate - `openssl x509 -noout -subject -in [user.cert]` * verify same value is set in database `select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'` (query will output `auth_params` with something like ` {"common_names":["some_user"]}`)

Configuration

All settings are defined by instance methods (a.k.a configuration methods) that make the scope and context of each value clear. Major configuration parameters are defined in one scope (client or operation) and don't override each other. Configuration is defined during client creation. See `com.clickhouse.client.api.Client.Builder`.

Client Configuration

| Method | Arguments | Description | Default | Key | | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------- | --------------------------- | | `addEndpoint(String endpoint)` | `endpoint` - URL formatted server address | Adds a server endpoint to list of available servers. Currently only one endpoint is supported. | `none` | `none` | | `addEndpoint(Protocol protocol, String host, int port, boolean secure)` | `protocol` - connection protocol
`host` - IP or hostname
`secure` - use HTTPS | Adds a server endpoint to list of available servers. Currently only one endpoint is supported. | `none` | `none` | | `enableConnectionPool(boolean enable)` | `enable` - flag to enable/disable | Sets if a connection pool is enabled | `true` | `connection_pool_enabled` | | `setMaxConnections(int maxConnections)` | `maxConnections` - number of connections | Sets how many connections can a client open to each server endpoint. | `10` | `max_open_connections` | | `setConnectionTTL(long timeout, ChronoUnit unit)` | `timeout` - timeout value
`unit` - time unit | Sets connection TTL after which connection will be considered as not active | `-1` | `connection_ttl` | | `setKeepAliveTimeout(long timeout, ChronoUnit unit)` | `timeout` - timeout value
`unit` - time unit | Sets HTTP connection keep-alive timeout. Set to `0` to disable Keep-Alive. | - | `http_keep_alive_timeout` | | `setConnectionReuseStrategy(ConnectionReuseStrategy strategy)` | `strategy` - `LIFO` or `FIFO` | Selects which strategy connection pool should use | `FIFO` | `connection_reuse_strategy` | | `setDefaultDatabase(String database)` | `database` - name of a database | Sets default database. | `default` | `database` | | Method | Arguments | Description | Default | Key | | ---------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | --------------------- | | `setUsername(String username)` | `username` - username for authentication | Sets username for an authentication method that is selected by further configuration | `default` | `user` | | `setPassword(String password)` | `password` - secret value | Sets a secret for password authentication and effectively selects as authentication method | - | `password` | | `setAccessToken(String accessToken)` | `accessToken` - access token string | Sets an access token to authenticate with a sets corresponding authentication method | - | `access_token` | | `useSSLAuthentication(boolean useSSLAuthentication)` | `useSSLAuthentication` - flag to enable SSL auth | Sets SSL Client Certificate as an authentication method. | - | `ssl_authentication` | | `useHTTPBasicAuth(boolean useBasicAuth)` | `useBasicAuth` - flag to enable/disable | Sets if basic HTTP authentication should be used for user-password authentication. Resolves issues with passwords containing special characters. | `true` | `http_use_basic_auth` | | `useBearerTokenAuth(String bearerToken)` | `bearerToken` - an encoded bearer token | Specifies whether to use Bearer Authentication and what token to use. The token will be sent as is. | - | `bearer_token` | | Method | Arguments | Description | Default | Key | | ------------------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ---------------------------- | | `setConnectTimeout(long timeout, ChronoUnit unit)` | `timeout` - timeout value
`unit` - time unit | Sets connection initiation timeout for any outgoing connection. | - | `connection_timeout` | | `setConnectionRequestTimeout(long timeout, ChronoUnit unit)` | `timeout` - timeout value
`unit` - time unit | Sets connection request timeout. This take effect only for getting connection from a pool. | `10000` | `connection_request_timeout` | | `setSocketTimeout(long timeout, ChronoUnit unit)` | `timeout` - timeout value
`unit` - time unit | Sets socket timeout that affects read and write operations | `0` | `socket_timeout` | | `setExecutionTimeout(long timeout, ChronoUnit timeUnit)` | `timeout` - timeout value
`timeUnit` - time unit | Sets maximum execution timeout for queries | `0` | `max_execution_time` | | `retryOnFailures(ClientFaultCause ...causes)` | `causes` - enum constant of `ClientFaultCause` | Sets recoverable/retriable fault types. | `NoHttpResponse` `ConnectTimeout` `ConnectionRequestTimeout` | `client_retry_on_failures` | | `setMaxRetries(int maxRetries)` | `maxRetries` - number of retries | Sets maximum number of retries for failures defined by `retryOnFailures` | `3` | `retry` | | Method | Arguments | Description | Default | Key | | ------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------- | | `setSocketRcvbuf(long size)` | `size` - size in bytes | Sets TCP socket receive buffer. This buffer out of the JVM memory. | `8196` | `socket_rcvbuf` | | `setSocketSndbuf(long size)` | `size` - size in bytes | Sets TCP socket send buffer. This buffer out of the JVM memory. | `8196` | `socket_sndbuf` | | `setSocketKeepAlive(boolean value)` | `value` - flag to enable/disable | Sets option `SO_KEEPALIVE` for every TCP socket. TCP Keep Alive enables mechanism that will check liveness of the connection. | - | `socket_keepalive` | | `setSocketTcpNodelay(boolean value)` | `value` - flag to enable/disable | Sets option `SO_NODELAY` for every TCP socket. This TCP option will make socket to push data as soon as possible. | - | `socket_tcp_nodelay` | | `setSocketLinger(int secondsToWait)` | `secondsToWait` - number of seconds | Set linger time for every TCP socket created by the client. | - | `socket_linger` | | Method | Arguments | Description | Default | Key | | ----------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------ | | `compressServerResponse(boolean enabled)` | `enabled` - flag to enable/disable | Sets if server should compress its responses. | `true` | `compress` | | `compressClientRequest(boolean enabled)` | `enabled` - flag to enable/disable | Sets if client should compress its requests. | `false` | `decompress` | | `useHttpCompression(boolean enabled)` | `enabled` - flag to enable/disable | Sets if HTTP compression should be used for client/server communications if corresponding options are enabled | - | - | | `appCompressedData(boolean enabled)` | `enabled` - flag to enable/disable | Tell client that compression will be handled by application. | `false` | `app_compressed_data` | | `setLZ4UncompressedBufferSize(int size)` | `size` - size in bytes | Sets size of a buffer that will receive uncompressed portion of a data stream. | `65536` | `compression.lz4.uncompressed_buffer_size` | | `disableNativeCompression` | `disable` - flag to disable | Disable native compression. If set to true then native compression will be disabled. | `false` | `disable_native_compression` | | Method | Arguments | Description | Default | Key | | ------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------- | -------------------- | | `setSSLTrustStore(String path)` | `path` - file path on local system | Sets if client should use SSL truststore for server host validation. | - | `trust_store` | | `setSSLTrustStorePassword(String password)` | `password` - secret value | Sets password to be used to unlock SSL truststore specified by `setSSLTrustStore` | - | `key_store_password` | | `setSSLTrustStoreType(String type)` | `type` - truststore type name | Sets type of the truststore specified by `setSSLTrustStore`. | - | `key_store_type` | | `setRootCertificate(String path)` | `path` - file path on local system | Sets if client should use specified root (CA) certificate for server host to validation. | - | `sslrootcert` | | `setClientCertificate(String path)` | `path` - file path on local system | Sets client certificate path to be used while initiating SSL connection and to be used by SSL authentication. | - | `sslcert` | | `setClientKey(String path)` | `path` - file path on local system | Sets client private key to be used for encrypting SSL communication with a server. | - | `ssl_key` | | `sslSocketSNI(String sni)` | `sni` - server name string | Sets server name to be used for SNI (Server Name Indication) in SSL/TLS connection. | - | `ssl_socket_sni` | | Method | Arguments | Description | Default | Key | | ------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------ | ------- | ---------------------------------------- | | `addProxy(ProxyType type, String host, int port)` | `type` - proxy type
`host` - proxy hostname or IP
`port` - proxy port | Sets proxy to be used for communication with a server. | - | `proxy_type`, `proxy_host`, `proxy_port` | | `setProxyCredentials(String user, String pass)` | `user` - proxy username
`pass` - password | Sets user credentials to authenticate with a proxy. | - | `proxy_user`, `proxy_password` | | Method | Arguments | Description | Default | Key | | ------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------- | | `setHttpCookiesEnabled(boolean enabled)` | `enabled` - flag to enable/disable | Set if HTTP cookies should be remembered and sent to server back. | - | - | | `httpHeader(String key, String value)` | `key` - HTTP header key
`value` - string value | Sets value for a single HTTP header. Previous value is overridden. | `none` | `none` | | `httpHeader(String key, Collection values)` | `key` - HTTP header key
`values` - list of string values | Sets values for a single HTTP header. Previous value is overridden. | `none` | `none` | | `httpHeaders(Map headers)` | `headers` - map with HTTP headers | Sets multiple HTTP header values at a time. | `none` | `none` | | `useHttpFormDataForQuery(boolean enable)` | `enable` - flag to enable/disable | Sets whether query parameters should be sent as HTTP form data in the request body instead of the URL. Works only with server-side compression. If client-level compression is enabled, it will be disabled for query requests with parameters, as each parameter is sent as multipart content. | `false` | `client.http.use_form_request_for_query` | | Method | Arguments | Description | Default | Key | | ----------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------ | | `serverSetting(String name, String value)` | `name` - setting name
`value` - setting value | Sets what settings to pass to server along with each query. Individual operation settings may override it. [List of settings](/concepts/features/configuration/settings/settings-query-level) | `none` | `none` | | `serverSetting(String name, Collection values)` | `name` - setting name
`values` - setting values | Sets what settings to pass to server with multiple values, for example [roles](/concepts/features/interfaces/http#setting-role-with-query-parameters) | `none` | `none` | | `setOption("custom_settings_prefix", value)` | `value` - prefix string | Sets the prefix for custom settings passed to the server. Should be aligned with the server configuration. See [ClickHouse Docs](/concepts/features/configuration/settings/settings-query-level#custom_settings). | `custom_` | `custom_settings_prefix` | | Method | Arguments | Description | Default | Key | | ---------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------- | | `useServerTimeZone(boolean useServerTimeZone)` | `useServerTimeZone` - flag to enable/disable | Sets if client should use server timezone when decoding DateTime and Date column values. | `true` | `use_server_time_zone` | | `useTimeZone(String timeZone)` | `timeZone` - java valid timezone ID | Sets if specified timezone should be used when decoding DateTime and Date column values. Will override server timezone. | - | `use_time_zone` | | `setServerTimeZone(String timeZone)` | `timeZone` - java valid timezone ID | Sets server side timezone. UTC timezone will be used by default. | `UTC` | `server_time_zone` | | Method | Arguments | Description | Default | Key | | ------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ---------------------------- | | `setOption(String key, String value)` | `key` - configuration option key
`value` - option value | Sets raw value of client options. Useful when reading configuration from properties files. | - | - | | `useAsyncRequests(boolean async)` | `async` - flag to enable/disable | Sets if client should execute request in a separate thread. Disabled by default because application knows better how to organize multi-threaded tasks. | `false` | `async` | | `setSharedOperationExecutor(ExecutorService executorService)` | `executorService` - executor service instance | Sets executor service for operation tasks. | `none` | `none` | | `setQueryIdGenerator(Supplier supplier)` | `supplier` - a `Supplier` that generates query IDs | Sets a custom query ID generator used when no query ID is specified in operation settings (`InsertSettings`, `QuerySettings`). | - | - | | `setClientNetworkBufferSize(int size)` | `size` - size in bytes | Sets size of a buffer in application memory space that is used to copy data between socket and application. | `300000` | `client_network_buffer_size` | | `allowBinaryReaderToReuseBuffers(boolean reuse)` | `reuse` - flag to enable/disable | If enabled, reader will use preallocated buffers to do numbers transcoding. Reduces GC pressure for numeric data. | - | - | | `columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy)` | `strategy` - matching strategy implementation | Sets custom strategy to be used for matching DTO class fields and DB columns when registering DTO. | `none` | `none` | | `setClientName(String clientName)` | `clientName` - application name string | Sets additional information about calling application. Will be passed as `User-Agent` header. | - | `client_name` | | `registerClientMetrics(Object registry, String name)` | `registry` - Micrometer registry instance
`name` - metrics group name | Registers sensors with Micrometer ([https://micrometer.io/](https://micrometer.io/)) registry instance. | - | - | | `setServerVersion(String version)` | `version` - server version string | Sets server version to avoid version detection. | - | `server_version` | | `typeHintMapping(Map typeHintMapping)` | `typeHintMapping` - map of type hints | Sets type hint mapping for ClickHouse types. For example, to make multidimensional arrays be present as Java containers. | - | `type_hint_mapping` |

Client Identification

There are two fields in a query log that identify application originated a request: `client_name` and `http_user_agent`. Native TCP protocol uses `client_name` to identify application. HTTP protocol uses `http_user_agent` to identify application. Client builder has method `setClientName` correct values for both protocols. The field `http_user_agent` is set according to `User-Agent` header common format: `application-name[/version] [(operating-system; architecture; ...)]`. This set of values is repeated for each layer: application, client library, http client library. What is set by `setClientName` method comes first in the list. For example: ```java showLineNumbers theme={null} client.setClientName("my-app-01/1.0"); ``` will result in the following `http_user_agent` value: ``` my-app-01/1.0 clickhouse-java-v2/0.9.6-SNAPSHOT (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4 ``` Application can set own http header `User-Agent` to identify itself. But part `clickhouse-java-v2/0.9.6-SNAPSHOT` will be appended to the end of the header.

Operation Identification

Query log has another two fields `query_id` and `log_comment` that can be used to identify an operation and add additional information to the query log. `query_id` is a unique identifier of an operation. It can be set by application by calling `setQueryId` method of the `QuerySettings` class. ```java showLineNumbers theme={null} QuerySettings querySettings = new QuerySettings(); querySettings.setQueryId("some-query-id"); ``` `log_comment` is a comment that can be added to the query log. It can be set by application by calling `logComment` method of the `QuerySettings` class. ```java showLineNumbers theme={null} QuerySettings querySettings = new QuerySettings(); querySettings.logComment("some-comment"); ```

Server Settings

Server side settings can be set on the client level once while creation (see `serverSetting` method of the `Builder`) and on operation level (see `serverSetting` for operation settings class). ```java showLineNumbers theme={null} 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"); ... } ``` ⚠️ When options are set via `setOption` method (either the `Client.Builder` or operation settings class) then server settings name should be prefixed with `clickhouse_setting_`. The `com.clickhouse.client.api.ClientConfigProperties#serverSetting()` may be handy in this case. ### Custom HTTP Header Custom HTTP headers can be set for all operations (client level) or a single one (operation level). ```java showLineNumbers theme={null} QuerySettings settings = new QuerySettings() .httpHeader(HttpHeaders.REFERER, clientReferer) .setQueryId(qId); ``` When options are set via `setOption` method (either the `Client.Builder` or operation settings class) then custom header name should be prefixed with `http_header_`. Method `com.clickhouse.client.api.ClientConfigProperties#httpHeader()` may be handy in this case.

Common Definitions

ClickHouseFormat

Enum of [supported formats](/reference/formats). It includes all formats that ClickHouse supports. * `raw` - user should transcode raw data * `full` - the client can transcode data by itself and accepts a raw data stream * `-` - operation not supported by ClickHouse for this format This client version supports: | Format | Input | Output | | ---------------------------------------------------------------------------------------------------------------- | :---: | :----: | | [TabSeparated](/reference/formats/TabSeparated/TabSeparated) | raw | raw | | [TabSeparatedRaw](/reference/formats/TabSeparated/TabSeparatedRaw) | raw | raw | | [TabSeparatedWithNames](/reference/formats/TabSeparated/TabSeparatedWithNames) | raw | raw | | [TabSeparatedWithNamesAndTypes](/reference/formats/TabSeparated/TabSeparatedWithNamesAndTypes) | raw | raw | | [TabSeparatedRawWithNames](/reference/formats/TabSeparated/TabSeparatedRawWithNames) | raw | raw | | [TabSeparatedRawWithNamesAndTypes](/reference/formats/TabSeparated/TabSeparatedRawWithNamesAndTypes) | raw | raw | | [Template](/reference/formats/Template/Template) | raw | raw | | [TemplateIgnoreSpaces](/reference/formats/Template/TemplateIgnoreSpaces) | raw | - | | [CSV](/reference/formats/CSV/CSV) | raw | raw | | [CSVWithNames](/reference/formats/CSV/CSVWithNames) | raw | raw | | [CSVWithNamesAndTypes](/reference/formats/CSV/CSVWithNamesAndTypes) | raw | raw | | [CustomSeparated](/reference/formats/CustomSeparated/CustomSeparated) | raw | raw | | [CustomSeparatedWithNames](/reference/formats/CustomSeparated/CustomSeparatedWithNames) | raw | raw | | [CustomSeparatedWithNamesAndTypes](/reference/formats/CustomSeparated/CustomSeparatedWithNamesAndTypes) | raw | raw | | [SQLInsert](/reference/formats/SQLInsert) | - | raw | | [Values](/reference/formats/Values) | raw | raw | | [Vertical](/reference/formats/Vertical) | - | raw | | [JSON](/reference/formats/JSON/JSON) | raw | raw | | [JSONAsString](/reference/formats/JSON/JSONAsString) | raw | - | | [JSONAsObject](/reference/formats/JSON/JSONAsObject) | raw | - | | [JSONStrings](/reference/formats/JSON/JSONStrings) | raw | raw | | [JSONColumns](/reference/formats/JSON/JSONColumns) | raw | raw | | [JSONColumnsWithMetadata](/reference/formats/JSON/JSONColumnsWithMetadata) | raw | raw | | [JSONCompact](/reference/formats/JSON/JSONCompact) | raw | raw | | [JSONCompactStrings](/reference/formats/JSON/JSONCompactStrings) | - | raw | | [JSONCompactColumns](/reference/formats/JSON/JSONCompactColumns) | raw | raw | | [JSONEachRow](/reference/formats/JSON/JSONEachRow) | raw | raw | | [PrettyJSONEachRow](/reference/formats/JSON/PrettyJSONEachRow) | - | raw | | [JSONEachRowWithProgress](/reference/formats/JSON/JSONEachRowWithProgress) | - | raw | | [JSONStringsEachRow](/reference/formats/JSON/JSONStringsEachRow) | raw | raw | | [JSONStringsEachRowWithProgress](/reference/formats/JSON/JSONStringsEachRowWithProgress) | - | raw | | [JSONCompactEachRow](/reference/formats/JSON/JSONCompactEachRow) | raw | raw | | [JSONCompactEachRowWithNames](/reference/formats/JSON/JSONCompactEachRowWithNames) | raw | raw | | [JSONCompactEachRowWithNamesAndTypes](/reference/formats/JSON/JSONCompactEachRowWithNamesAndTypes) | raw | raw | | [JSONCompactStringsEachRow](/reference/formats/JSON/JSONCompactStringsEachRow) | raw | raw | | [JSONCompactStringsEachRowWithNames](/reference/formats/JSON/JSONCompactStringsEachRowWithNames) | raw | raw | | [JSONCompactStringsEachRowWithNamesAndTypes](/reference/formats/JSON/JSONCompactStringsEachRowWithNamesAndTypes) | raw | raw | | [JSONObjectEachRow](/reference/formats/JSON/JSONObjectEachRow) | raw | raw | | [BSONEachRow](/reference/formats/BSONEachRow) | raw | raw | | [TSKV](/reference/formats/TabSeparated/TSKV) | raw | raw | | [Pretty](/reference/formats/Pretty/Pretty) | - | raw | | [PrettyNoEscapes](/reference/formats/Pretty/PrettyNoEscapes) | - | raw | | [PrettyMonoBlock](/reference/formats/Pretty/PrettyMonoBlock) | - | raw | | [PrettyNoEscapesMonoBlock](/reference/formats/Pretty/PrettyNoEscapesMonoBlock) | - | raw | | [PrettyCompact](/reference/formats/Pretty/PrettyCompact) | - | raw | | [PrettyCompactNoEscapes](/reference/formats/Pretty/PrettyCompactNoEscapes) | - | raw | | [PrettyCompactMonoBlock](/reference/formats/Pretty/PrettyCompactMonoBlock) | - | raw | | [PrettyCompactNoEscapesMonoBlock](/reference/formats/Pretty/PrettyCompactNoEscapesMonoBlock) | - | raw | | [PrettySpace](/reference/formats/Pretty/PrettySpace) | - | raw | | [PrettySpaceNoEscapes](/reference/formats/Pretty/PrettySpaceNoEscapes) | - | raw | | [PrettySpaceMonoBlock](/reference/formats/Pretty/PrettySpaceMonoBlock) | - | raw | | [PrettySpaceNoEscapesMonoBlock](/reference/formats/Pretty/PrettySpaceNoEscapesMonoBlock) | - | raw | | [Prometheus](/reference/formats/Prometheus) | - | raw | | [Protobuf](/reference/formats/Protobuf/Protobuf) | raw | raw | | [ProtobufSingle](/reference/formats/Protobuf/ProtobufSingle) | raw | raw | | [ProtobufList](/reference/formats/Protobuf/ProtobufList) | raw | raw | | [Avro](/reference/formats/Avro/Avro) | raw | raw | | [AvroConfluent](/reference/formats/Avro/AvroConfluent) | raw | - | | [Parquet](/reference/formats/Parquet/Parquet) | raw | raw | | [ParquetMetadata](/reference/formats/Parquet/ParquetMetadata) | raw | - | | [Arrow](/reference/formats/Arrow/Arrow) | raw | raw | | [ArrowStream](/reference/formats/Arrow/ArrowStream) | raw | raw | | [ORC](/reference/formats/ORC) | raw | raw | | [One](/reference/formats/One) | raw | - | | [Npy](/reference/formats/Npy) | raw | raw | | [RowBinary](/reference/formats/RowBinary/RowBinary) | full | full | | [RowBinaryWithNames](/reference/formats/RowBinary/RowBinaryWithNamesAndTypes) | full | full | | [RowBinaryWithNamesAndTypes](/reference/formats/RowBinary/RowBinaryWithNamesAndTypes) | full | full | | [RowBinaryWithDefaults](/reference/formats/RowBinary/RowBinaryWithDefaults) | full | - | | [Native](/reference/formats/Native) | full | raw | | [Null](/reference/formats/Null) | - | raw | | [XML](/reference/formats/XML) | - | raw | | [CapnProto](/reference/formats/CapnProto) | raw | raw | | [LineAsString](/reference/formats/LineAsString/LineAsString) | raw | raw | | [Regexp](/reference/formats/Regexp) | raw | - | | [RawBLOB](/reference/formats/RawBLOB) | raw | raw | | [MsgPack](/reference/formats/MsgPack) | raw | raw | | [MySQLDump](/reference/formats/MySQLDump) | raw | - | | [DWARF](/reference/formats/DWARF) | raw | - | | [Markdown](/reference/formats/Markdown) | - | raw | | [Form](/reference/formats/Form) | raw | - |

Insert API

insert(String tableName, InputStream data, ClickHouseFormat format)

Accepts data as an `InputStream` of bytes in the specified format. It is expected that `data` is encoded in the `format`. **Signatures** ```java theme={null} CompletableFuture insert(String tableName, InputStream data, ClickHouseFormat format, InsertSettings settings) CompletableFuture insert(String tableName, InputStream data, ClickHouseFormat format) ``` **Parameters** `tableName` - a target table name. `data` - an input stream of an encoded data. `format` - a format in which the data is encoded. `settings` - request settings. **Return value** Future of `InsertResponse` type - result of the operation and additional information like server side metrics. **Examples** ```java showLineNumbers theme={null} 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)

Sends a write request to database. The list of objects is converted into an efficient format and then is sent to a server. The class of the list items should be registered up-front using `register(Class, TableSchema)` method. **Signatures** ```java theme={null} client.insert(String tableName, List data, InsertSettings settings) client.insert(String tableName, List data) ``` **Parameters** `tableName` - name of the target table. `data` - collection DTO (Data Transfer Object) objects. `settings` - request settings. **Return value** Future of `InsertResponse` type - the result of the operation and additional information like server side metrics. **Examples** ```java showLineNumbers theme={null} // 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 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

Configuration options for insert operations. **Configuration methods** | Method | Description | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `setQueryId(String queryId)` | Sets query ID that will be assigned to the operation. Default: `null`. | | `setDeduplicationToken(String token)` | Sets the deduplication token. This token will be sent to the server and can be used to identify the query. Default: `null`. | | `setInputStreamCopyBufferSize(int size)` | Copy buffer size. The buffer is used during write operations to copy data from user-provided input stream to an output stream. Default: `8196`. | | `serverSetting(String name, String value)` | Sets individual server settings for an operation. | | `serverSetting(String name, Collection values)` | Sets individual server settings with multiple values for an operation. Items of the collection should be `String` values. | | `setDBRoles(Collection dbRoles)` | Sets DB roles to be set before executing an operation. Items of the collection should be `String` values. | | `setOption(String option, Object value)` | Sets a configuration option in raw format. This isn't a server setting. |

InsertResponse

Response object that holds result of insert operation. It is only available if the client got response from a server. This object should be closed as soon as possible to release a connection because the connection can't be re-used until all data of previous response is fully read. | Method | Description | | ------------------------------- | --------------------------------------------------------------------------------------------------------- | | `OperationMetrics getMetrics()` | Returns object with operation metrics. | | `String getQueryId()` | Returns query ID assigned for the operation by the application (through operation settings or by server). |

Query API

query(String sqlQuery)

Sends `sqlQuery` as is. Response format is set by query settings. `QueryResponse` will hold a reference to the response stream that should be consumed by a reader for the supportig format. **Signatures** ```java theme={null} CompletableFuture query(String sqlQuery, QuerySettings settings) CompletableFuture query(String sqlQuery) ``` **Parameters** `sqlQuery` - a single SQL statement. The Query is sent as is to a server. `settings` - request settings. **Return value** Future of `QueryResponse` type - a result dataset and additional information like server side metrics. The Response object should be closed after consuming the dataset. **Examples** ```java theme={null} 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\ queryParams, QuerySettings settings)

Sends `sqlQuery` as is. Additionally will send query parameters so the server can compile the SQL expression. **Signatures** ```java theme={null} CompletableFuture query(String sqlQuery, Map queryParams, QuerySettings settings) ``` **Parameters** `sqlQuery` - sql expression with placeholders `{}`. `queryParams` - map of variables to complete the sql expression on server. `settings` - request settings. **Return value** Future of `QueryResponse` type - a result dataset and additional information like server side metrics. The Response object should be closed after consuming the dataset. **Examples** ```java showLineNumbers theme={null} // define parameters. They will be sent to the server along with the request. Map 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)

Queries a data in `RowBinaryWithNamesAndTypes` format. Returns the result as a collection. Read performance is the same as with the reader but more memory is required to hold the whole dataset. **Signatures** ```java theme={null} List queryAll(String sqlQuery) ``` **Parameters** `sqlQuery` - sql expression to query data from a server. **Return value** Complete dataset represented by a list of `GenericRecord` objects that provide access in row style for the result data. **Examples** ```java showLineNumbers theme={null} 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

Configuration options for query operations. **Configuration methods** | Method | Description | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `setQueryId(String queryId)` | Sets query ID that will be assigned to the operation. | | `setFormat(ClickHouseFormat format)` | Sets response format. See `RowBinaryWithNamesAndTypes` for the full list. | | `setMaxExecutionTime(Integer maxExecutionTime)` | Sets operation execution time on server. Won't affect read timeout. | | `waitEndOfQuery(Boolean waitEndOfQuery)` | Requests the server to wait for the end of the query before sending a response. | | `setUseServerTimeZone(Boolean useServerTimeZone)` | Server timezone (see client config) will be used to parse date/time types in the result of an operation. Default `false`. | | `setUseTimeZone(String timeZone)` | Requests server to use `timeZone` for time conversion. See [session\_timezone](/reference/settings/session-settings#session_timezone). | | `serverSetting(String name, String value)` | Sets individual server settings for an operation. | | `serverSetting(String name, Collection values)` | Sets individual server settings with multiple values for an operation. Items of the collection should be `String` values. | | `setDBRoles(Collection dbRoles)` | Sets DB roles to be set before executing an operation. Items of the collection should be `String` values. | | `setOption(String option, Object value)` | Sets a configuration option in raw format. This isn't a server setting. |

QueryResponse

Response object that holds result of query execution. It is only available if the client got a response from a server. This object should be closed as soon as possible to release a connection because the connection can't be re-used until all data of previous response is fully read. | Method | Description | | ------------------------------- | --------------------------------------------------------------------------------------------------------- | | `ClickHouseFormat getFormat()` | Returns a format in which data in the response is encoded. | | `InputStream getInputStream()` | Returns uncompressed byte stream of data in the specified format. | | `OperationMetrics getMetrics()` | Returns object with operation metrics. | | `String getQueryId()` | Returns query ID assigned for the operation by the application (through operation settings or by server). | | `TimeZone getTimeZone()` | Returns timezone that should be used for handling Date/DateTime types in the response. |

Examples

* Example code is available in [repo](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2) * Reference Spring Service [implementation](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-service)

Common API

getTableSchema(String table)

Fetches table schema for the `table`. **Signatures** ```java theme={null} TableSchema getTableSchema(String table) TableSchema getTableSchema(String table, String database) ``` **Parameters** `table` - table name for which schema data should be fetched. `database` - database where the target table is defined. **Return value** Returns a `TableSchema` object with list of table columns.

getTableSchemaFromQuery(String sql)

Fetches schema from a SQL statement. **Signatures** ```java theme={null} TableSchema getTableSchemaFromQuery(String sql) ``` **Parameters** `sql` - "SELECT" SQL statement which schema should be returned. **Return value** Returns a `TableSchema` object with columns matching the `sql` expression.

TableSchema

register(Class\ clazz, TableSchema schema)

Compiles serialization and deserialization layer for the Java Class to use for writing/reading data with `schema`. The method will create a serializer and deserializer for the pair getter/setter and corresponding column. Column match is found by extracting its name from a method name. For example, `getFirstName` will be for the column `first_name` or `firstname`. **Signatures** ```java theme={null} void register(Class clazz, TableSchema schema) ``` **Parameters** `clazz` - Class representing the POJO used to read/write data. `schema` - Data schema to use for matching with POJO properties. **Examples** ```java showLineNumbers theme={null} client.register(ArticleViewEvent.class, client.getTableSchema(TABLE_NAME)); ```

Usage Examples

Complete examples code is stored in the repo in a 'example\` [folder](https://github.com/ClickHouse/clickhouse-java/tree/main/examples): * [client-v2](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2) - main set of examples. * [demo-service](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-service) - example of how to use the client in a Spring Boot application. * [demo-kotlin-service](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-kotlin-service) - example of how to use the client in Ktor (Kotlin) application.

Reading Data

There are two common ways to read data: * `query()` method that returns low-level `QueryResponse` object that contains `InputStream` with data. Usually combined with `ClickHouseBinaryFormatReader` for streaming reads but can be used with any other custom reader implementation. `QueryResponse` also provides access to the result set metadata and metrics. * `queryAll()` method and using `GenericRecord` for convenient row access. In this case the whole result set is loaded into memory. * `queryRecords()` method that returns `com.clickhouse.client.api.query.Records` - an iterator for `GenericRecord` objects. This method uses streaming approach (no data is loaded into memory) and utilises `GenericRecord` to access data. **Note:** streaming approach requires fast read otherwise it may cause server write timeout because data is read directly from the network stream.

Reading Arrays

**`ClickHouseBinaryFormatReader` Methods** * `getList(...)` - reads any `Array(...)` as `List`. Good default for flexible typed reads. Supports nested arrays. * `getByteArray(...)`, `getShortArray(...)`, `getIntArray(...)`, `getLongArray(...)`, `getFloatArray(...)`, `getDoubleArray(...)`, `getBooleanArray(...)` - best for 1D arrays of primitive-compatible values. * `getStringArray(...)` - for `Array(String)` (and enum values represented as names). * `getObjectArray(...)` - generic option for any `Array(...)` element type, including nested arrays. Use to read arrays with nullable values and nested arrays. Index-based and name-based overloads are available for all methods. Index is 1-based. Index-based do dirrect access to a column. Name-based methods require index lookup each time. ```java theme={null} 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` Methods** * `getList(...)` - reads any `Array(...)` as `List`. Good default for flexible typed reads. Supports nested arrays. * `getByteArray(...)`, `getShortArray(...)`, `getIntArray(...)`, `getLongArray(...)`, `getFloatArray(...)`, `getDoubleArray(...)`, `getBooleanArray(...)` - best for 1D arrays of primitive-compatible values. * `getStringArray(...)` - for `Array(String)` (and enum values represented as names). * `getObjectArray(...)` - generic option for any `Array(...)` element type, including nested arrays. Use to read arrays with nullable values and nested arrays. Index-based and name-based overloads are available for all methods. Index is 1-based. Index-based do dirrect access to a column. Name-based methods require index lookup each time. ```java theme={null} try (QueryResponse response = client.query("SELECT * FROM my_table").get()) { List 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 | V1 Configuration | V2 Builder Method | Comments | | -------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------- | | `ClickHouseDefaults#HOST` | `Client.Builder#addEndpoint` | | | `ClickHouseDefaults#PROTOCOL` | ✗ | Only HTTP supported in V2 | | `ClickHouseDefaults#DATABASE`
`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`
`ClickHouseHttpOption#KEEP_ALIVE_TIMEOUT` | `Client.Builder#setKeepAliveTimeout` | | | `ClickHouseHttpOption#CONNECTION_REUSE_STRATEGY` | `Client.Builder#setConnectionReuseStrategy` | | | `ClickHouseHttpOption#USE_BASIC_AUTHENTICATION` | `Client.Builder#useHTTPBasicAuth` | | | 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 | | 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` | | | 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` | ✗ | | | 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` | | | 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` | ✗ | | | V1 Configuration | V2 Builder Method | Comments | | ------------------------------------------------------------------------------------ | ---------------------------------- | -------- | | `ClickHouseDefaults#SERVER_TIME_ZONE`
`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` | | | 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` | ✗ | | | V1 Configuration | V2 Builder Method | Comments | | -------------------------------------------------------------- | --------------------------------- | -------------------------------- | | `ClickHouseDefaults#ASYNC`
`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` | ✗ | | | 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 | | V1 Configuration | V2 Builder Method | Comments | | ---------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------- | | `ClickHouseDefaults#FORMAT`
`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` | | 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` | ✗ | | | 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`
`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` | ✗ | | ### 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 theme={null} InputStream inData = getInData(); ClickHouseRequest.Mutation request = client.read(server) .write() .table(tableName) .format(ClickHouseFormat.TSV); ClickHouseConfig config = request.getConfig(); CompletableFuture 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 Insert TSV formatted data.** ```java theme={null} 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 } ``` * there is a single method to call. No need to create an additional request object. * request body stream is closed automatically when all data is copied. * new low-level API is available `com.clickhouse.client.api.Client#insert(java.lang.String, java.util.List, com.clickhouse.client.api.DataStreamWriter, com.clickhouse.data.ClickHouseFormat, com.clickhouse.client.api.insert.InsertSettings)`. `com.clickhouse.client.api.DataStreamWriter` is designed to implement custom data writing logic. For instance, reading data from a queue. ### Reading Data * Data is read in `RowBinaryWithNamesAndTypes` format by default. Currently only this format is supported when data binding is required. * Data can be read as a collection of records using `List com.clickhouse.client.api.Client#queryAll(java.lang.String)` method. It will read data to a memory and release connection. No need for extra handling. `GenericRecord` gives access to data, implements some conversions. ```java theme={null} Collection 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"); } ``` Java client library to communicate with a DB server through its protocols. Current implementation supports only [HTTP interface](/concepts/features/interfaces/http). The library provides own API to send requests to a server. **Deprecation** This library will be deprecated soon. Use the latest [Java Client](/integrations/language-clients/java/client) for new projects

Setup

```xml theme={null} com.clickhouse clickhouse-http-client 0.7.2 ``` ```kotlin theme={null} // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-http-client implementation("com.clickhouse:clickhouse-http-client:0.7.2") ``` ```groovy theme={null} // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-http-client implementation 'com.clickhouse:clickhouse-http-client:0.7.2' ``` Since version `0.5.0`, the driver uses a new client http library that needs to be added as a dependency. ```xml theme={null} org.apache.httpcomponents.client5 httpclient5 5.3.1 ``` ```kotlin theme={null} // https://mvnrepository.com/artifact/org.apache.httpcomponents.client5/httpclient5 implementation("org.apache.httpcomponents.client5:httpclient5:5.3.1") ``` ```groovy theme={null} // https://mvnrepository.com/artifact/org.apache.httpcomponents.client5/httpclient5 implementation 'org.apache.httpcomponents.client5:httpclient5:5.3.1' ```

Initialization

Connection URL Format: `protocol://host[:port][/database][?param[=value][¶m[=value]][#tag[,tag]]`, for example: * `http://localhost:8443?ssl=true&sslmode=NONE` * `https://(https://explorer@play.clickhouse.com:443` Connect to a single node: ```java showLineNumbers theme={null} ClickHouseNode server = ClickHouseNode.of("http://localhost:8123/default?compress=0"); ``` Connect to a cluster with multiple nodes: ```java showLineNumbers theme={null} ClickHouseNodes servers = ClickHouseNodes.of( "jdbc:ch:http://server1.domain,server2.domain,server3.domain/my_db" + "?load_balancing_policy=random&health_check_interval=5000&failover=2"); ```

Query API

```java showLineNumbers theme={null} try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP); ClickHouseResponse response = client.read(servers) .format(ClickHouseFormat.RowBinaryWithNamesAndTypes) .query("select * from numbers limit :limit") .params(1000) .executeAndWait()) { ClickHouseResponseSummary summary = response.getSummary(); long totalRows = summary.getTotalRowsToRead(); } ```

Streaming Query API

```java showLineNumbers theme={null} try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP); ClickHouseResponse response = client.read(servers) .format(ClickHouseFormat.RowBinaryWithNamesAndTypes) .query("select * from numbers limit :limit") .params(1000) .executeAndWait()) { for (ClickHouseRecord r : response.records()) { int num = r.getValue(0).asInteger(); // type conversion String str = r.getValue(0).asString(); LocalDate date = r.getValue(0).asDate(); } } ``` See [complete code example](https://github.com/ClickHouse/clickhouse-java/blob/main/examples/client/src/main/java/com/clickhouse/examples/jdbc/Main.java#L73) in the [repo](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client).

Insert API

```java showLineNumbers theme={null} try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP); ClickHouseResponse response = client.read(servers).write() .format(ClickHouseFormat.RowBinaryWithNamesAndTypes) .query("insert into my_table select c2, c3 from input('c1 UInt8, c2 String, c3 Int32')") .data(myInputStream) // `myInputStream` is source of data in RowBinary format .executeAndWait()) { ClickHouseResponseSummary summary = response.getSummary(); summary.getWrittenRows(); } ``` See [complete code example](https://github.com/ClickHouse/clickhouse-java/blob/main/examples/client/src/main/java/com/clickhouse/examples/jdbc/Main.java#L39) in the [repo](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client). **RowBinary Encoding** RowBinary format is described on its [page](/reference/formats/RowBinary/RowBinaryWithNamesAndTypes). There is an example of [code](https://github.com/ClickHouse/clickhouse-kafka-connect/blob/main/src/main/java/com/clickhouse/kafka/connect/sink/db/ClickHouseWriter.java#L622).

Features

Compression

The client will by default use LZ4 compression, which requires this dependency: ```xml theme={null} org.lz4 lz4-java 1.8.0 ``` ```kotlin theme={null} // https://mvnrepository.com/artifact/org.lz4/lz4-java implementation("org.lz4:lz4-java:1.8.0") ``` ```groovy theme={null} // https://mvnrepository.com/artifact/org.lz4/lz4-java implementation 'org.lz4:lz4-java:1.8.0' ``` You can choose to use gzip instead by setting `compress_algorithm=gzip` in the connection URL. Alternatively, you can disable compression a few ways. 1. Disable by setting `compress=0` in the connection URL: `http://localhost:8123/default?compress=0` 2. Disable via the client configuration: ```java showLineNumbers theme={null} ClickHouseClient client = ClickHouseClient.builder() .config(new ClickHouseConfig(Map.of(ClickHouseClientOption.COMPRESS, false))) .nodeSelector(ClickHouseNodeSelector.of(ClickHouseProtocol.HTTP)) .build(); ``` See the [compression documentation](/guides/clickhouse/data-modelling/compression/compression-modes) to learn more about different compression options.

Multiple queries

Execute multiple queries in a worker thread one after another within same session: ```java showLineNumbers theme={null} CompletableFuture> future = ClickHouseClient.send(servers.apply(servers.getNodeSelector()), "create database if not exists my_base", "use my_base", "create table if not exists test_table(s String) engine=Memory", "insert into test_table values('1')('2')('3')", "select * from test_table limit 1", "truncate table test_table", "drop table if exists test_table"); List results = future.get(); ```

Named Parameters

You can pass parameters by name rather than relying solely on their position in the parameter list. This capability is available using `params` function. ```java showLineNumbers theme={null} try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP); ClickHouseResponse response = client.read(servers) .format(ClickHouseFormat.RowBinaryWithNamesAndTypes) .query("select * from my_table where name=:name limit :limit") .params("Ben", 1000) .executeAndWait()) { //... } } ``` **Parameters** All `params` signatures involving `String` type (`String`, `String[]`, `Map`) assume the keys being passed are valid ClickHouse SQL strings. For instance: ```java showLineNumbers theme={null} try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP); ClickHouseResponse response = client.read(servers) .format(ClickHouseFormat.RowBinaryWithNamesAndTypes) .query("select * from my_table where name=:name") .params(Map.of("name","'Ben'")) .executeAndWait()) { //... } } ``` If you prefer not to parse String objects to ClickHouse SQL manually, you can use the helper function `ClickHouseValues.convertToSqlExpression` located at `com.clickhouse.data`: ```java showLineNumbers theme={null} try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP); ClickHouseResponse response = client.read(servers) .format(ClickHouseFormat.RowBinaryWithNamesAndTypes) .query("select * from my_table where name=:name") .params(Map.of("name", ClickHouseValues.convertToSqlExpression("Ben's"))) .executeAndWait()) { //... } } ``` In the example above, `ClickHouseValues.convertToSqlExpression` will escape the inner single quote, and surround the variable with a valid single quotes. Other types, such as `Integer`, `UUID`, `Array` and `Enum` will be converted automatically inside `params`.

Node Discovery

Java client provides the ability to discover ClickHouse nodes automatically. Auto-discovery is disabled by default. To manually enable it, set `auto_discovery` to `true`: ```java theme={null} properties.setProperty("auto_discovery", "true"); ``` Or in the connection URL: ```plaintext theme={null} jdbc:ch://my-server/system?auto_discovery=true ``` If auto-discovery is enabled, there is no need to specify all ClickHouse nodes in the connection URL. Nodes specified in the URL will be treated as seeds, and the Java client will automatically discover more nodes from system tables and/or clickhouse-keeper or zookeeper. The following options are responsible for auto-discovery configuration: | Property | Default | Description | | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------- | | auto\_discovery | `false` | Whether the client should discover more nodes from system tables and/or clickhouse-keeper/zookeeper. | | node\_discovery\_interval | `0` | Node discovery interval in milliseconds, zero or negative value means one-time discovery. | | node\_discovery\_limit | `100` | Maximum number of nodes that can be discovered at a time; zero or negative value means no limit. |

Load Balancing

The Java client chooses a ClickHouse node to send requests to, according to the load-balancing policy. In general, the load-balancing policy is responsible for the following things: 1. Get a node from a managed node list. 2. Managing node's status. 3. Optionally schedule a background process for node discovery (if auto-discovery is enabled) and run a health check. Here is a list of options to configure load balancing: | Property | Default | Description | | ----------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | load\_balancing\_policy | `""` | The load-balancing policy can be one of:
  • `firstAlive` - request is sent to the first healthy node from the managed node list
  • `random` - request is sent to a random node from the managed node list
  • `roundRobin` - request is sent to each node from the managed node list, in turn.
  • full qualified class name implementing `ClickHouseLoadBalancingPolicy` - custom load balancing policy
    • If it isn't specified the request is sent to the first node from the managed node list | | load\_balancing\_tags | `""` | Load balancing tags for filtering out nodes. Requests are sent only to nodes that have the specified tags | | health\_check\_interval | `0` | Health check interval in milliseconds, zero or negative value means one-time. | | health\_check\_method | `ClickHouseHealthCheckMethod.SELECT_ONE` | Health check method. Can be one of:
  • `ClickHouseHealthCheckMethod.SELECT_ONE` - check with `select 1` query
  • `ClickHouseHealthCheckMethod.PING` - protocol-specific check, which is generally faster
    • | | node\_check\_interval | `0` | Node check interval in milliseconds, negative number is treated as zero. The node status is checked if the specified amount of time has passed since the last check.
    The difference between `health_check_interval` and `node_check_interval` is that the `health_check_interval` option schedules the background job, which checks the status for the list of nodes (all or faulty), but `node_check_interval` specifies the amount of time has passed since the last check for the particular node | | check\_all\_nodes | `false` | Whether to perform a health check against all nodes or just faulty ones. |

    Failover and retry

    Java client provides configuration options to set up failover and retry behavior for failed queries: | Property | Default | Description | | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | failover | `0` | Maximum number of times a failover can happen for a request. Zero or a negative value means no failover. Failover sends the failed request to a different node (according to the load-balancing policy) in order to recover from failover. | | retry | `0` | Maximum number of times retry can happen for a request. Zero or a negative value means no retry. Retry sends a request to the same node and only if the ClickHouse server returns the `NETWORK_ERROR` error code | | repeat\_on\_session\_lock | `true` | Whether to repeat execution when the session is locked until timed out(according to `session_timeout` or `connect_timeout`). The failed request is repeated if the ClickHouse server returns the `SESSION_IS_LOCKED` error code |

    Adding custom http headers

    Java client support HTTP/S transport layer in case we want to add custom HTTP headers to the request. We should use the custom\_http\_headers property, and the headers need to be `,` separated. The header key/value should be divided using `=`

    Java Client support

    ```java theme={null} options.put("custom_http_headers", "X-ClickHouse-Quota=test, X-ClickHouse-Test=test"); ```

    JDBC Driver

    ```java theme={null} properties.setProperty("custom_http_headers", "X-ClickHouse-Quota=test, X-ClickHouse-Test=test"); ```