Skip to content

ClickHouse/clickhouse-java

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

ClickHouse Java Libraries

GitHub release (latest SemVer including pre-releases) GitHub release (by tag) Coverage Sonatype Nexus (Snapshots) GitHub milestone

Java libraries for connecting to ClickHouse and processing data in various formats. Java client is async, lightweight, and low-overhead library for ClickHouse; while JDBC and R2DBC drivers are built on top of the Java client with more dependencies and features. Java 8 or higher is required to use the libraries. In addition, please use ClickHouse 20.7+ or any of active releases.

image

Features

Category Feature Supported Remark
API JDBC
R2DBC supported since 0.4.0
Protocol HTTP recommended, defaults to java.net.HttpURLConnection and it can be changed to java.net.http.HttpClient(unstable) or Apache HTTP Client 5. Note that the latter was added in 0.4.0 to support custom socket options.
gRPC still experimental, works with 22.3+, known to has issue when using LZ4 compression
TCP/Native clickhouse-cli-client(wrapper of ClickHouse native command-line client) was added in 0.3.2-patch10, clickhouse-tcp-client will be available in 0.5
Local/File clickhouse-cli-client will be enhanced to support clickhouse-local
Compatibility Server < 20.7 use 0.3.1-patch(or 0.2.6 if you're stuck with JDK 7)
Server >= 20.7 use 0.3.2 or above. All active releases are supported.
Compression lz4 default
zstd supported since 0.4.0, works with ClickHouse 22.10+
Data Format RowBinary RowBinaryWithNamesAndTypes for query and RowBinary for insertion
TabSeparated Does not support as many data types as RowBinary
Data Type AggregatedFunction limited to groupBitmap, and known to have issue with 64bit bitmap
Array(*)
Bool
Date*
DateTime*
Decimal* SET output_format_decimal_trailing_zeros=1 in 21.9+ for consistency
Enum* can be treated as both string and integer
Geo Types Point, Ring, Polygon, and MultiPolygon
Int*, UInt* UInt64 is mapped to long
IPv*
Map(*)
Nested(*)
Object('JSON') supported since 0.3.2-patch8
SimpleAggregateFunction
*String
Tuple(*)
UUID
High Availability Load Balancing supported since 0.3.2-patch10
Failover supported since 0.3.2-patch10
Transaction Transaction supported since 0.3.2-patch11, use ClickHouse 22.7+ for native implicit transaction support
Savepoint
XAConnection

Usage

The library can be downloaded from both Github Releases and Maven Central. Development snapshots(aka. nightly build) are available on Sonatype OSSRH.

<repositories>
    <repository>
        <id>ossrh</id>
        <name>Sonatype OSSRH</name>
        <url>https://s01.oss.sonatype.org/content/repositories/snapshots/</url>
    </repository>
</repositories>

Java Client

<dependency>
    <groupId>com.clickhouse</groupId>
    <!-- or clickhouse-grpc-client if you prefer gRPC -->
    <artifactId>clickhouse-http-client</artifactId>
    <version>0.4.0</version>
</dependency>
//  endpoint: protocol://host[:port][/database][?param[=value][&param[=value]][#tag[,tag]]
ClickHouseNode endpoint = ClickHouseNode.of("https://localhost"); // http://localhost:8443?ssl=true&sslmode=NONE
// endpoints: [defaultProtocol://]endpoint[,endpoint][/defaultDatabase][?defaultParameters][#defaultTags]
ClickHouseNodes endpoints = ClickHouseNodes.of("http://(https://explorer@play.clickhouse.com:443),localhost,"
    + "(tcp://localhost?!auto_discovery#experimental),(grpc://localhost#experimental)?failover=3#test")

try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP);
    ClickHouseResponse response = client.connect(endpoint) // or client.connect(endpoints)
        // you'll have to parse response manually if using a different format
        .format(ClickHouseFormat.RowBinaryWithNamesAndTypes)
        .query("select * from numbers(:limit)")
        .params(1000).executeAndWait()) {
    // or response.stream() if you prefer stream API
    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();
    }

    ClickHouseResponseSummary summary = response.getSummary();
    long totalRows = summary.getTotalRowsToRead();
}

JDBC Driver

<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.4.0</version>
    <!-- use uber jar with all dependencies included, change classifier to http for smaller jar -->
    <classifier>all</classifier>
    <exclusions>
        <exclusion>
            <groupId>*</groupId>
            <artifactId>*</artifactId>
        </exclusion>
    </exclusions>
</dependency>
// jdbc:(ch|clickhouse):[defaultProtocol://]endpoint[,endpoint][/defaultDatabase][?defaultParameters][#defaultTags]
String url = "jdbc:ch:https://play.clickhouse.com:443";
Properties properties = new Properties();
properties.setProperty("user", "explorer");
properties.setProperty("password", "");
// optional properties
properties.setProperty("client_name", "Agent #1");
...

ClickHouseDataSource dataSource = new ClickHouseDataSource(url, properties);
try (Connection conn = dataSource.getConnection();
    Statement stmt = conn.createStatement();
    ResultSet rs = stmt.executeQuery("show databases")) {
    ...
}

More examples can be found at here.

Build with Maven

Use mvn -Dj8 -DskipITs clean verify to compile and generate packages if you're using JDK 8. To create a multi-release jar (see JEP-238), please use JDK 11+ with ~/.m2/toolchains.xml like below, and run mvn -DskipITs clean verify instead.

<?xml version="1.0" encoding="UTF8"?>
<toolchains>
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>11</version>
        </provides>
        <configuration>
            <jdkHome>/usr/lib/jvm/java-11-openjdk</jdkHome>
        </configuration>
    </toolchain>
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>17</version>
        </provides>
        <configuration>
            <jdkHome>/usr/lib/jvm/java-17-openjdk</jdkHome>
        </configuration>
    </toolchain>
</toolchains>

Testing

By default, docker is required to run integration test. Docker image(defaults to clickhouse/clickhouse-server) will be pulled from Internet, and containers will be created automatically by testcontainers before testing. To test against specific version of ClickHouse, you can pass parameter like -DclickhouseVersion=22.8 to Maven.

In the case you don't want to use docker and/or prefer to test against an existing server, please follow instructions below:

  • make sure the server can be accessed using default account(user default and no password), which has both DDL and DML privileges
  • add below two configuration files to the existing server and expose all defaults ports for external access
    • ports.xml - enable all ports
    • and users.xml - accounts used for integration test Note: you may need to change root element from clickhouse to yandex when testing old version of ClickHouse.
  • make sure ClickHouse binary(usually /usr/bin/clickhouse) is available in PATH, as it's required to test clickhouse-cli-client
  • put test.properties under either ~/.clickhouse or src/test/resources of your project, with content like below:
    clickhouseServer=x.x.x.x
    # below properties are only useful for test containers
    #clickhouseVersion=latest
    #clickhouseTimezone=UTC
    #clickhouseImage=clickhouse/clickhouse-server
    #additionalPackages=

Benchmark

To benchmark JDBC drivers:

cd clickhouse-benchmark
mvn clean package
# single thread mode
java -DdbHost=localhost -jar target/benchmarks.jar -t 1 \
    -p client=clickhouse-jdbc -p connection=reuse \
    -p statement=prepared -p type=default Query.selectInt8

It's time consuming to run all benchmarks against all drivers using different parameters for comparison. If you just need some numbers to understand performance, please refer to this and watch this for more information and updates.