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 | โ | SELECT * FROM table ... |
| 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. | Centralized Configuration | โ | supported since 0.4.2, limited to JDBC driver and requires custom server setting custom_jdbc_config for all connected JDBC clients - #1290 |
| INFILE & OUTFILE | โ | supported since 0.4.2, limited to JDBC driver and requires localFile option - #1291 |
|
| Implicit Type Conversion | โ | String/number to Date/Time/Timestamp and more | |
| Object mapping | โ | supported since 0.4.6, slow and limited to simple data types |
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 examples and the docs on the ClickHouse website.
JDBC Driver
See examples and the docs on the ClickHouse website.
Contributing
Check out our contributing guide.