メインコンテンツまでスキップ
メインコンテンツまでスキップ

クライアント (0.7.x およびそれ以前)

DBサーバとそのプロトコルを通じて通信するためのJavaクライアントライブラリです。現在の実装は、HTTPインターフェース のみをサポートしています。このライブラリは、サーバにリクエストを送信するための独自のAPIを提供します。

非推奨

このライブラリは近々非推奨になります。新しいプロジェクトには最新のJava Clientを使用してください。

セットアップ​

バージョン 0.5.0 以降、ドライバは新しいクライアントHTTPライブラリを使用しており、依存関係として追加する必要があります。

初期化​

接続URL形式: protocol://host[:port][/database][?param[=value][&param[=value]][#tag[,tag]]。例:

単一ノードに接続:

複数ノードを持つクラスターに接続:

クエリAPI​

ストリーミングクエリAPI​

完全なコード例をリポジトリで確認してください。

挿入API​

完全なコード例をリポジトリで確認してください。

RowBinaryエンコーディング

RowBinary形式については、ページを参照してください。

コードの例があります。

機能​

圧縮​

クライアントはデフォルトでLZ4圧縮を使用します。これには次の依存関係が必要です：

接続URLに compress_algorithm=gzip を設定することでgzipを使用することもできます。

もしくは、いくつかの方法で圧縮を無効にすることができます。

  1. 接続URLで compress=0 を設定して無効にする: http://localhost:8123/default?compress=0
  2. クライアント構成を介して無効にする：

さまざまな圧縮オプションについては、圧縮ドキュメントを確認してください。

複数のクエリ​

同じセッション内でワーカースレッドで複数のクエリを1つずつ実行します：

名前付きパラメータ​

パラメータリスト内の位置に依存せず、名前でパラメータを渡すことができます。この機能は params 関数を使用して利用できます。

パラメータ

String型を含むすべての params シグネチャ（String、String[]、Map<String, String>）は、渡されるキーが有効なClickHouse SQL文字列であることを前提としています。例えば：

ClickHouse SQLに手動でStringオブジェクトを解析したくない場合は、com.clickhouse.data にあるヘルパー関数 ClickHouseValues.convertToSqlExpression を使用できます：

上記の例では、ClickHouseValues.convertToSqlExpression が内部のシングルクオートをエスケープし、変数を有効なシングルクオートで囲みます。

Integer、UUID、Array、および Enum などの他の型は、 params 内で自動的に変換されます。

ノード発見​

Javaクライアントは、ClickHouseノードを自動的に発見する機能を提供します。自動発見はデフォルトで無効になっています。手動で有効にするには、auto_discovery を true に設定します：

または接続URL内で：

自動発見が有効になっている場合、接続URL内ですべてのClickHouseノードを指定する必要はありません。URL内で指定されたノードはシードとして扱われ、Javaクライアントはシステムテーブルやclickhouse-keeperまたはzookeeperから自動的に他のノードを発見します。

自動発見設定に関連するオプションは次のとおりです：

プロパティデフォルト説明
auto_discoveryfalseクライアントがシステムテーブルやclickhouse-keeper/zookeeperからさらにノードを発見するべきかどうか。
node_discovery_interval0ノード発見間隔（ミリ秒）。ゼロまたは負の値は一度だけ発見することを意味します。
node_discovery_limit100一度に発見できるノードの最大数。ゼロまたは負の値は制限なしを意味します。

負荷分散​

Javaクライアントは、負荷分散ポリシーに従ってリクエストを送信するClickHouseノードを選択します。一般に、負荷分散ポリシーは以下のことを担当します：

  1. 管理されたノードリストからノードを取得する。
  2. ノードの状態を管理する。
  3. （自動発見が有効な場合）ノード発見のためのバックグラウンドプロセスをスケジュールし、ヘルスチェックを実行する。

負荷分散を構成するためのオプションは以下のとおりです：

プロパティデフォルト説明
load_balancing_policy""負荷分散ポリシーは次のいずれかです：
  • firstAlive - 管理されたノードリストから最初の健康なノードにリクエストを送信
  • random - 管理されたノードリストからランダムなノードにリクエストを送信
  • roundRobin - 管理されたノードリストの各ノードに順番にリクエストを送信。
  • ClickHouseLoadBalancingPolicyを実装する完全修飾クラス名 - カスタム負荷分散ポリシー
    • 指定されていない場合、リクエストは管理されたノードリストの最初のノードに送信されます。
    load_balancing_tags""ノードをフィルタリングするための負荷分散タグ。指定されたタグを持つノードのみにリクエストが送信されます。
    health_check_interval0ヘルスチェック間隔（ミリ秒）。ゼロまたは負の値は一度だけを意味します。
    health_check_methodClickHouseHealthCheckMethod.SELECT_ONEヘルスチェックメソッド。次のいずれかです：
  • ClickHouseHealthCheckMethod.SELECT_ONE - select 1 クエリでチェック
  • ClickHouseHealthCheckMethod.PING - プロトコル固有のチェック、通常はより高速です。
    • node_check_interval0ノードチェック間隔（ミリ秒）。負の数はゼロとして扱われます。指定された時間が最終チェックから経過すると、ノード状態がチェックされます。
    health_check_intervalとnode_check_intervalの違いは、health_check_intervalオプションがバックグラウンドジョブをスケジュールし、ノードリスト（全てまたは故障したもの）のステータスをチェックするのに対し、node_check_intervalは特定のノードについて最後のチェックから経過した時間を指定します。
    check_all_nodesfalseすべてのノードに対してヘルスチェックを実行するか、故障したノードのみかどうか。

    フェイルオーバーとリトライ​

    Javaクライアントは、失敗したクエリのためにフェイルオーバーとリトライの動作を設定するためのオプションを提供します：

    プロパティデフォルト説明
    failover0リクエストのためのフェイルオーバーが発生する最大回数。ゼロまたは負の値はフェイルオーバーなしを意味します。フェイルオーバーは、異なるノードに失敗したリクエストを送信し、フェイルオーバーから回復します。
    retry0リクエストのためのリトライが発生する最大回数。ゼロまたは負の値はリトライなしを意味します。リトライは、同じノードにリクエストを送信し、ClickHouseサーバが NETWORK_ERROR エラーコードを返した場合のみ発生します。
    repeat_on_session_locktrueセッションがタイムアウトするまで、ロック時に実行を繰り返すかどうか（session_timeout または connect_timeout に従う）。ClickHouseサーバが SESSION_IS_LOCKED エラーコードを返した場合、失敗したリクエストは繰り返されます。

    カスタムHTTPヘッダーの追加​

    Javaクライアントは、リクエストにカスタムHTTPヘッダーを追加する場合に、HTTP/Sトランスポート層をサポートします。 custom_http_headers プロパティを使用する必要があり、ヘッダーは , で区切る必要があります。ヘッダーのキー/値は = で区切るべきです。

    Javaクライアントサポート​

    JDBCドライバ​