Skip to main content

Java Client (V2)

Implementation of a new API. It uses Apache Http Client to communicate with ClickHouse server. We have selected this http client because it has many built-in features and has proven itself in old client implementation. We are planning to support other http client libraries.

Note: Client-V2 is currently in the phase of active development and we are still working on it.

Setup​

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

Initialization​

Client object is initialized by com.clickhouse.client.api.Client.Builder#build(). Each client has own context and no objects are shared between them. Builder has configuration method for convinient setup.

Example: 

 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.

Configuration​

All settings are defined by instance methods (a.k.a configuration methods) that make scope and context of each value clear. Major configuration parameters are defined in one scope (client or operation) and do not override each other. Handling configuration overriding across is a very hard task so we doing our best to keep it simple.

This section describes only client wide settings. Each operation may have own and will be listed in the their sections.

Insert API​

insert(String tableName, InputStream data)​

Sends write request to database. Input data is read from the input stream.

Signatures

CompletableFuture<InsertResponse> insert(String tableName, InputStream data, ClickHouseFormat format, InsertSettings settings)
CompletableFuture<InsertResponse> 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 operation and additional information like server side metrics.

Examples

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 write request to database. List of objects is converted into a most effective format and then is sent to a server. Class of the list items should be registed up-front using register(Class, TableSchema) method.

Signatures

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 - result of operation and additional information like server side metrics.

Examples

// 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<ArtivleViewEvent> 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. 
}

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 what should be consumer by a reader for supportig format

Signatures

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

Parameters

Return value

Future of QueryResponse type - a result dataset and additional information like server side metrics. Response object should be closed after consuming the dataset.

Examples


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

Sends sqlQuery as is. Additionally will send query parameter so server can comple SQL expression.

Signatures

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

Parameters

sqlQuery - sql expression with placeholders {}

queryParams - map of variables to complete sql expression on server

settings - request settings

Return value

Future of QueryResponse type - a result dataset and additional information like server side metrics. Response object should be closed after consuming the dataset.

queryAll(String sqlQuery)​

Queries a data in RowBinaryWithNamesAndTypes format. Returns result as a collection. Read performance is the same as with reader but more memory required at a time to keep whole dataset.

Signatures

List<GenericRecord> queryAll(String sqlQuery)

Parameters

sqlQuery - sql expression to query data from a serve r

Return value

Complete dataset represented by list of GenericRecord object that provide access in row style for the result data.

Examples

QuerySettings​

Configuration methods

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. Will not affect read timeout.
waitEndOfQuery(Boolean waitEndOfQuery)
Requests the server to wait for the and of the query before sending 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`)[https://clickhouse.com/docs/en/operations/settings/settings#session_timezone]

Examples​

Common API​