Java Client

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 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<String> supplier)` `supplier` - a `Supplier<String>` 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/>) 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[​](#client-identification "Direct link to 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:

```
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[​](#operation-identification "Direct link to 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.

```
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.

```
QuerySettings querySettings = new QuerySettings();
querySettings.logComment("some-comment");
```

### Server Settings[​](#server-settings "Direct link to 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).

```
 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-header "Direct link to Custom HTTP Header")

Custom HTTP headers can be set for all operations (client level) or a single one (operation level).

```
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.