skyoct / clickhouse-java

Java client and JDBC driver for ClickHouse

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	✅	⚠️ 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.