WebSafe 3.7clickhouse.com
|
|
🏠
Skip to main content
Skip to main content
Edit this page

Java clients overview

ClickHouse client​

Java client is a library implementing own API that abstracts details of network communications with ClickHouse server. Currently HTTP Interface is supported only. The library provide utilities to work with different ClickHouse formats and other related functions.

Java Client was developed far back in 2015. Its codebase became very hard to maintain, API is confusing, it is hard to optimize it further. So we have refactored it in 2024 into a new component client-v2. It has clear API, lighter codebase and more performance improvements, better ClickHouse formats support (RowBinary & Native mainly). JDBC will use this client in near feature.

Supported data types​

Data TypeClient V2 SupportClient V1 Support
Int8βœ”βœ”
Int16βœ”βœ”
Int32βœ”βœ”
Int64βœ”βœ”
Int128βœ”βœ”
Int256βœ”βœ”
UInt8βœ”βœ”
UInt16βœ”βœ”
UInt32βœ”βœ”
UInt64βœ”βœ”
UInt128βœ”βœ”
UInt256βœ”βœ”
Float32βœ”βœ”
Float64βœ”βœ”
Decimalβœ”βœ”
Decimal32βœ”βœ”
Decimal64βœ”βœ”
Decimal128βœ”βœ”
Decimal256βœ”βœ”
Boolβœ”βœ”
Stringβœ”βœ”
FixedStringβœ”βœ”
Nullableβœ”βœ”
Dateβœ”βœ”
Date32βœ”βœ”
DateTimeβœ”βœ”
DateTime32βœ”βœ”
DateTime64βœ”βœ”
Intervalβœ—βœ—
Enumβœ”βœ”
Enum8βœ”βœ”
Enum16βœ”βœ”
Arrayβœ”βœ”
Mapβœ”βœ”
Nestedβœ”βœ”
Tupleβœ”βœ”
UUIDβœ”βœ”
IPv4βœ”βœ”
IPv6βœ”βœ”
Objectβœ—βœ”
Pointβœ”βœ”
Nothingβœ”βœ”
MultiPolygonβœ”βœ”
Ringβœ”βœ”
Polygonβœ”βœ”
SimpleAggregateFunctionβœ”βœ”
AggregateFunctionβœ—βœ”
Variantβœ”βœ—
Dynamicβœ”βœ—
JSONβœ”βœ—

ClickHouse Data Types

Note
  • AggregatedFunction - ⚠️ doesn't support SELECT * FROM table ...
  • Decimal - SET output_format_decimal_trailing_zeros=1 in 21.9+ for consistency
  • Enum - can be treated as both string and integer
  • UInt64 - mapped to long in client-v1

Features​

Table of features of the clients:

NameClient V2Client V1Comments
Http Connectionβœ”βœ”
Http Compression (LZ4)βœ”βœ”
Application Controlled Compressionβœ”βœ—
Server Response Compression - LZ4βœ”βœ”
Client Request Compression - LZ4βœ”βœ”
HTTPSβœ”βœ”
Client SSL Cert (mTLS)βœ”βœ”
Http Proxyβœ”βœ”
POJO SerDeβœ”βœ—
Connection Poolβœ”βœ”When Apache HTTP Client used
Named Parametersβœ”βœ”
Retry on failureβœ”βœ”
Failoverβœ—βœ”
Load-balancingβœ—βœ”
Server auto-discoveryβœ—βœ”
Log Commentβœ”βœ”
Session Rolesβœ”βœ”
SSL Client Authenticationβœ”βœ”
SNI Configurationβœ”βœ—
Session timezoneβœ”βœ”

JDBC Drive inherits same features as underlying client implementation. Other JDBC features are listed on its page.

Compatibility​

  • All projects in this repo are tested with all active LTS versions of ClickHouse.
  • Support policy
  • We recommend to upgrade client continuously to not miss security fixes and new improvements
  • If you have an issue with migration to v2 API - create an issue and we will respond!

Logging​

Our Java language client uses SLF4J for logging. You can use any SLF4J-compatible logging framework, such as Logback or Log4j. For example, if you're using Maven you could add the following dependency to your pom.xml file:

<dependencies>
    <!-- SLF4J API -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>2.0.16</version> <!-- Use the latest version -->
    </dependency>

    <!-- Logback Core -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-core</artifactId>
        <version>1.5.16</version> <!-- Use the latest version -->
    </dependency>

    <!-- Logback Classic (bridges SLF4J to Logback) -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.5.16</version> <!-- Use the latest version -->
    </dependency>
</dependencies>

Configuring logging​

This is going to depend on the logging framework you're using. For example, if you're using Logback, you could configure logging in a file called logback.xml:

<configuration>
    <!-- Console Appender -->
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>[%d{yyyy-MM-dd HH:mm:ss}] [%level] [%thread] %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- File Appender -->
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>logs/app.log</file>
        <append>true</append>
        <encoder>
            <pattern>[%d{yyyy-MM-dd HH:mm:ss}] [%level] [%thread] %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Root Logger -->
    <root level="info">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>

    <!-- Custom Log Levels for Specific Packages -->
    <logger name="com.clickhouse" level="info" />
</configuration>

Changelog