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	❌	⚠️ limited to `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(*)	✅	⚠️ 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.	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