Java client

​

Setup

• Maven Central (project web page): https://mvnrepository.com/artifact/com.clickhouse/client-v2
• Nightly builds (repository link): https://central.sonatype.com/repository/maven-snapshots/

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

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

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

​

Initialization

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

​

Authentication

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

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

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

​

Connection Pooling

​

Recommended Connection Pool Configuration

Client client = new Client.Builder()
        .addEndpoint("https://clickhouse-cloud-instance:8443/")
        .setUsername("default")
        .setPassword("secret")
        .setMaxConnections(50)
        .setConnectionRequestTimeout(5, TimeUnit.SECONDS)
        .setKeepAliveTimeout(60, TimeUnit.SECONDS)
        .setConnectionReuseStrategy(ConnectionReuseStrategy.FIFO)
        .build();

​

Configuration

​

Client Configuration

​

Client Identification

client.setClientName("my-app-01/1.0");

my-app-01/1.0 clickhouse-java-v2/0.9.6-SNAPSHOT (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4

​

Operation Identification

QuerySettings querySettings = new QuerySettings();
querySettings.setQueryId("some-query-id");

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

​

Server Settings

 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");

	...
}

​

Custom HTTP Headers

Map<String, String> userHeaders = new HashMap<>();
userHeaders.put("X-User-Header1", "value1");
userHeaders.put("X-User-Header2", "value2");

Client client = new Client.Builder()
        .addEndpoint("https://clickhouse-cloud-instance:8443/")
        .setUsername(user)
        .setPassword(password)
        .httpHeader("X-ClickHouse-Quota", "test")
        .httpHeader("X-Forwarded-For", Arrays.asList("1.2.3.4", "5.6.7.8"))
        .httpHeaders(userHeaders)
        .build();

clientBuilder.setOption(ClientConfigProperties.httpHeader("X-ClickHouse-Quota"), "test");
// equivalent to:
clientBuilder.setOption("http_header_X-CLICKHOUSE-QUOTA", "test");

​

ClickHouse Cloud Features

​

Replica-aware Routing (CLOUD)

String replicaTag = "my-app-session-1";

try (Client client = new Client.Builder()
        .addEndpoint("https://your-service.clickhouse.cloud:8443")
        .setUsername(user)
        .setPassword(password)
        .httpHeader(ClickHouseHttpProto.HEADER_REPLICA_TAG, replicaTag)
        .build()) {
    client.query("SELECT hostname()").get();
}

​

JWT Authentication (CLOUD)

​

Initial Configuration

import com.clickhouse.client.api.Client;

public Client createJwtClient(String jwtToken) {
    return new Client.Builder()
            .addEndpoint("https://your-service.clickhouse.cloud:8443")
            .useBearerTokenAuth(jwtToken)
            .build();
}

​

Updating Token at Runtime

import com.clickhouse.client.api.Client;

public void refreshJwtToken(Client client, String newJwtToken) {
    // Set the new JWT before the current token expires
    client.updateBearerToken(newJwtToken);
}

​

Common Definitions

​

ClickHouseFormat

• 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

​

Insert API

​

insert(String tableName, InputStream data, ClickHouseFormat format)

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

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)

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

// 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

​

InsertResponse

​

Query API

• QuerySettings#setFormat() this will set format header in a request.
• In FORMAT clause in query itself.
• Server settings default_format (/reference/settings/session-settings/default#default_format)

• Client < 0.11.0 & ClickHouse < 26.8 - FORMAT clause has priority over request format header.
• Client > 0.11.0 & ClickHouse > 26.8 - request header has priority over FORMAT clause.
  • Client sets header when no format is specified in QuerySettings - this doesn’t allow to override format in query.
• Client starting 0.11.0 - sets default format value on client level and not on operation level. This allows existing code work without changes and new code to use FORMAT clause by settings format on client to null.

​

query(String sqlQuery)

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

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)

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

// 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)

List<GenericRecord> queryAll(String sqlQuery)

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

​

QueryResponse

​

Examples

• Example code is available in repo
• Reference Spring Service implementation

​

Common API

​

getTableSchema(String table)

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

​

getTableSchemaFromQuery(String sql)

TableSchema getTableSchemaFromQuery(String sql)

​

TableSchema

​

register(Class<?> clazz, TableSchema schema)

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

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

​

Usage Examples

• client-v2 - main set of examples.
• demo-service - example of how to use the client in a Spring Boot application.
• demo-kotlin-service - example of how to use the client in Ktor (Kotlin) application.

​

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

​

Reading Arrays

• getList(...) - reads any Array(...) as List<T>. 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.

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];
    }
}

• getList(...) - reads any Array(...) as List<T>. 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.

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
    }
}

​

Observability & Monitoring

​

Client Builder Observability API

• setMetricsRecorder(MetricsRecorder recorder): Registers a metrics recorder for exporting operational metrics (durations, counts, retries, errors). When not explicitly set, defaults to DefaultMetricsRecorder.NOOP.
• setSpanRecorder(SpanRecorder recorder): Registers a span recorder for distributed tracing (operation spans and transport request spans). When not explicitly set, defaults to DefaultSpanRecorder.NOOP.
• registerClientMetrics(Object registry, String groupName): Binds Apache HttpClient connection pool metrics (such as available and leased connections, pending requests, and connection creation time) to a Micrometer MeterRegistry.

import com.clickhouse.client.api.Client;
import com.clickhouse.client.api.observability.micrometer.MicrometerMetricsRecorder;
import com.clickhouse.client.api.observability.otel.OpenTelemetrySpanRecorder;

import io.micrometer.core.instrument.MeterRegistry;
import io.opentelemetry.api.OpenTelemetry;

public Client createObservedClient(MeterRegistry meterRegistry, OpenTelemetry openTelemetry) {
    return new Client.Builder()
        .addEndpoint("http://localhost:8123")
        .setUsername("default")
        .setPassword("secret")
        .setMetricsRecorder(new MicrometerMetricsRecorder(meterRegistry))
        .setSpanRecorder(new OpenTelemetrySpanRecorder(openTelemetry))
        .registerClientMetrics(meterRegistry, "clickhouse-client-pool")
        .build();
}

1. OpenTelemetry Agent & Global Autoconfiguration:
   • For applications using the OpenTelemetry Java Agent or global SDK autoconfiguration, instantiate OpenTelemetrySpanRecorder and MicrometerMetricsRecorder using their default no-argument constructors.
   • The default constructors automatically bind to GlobalOpenTelemetry.get() and Micrometer’s Metrics.globalRegistry.
2. Explicit Client-Level Integration:
   • Pass explicitly created OpenTelemetry, Tracer, or Micrometer MeterRegistry instances directly into the recorder constructors.
   • Ideal when managing multiple isolated clients or multi-tenant services with independent telemetry sinks.

import com.clickhouse.client.api.Client;
import com.clickhouse.client.api.observability.micrometer.MicrometerMetricsRecorder;
import com.clickhouse.client.api.observability.otel.OpenTelemetrySpanRecorder;

public Client.Builder configureGlobalTelemetry(Client.Builder builder) {
    return builder
        .setMetricsRecorder(new MicrometerMetricsRecorder()) // uses Metrics.globalRegistry
        .setSpanRecorder(new OpenTelemetrySpanRecorder());    // uses GlobalOpenTelemetry
}

​

Metrics Reported

​

Operational Metrics

​

Metric Attributes / Tags

​

Connection Pool Metrics

• httpcomponents.httpclient.pool.total.max: Configured maximum allowed persistent connections.
• httpcomponents.httpclient.pool.total.connections (tagged with state="available" or state="leased"): Active connections in the pool.
• httpcomponents.httpclient.pool.total.pending: Number of connection requests awaiting a free connection.
• httpcomponents.httpclient.pool.route.max.default: Configured default maximum connections per route.
• httpcomponents.httpclient.connect.time: Running average connection establishment time.

​

Response Metrics API

import com.clickhouse.client.api.Client;
import com.clickhouse.client.api.metrics.ClientMetrics;
import com.clickhouse.client.api.metrics.OperationMetrics;
import com.clickhouse.client.api.metrics.ServerMetrics;
import com.clickhouse.client.api.query.QueryResponse;

public void inspectResponseMetrics(Client client) throws Exception {
    try (QueryResponse response = client.query("SELECT * FROM my_table").get()) {
        OperationMetrics metrics = response.getMetrics();
        long readRows = metrics.getMetric(ServerMetrics.NUM_ROWS_READ).getLong();
        long readBytes = metrics.getMetric(ServerMetrics.NUM_BYTES_READ).getLong();
        long durationMs = metrics.getMetric(ClientMetrics.OP_DURATION).getLong();
    }
}

​

Spans Reported

1. Operation Span: Represents a high-level client operation (QUERY <database> or INSERT <database>.<table_name>). Started under the current thread’s trace context (Context.current()) so that database operations join the caller’s active trace span.
2. Transport Request Span: Represents an individual HTTP transport request attempt (POST). Created as a child of the corresponding operation span. Each retry attempt creates a new transport request span under the operation span.

​

Span Attributes

import io.opentelemetry.context.Context;
import io.opentelemetry.context.Scope;
import com.clickhouse.client.api.Client;
import com.clickhouse.client.api.insert.InsertResponse;

public void processBatchAsync(Client client, String table, List<?> data, Context parentContext) throws Exception {
    try (Scope ignored = parentContext.makeCurrent()) {
        try (InsertResponse response = client.insert(table, data).get()) {
            // Background Client V2 span joins parentContext trace
        }
    }
}

​

Developing Custom Recorders

• DefaultMetricsRecorder: Base implementation of MetricsRecorder. Override specific callbacks like recordQuerySuccess or recordQueryFailure. Use MetricsSupport.DEFAULT to derive standard metric names (MetricName), units, and attribute maps (MetricAttribute).
• DefaultSpanRecorder: Base implementation of SpanRecorder. Override span creation callbacks like startQuerySpan, startInsertSpan, or startRequestSpan. Use SpanSupport.DEFAULT to calculate standard OpenTelemetry span names and attributes (SpanAttribute).

• com.clickhouse.client.api.observability.otel.OpenTelemetrySpanRecorder (OpenTelemetry tracing integration)
• com.clickhouse.client.api.observability.micrometer.MicrometerMetricsRecorder (Micrometer metrics integration)

​

Migration Guide

• 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

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

​

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.

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");
    }
}

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<java.lang.String>, 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<GenericRecord> 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.

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");
}