Java クライアントの概要

JavaからClickHouseに接続するための選択肢

• Client 0.8+
• JDBC 0.8+
• R2DBC Driver

​

ClickHouse client

Java クライアントは、ClickHouse server とのネットワーク通信の詳細を抽象化する独自の API を実装したライブラリです。現時点でサポートされているのは HTTP インターフェイスのみです。このライブラリには、さまざまな ClickHouse フォーマットの操作や、そのほかの関連機能のためのユーティリティが用意されています。

Java クライアントは 2015 年とかなり早い時期に開発されましたが、コードベースの保守は非常に難しくなり、API もわかりにくく、これ以上の最適化も困難になっていました。そのため、2024 年にこれを新しいコンポーネント client-v2 としてリファクタリングしました。これにより、API はより明確になり、コードベースはより軽量になり、パフォーマンスも改善され、ClickHouse フォーマット (特に RowBinary と Native) のサポートも強化されました。JDBC も近いうちにこのクライアントを使用する予定です。

​

サポートされているデータ型

データ型	Client V2対応	Client V1対応
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 のデータ型

一部サポート

• AggregateFunction — バイナリの直接読み取りでサポートされるのは groupBitmap のみです。その他の集約関数 (min、max、avg など) では、状態をサーバー側で解決するため、クエリで -Merge combinators (例: minMerge(), avgMerge()) を使用してください。AggregateFunction 型のカラムに対する SELECT * FROM table ... はサポートされていません。

データ型に関する注記

• Decimal — 一貫性を保つため、21.9 以降では SET output_format_decimal_trailing_zeros=1 を使用します。
• Enum — 文字列としても整数としても扱えます。
• UInt64 — client-v1 では long にマッピングされます。

​

機能

クライアントの機能一覧:

Name	Client V2	Client V1	Comments
HTTP 接続	✔	✔
HTTP 圧縮 (LZ4)	✔	✔
アプリケーション制御の圧縮	✔	✗
サーバー応答の圧縮 - LZ4	✔	✔
クライアントリクエストの圧縮 - LZ4	✔	✔
HTTPS	✔	✔
クライアント SSL 証明書 (mTLS)	✔	✔
HTTP プロキシ	✔	✔
POJO SerDe	✔	✗
接続プール	✔	✔	Apache HTTP Client を使用する場合
名前付きパラメーター	✔	✔
障害時の再試行	✔	✔
フェイルオーバー	✗	✔
負荷分散	✗	✔
サーバーの自動検出	✗	✔
ログコメント	✔	✔
セッションロール	✔	✔
SSL クライアント認証	✔	✔
SNI 設定	✔	✗
セッションタイムゾーン	✔	✔

JDBC ドライバは、基盤となるクライアント実装と同じ機能を継承します。その他の JDBC 機能は、ページに記載されています。

​

互換性

• このリポジトリ内のすべてのプロジェクトは、ClickHouse の現在サポート中のすべての LTS バージョンでテストされています。
• サポートポリシー
• セキュリティ修正や新しい改善を見逃さないよう、クライアントは継続的にアップグレードすることを推奨します
• v2 API への移行で問題がある場合は、issue を作成してください。対応します！

​

ログ

Java 言語クライアントでは、ログに SLF4J を使用しています。Logback や Log4j など、SLF4J 互換の任意のログフレームワークを使用できます。 たとえば、Maven を使用している場合は、pom.xml ファイルに次の依存関係を追加できます。

pom.xml

<dependencies>
    <!-- SLF4J API -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>2.0.16</version> <!-- 最新バージョンを使用してください -->
    </dependency>

    <!-- Logback Core -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-core</artifactId>
        <version>1.5.16</version> <!-- 最新バージョンを使用してください -->
    </dependency>

    <!-- Logback Classic（SLF4J を Logback にブリッジします） -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.5.16</version> <!-- 最新バージョンを使用してください -->
    </dependency>
</dependencies>

​

ログの設定

これは、使用しているロギングフレームワークによって異なります。たとえば、Logback を使用している場合は、logback.xml という名前のファイルでログを設定できます。

logback.xml

<configuration>
    <!-- コンソールアペンダー -->
    <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>

    <!-- ファイルアペンダー -->
    <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 level="info">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>

    <!-- 特定パッケージのカスタムログレベル -->
    <logger name="com.clickhouse" level="info" />
</configuration>

変更履歴