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 | ||
Query Language | SQL | ||
PRQL | will be available in 0.4.2 | ||
GraphQL | will be available in 0.4.2 | ||
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 |
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.