Skip to content

Latest commit

 

History

History
76 lines (62 loc) · 16.2 KB

README.md

File metadata and controls

76 lines (62 loc) · 16.2 KB
Raw

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 ✅ ⚠️ experimental, works with 22.3+, known to has issue with lz4 compression and may cause high memory usage on server
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 AggregateFunction ✅ ⚠️ does not support 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(*) ✅ ⚠️ broken before 0.4.1
Object('JSON') ✅ supported since 0.3.2-patch8
SimpleAggregateFunction ✅
*String ✅ ⚠️ requires 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.