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 | ||
| 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 | |||
| 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 | |||
| Data Type | AggregateFunction | groupBitmap; 64bit bitmap was NOT working properly before 0.4.1 |
|
| 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 | use_binary_string=true for binary string support since v0.4.0 |
||
| 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 | |||
| Misc. | Implicit Type Conversion | String/number to Date/Time/Timestamp and more | |
| Centralized Configuration | 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.
<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.
