ClickHouse Java Libraries

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.

Features

| Category | Feature | Supported | Remark | | ----------------- | ----------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | API | JDBC | :whitecheckmark: | | | | R2DBC | :whitecheckmark: | supported since 0.4.0 | | Protocol | HTTP | :whitecheckmark: | 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 | :whitecheckmark: | :warning: experimental, works with 22.3+, known to has issue with lz4 compression and may cause high memory usage on server | | | TCP/Native | :whitecheckmark: | 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 | :x: | clickhouse-cli-client will be enhanced to support clickhouse-local | | Compatibility | Server < 20.7 | :x: | use 0.3.1-patch(or 0.2.6 if you're stuck with JDK 7) | | | Server >= 20.7 | :whitecheckmark: | use 0.3.2 or above. All active releases are supported. | | Compression | lz4 | :whitecheckmark: | default | | | zstd | :whitecheckmark: | supported since 0.4.0, works with ClickHouse 22.10+ | | Data Format | RowBinary | :whitecheckmark: | RowBinaryWithNamesAndTypes for query and RowBinary for insertion | | | TabSeparated | :whitecheckmark: | :warning: does not support as many data types as RowBinary | | Data Type | AggregateFunction | :x: | :warning: limited to groupBitmap; 64bit bitmap was NOT working properly before 0.4.1 | | | Array(*) | :whitecheckmark: | | | | Bool | :whitecheckmark: | | | | Date* | :whitecheckmark: | | | | DateTime* | :whitecheckmark: | | | | Decimal* | :whitecheckmark: | SET output_format_decimal_trailing_zeros=1 in 21.9+ for consistency | | | Enum* | :whitecheckmark: | can be treated as both string and integer | | | Geo Types | :whitecheckmark: | Point, Ring, Polygon, and MultiPolygon | | | Int*, UInt* | :whitecheckmark: | UInt64 is mapped to long | | | IPv* | :whitecheckmark: | | | | Map(*) | :whitecheckmark: | | | | Nested(*) | :whitecheckmark: | :warning: broken before 0.4.1 | | | Object('JSON') | :whitecheckmark: | supported since 0.3.2-patch8 | | | SimpleAggregateFunction | :whitecheckmark: | | | | *String | :whitecheckmark: | :warning: requires use_binary_string=true for binary string support since v0.4.0 | | | Tuple(*) | :whitecheckmark: | | | | UUID | :whitecheckmark: | | | High Availability | Load Balancing | :whitecheckmark: | supported since 0.3.2-patch10 | | | Failover | :whitecheckmark: | supported since 0.3.2-patch10 | | Transaction | Transaction | :whitecheckmark: | supported since 0.3.2-patch11, use ClickHouse 22.7+ for native implicit transaction support | | | Savepoint | :x: | | | | XAConnection | :x: | | | Misc. | Implicit Type Conversion | :whitecheckmark: | String/number to Date/Time/Timestamp and more | | | Centralized Configuration | :whitecheckmark: | supported since 0.4.2, custom server setting custom_jdbc_config for all connected JDBC clients |

Usage

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

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

Java Client

See the client docs on the ClickHouse website.

JDBC Driver

See the jdbc driver docs on the ClickHouse website.

Contributing

Check out our contributing guide.