DBサーバーとそのプロトコルを通じて通信するための Java クライアントライブラリです。現在の実装は HTTP インターフェイス のみをサポートしています。
このライブラリはサーバーへリクエストを送信するための独自の API を提供します。また、さまざまなバイナリデータフォーマット (RowBinary* & Native*) を扱うためのツールも提供しています。
アクセストークンまたは Bearerトークン (JWT など) による認証を行うには、SSLクライアント証明書による認証を行うには、
結果として、アプリケーションは、自身を識別するために独自の HTTP ヘッダー ⚠️ 重要: 操作ごとに設定するには、クライアントビルダーではなく、以降、この パラメーターパラメーターパラメーターパラメーターパラメーターパラメーターパラメーターパラメーター連携方法アプリケーションにオブザーバビリティを組み込むには、主に次の2つのパターンがあります。V2でTSVフォーマットのデータを挿入する。
セットアップ
- Maven Central (プロジェクトのWebページ) : https://mvnrepository.com/artifact/com.clickhouse/client-v2
- ナイトリービルド (リポジトリへのリンク): https://central.sonatype.com/repository/maven-snapshots/
- Maven
- Gradle (Kotlin)
- Gradle
初期化
Client オブジェクトはcom.clickhouse.client.api.Client.Builder#build() によって初期化されます。各クライアントは独自のコンテキストを持ち、クライアント間でオブジェクトが共有されることはありません。
Builder には、便利な設定メソッドが用意されています。例:showLineNumbers
Client は AutoCloseable であり、不要になったらクローズしてください。認証
認証は初期化フェーズでクライアントごとに設定されます。サポートされる認証方式は 3 種類あります:パスワード、アクセストークン、SSL クライアント証明書。パスワードによる認証を行うには、setUsername(String) および setPassword(String) を呼び出してユーザー名とパスワードを設定する必要があります。showLineNumbers
useBearerTokenAuth(String) (未加工のアクセストークンの場合は setAccessToken(String)) を呼び出してトークンを設定する必要があります。showLineNumbers
setUsername(String)、useSSLAuthentication(boolean)、setClientCertificate(String)、および setClientKey(String) をそれぞれ呼び出して、ユーザー名の設定、SSL認証の有効化、クライアント証明書とクライアント秘密鍵の設定を行う必要があります。showLineNumbers
SSL 認証は、本番環境ではトラブルシューティングが難しいことがあります。これは、SSL ライブラリが返すエラーの多くに十分な情報が含まれていないためです。たとえば、クライアント証明書と秘密鍵が一致していない場合、サーバーは接続を即座に切断します (HTTP の場合は、HTTP リクエストがまったく送信されない接続開始段階で切断されるため、レスポンスも返されません) 。証明書と秘密鍵の検証には、openssl などのツールを使用してください。
- 秘密鍵の整合性を確認する:
openssl rsa -in [key-file.key] -check -noout - クライアント証明書に、ユーザーに対応する CN が含まれていることを確認する:
- ユーザー証明書から CN を取得する -
openssl x509 -noout -subject -in [user.cert] - 同じ値がデータベースに設定されていることを確認する:
select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'(このクエリを実行すると、auth_paramsに{"common_names":["some_user"]}のような内容が出力されます)
- ユーザー証明書から CN を取得する -
接続プーリング
Client は、内部に HTTP接続プールを持つ Apache HttpClient 5 を使用します。各操作ではプールから接続を取得してリクエストを送信し、レスポンスをストリーミングで受信した後、接続をプールに返却します。Client.Builder の主な接続プール設定:接続プールの推奨設定
showLineNumbers
設定
すべての設定は、各値のスコープとコンテキストが明確になるように、インスタンスメソッド (別名: 設定メソッド) で定義されています。 主要な設定パラメーターは、単一のスコープ (クライアントまたは操作) で定義され、互いに上書きしません。設定はクライアントの作成時に定義されます。com.clickhouse.client.api.Client.Builder を参照してください。クライアント設定
- 接続 & エンドポイント
- 認証
- タイムアウトと再試行
- ソケットオプション
- 圧縮
- SSL/セキュリティ
- プロキシ
- HTTP とヘッダー
- サーバー設定
- タイムゾーン
- 詳細設定
クライアントの識別
クエリログには、リクエストの送信元アプリケーションを識別する2つのフィールドがあります:client_name と http_user_agent です。ネイティブTCPプロトコルはアプリケーションの識別に client_name を使用し、HTTPプロトコルは http_user_agent を使用します。クライアントビルダーには、両プロトコルに対して正しい値を設定するメソッド setClientName があります。
フィールド http_user_agent は、User-Agent ヘッダーの一般的なフォーマットに従って設定されます: application-name[/version] [(operating-system; architecture; ...)]。
この値のセットは、アプリケーション、クライアントライブラリ、HTTPクライアントライブラリという各レイヤーに対して繰り返されます。setClientName メソッドで設定された値がリストの先頭に配置されます。例:showLineNumbers
http_user_agent の値は次のようになります。User-Agent を設定できます。ただし、clickhouse-java-v2/0.9.6-SNAPSHOT の部分がヘッダーの末尾に追加されます。オペレーションの識別
クエリログには、操作の識別やクエリログへの追加情報の付加に使用できるquery_id と log_comment という2つのフィールドがあります。query_id は操作の一意の識別子です。アプリケーションは QuerySettings クラスの setQueryId メソッドを呼び出して設定できます。showLineNumbers
log_comment は、クエリログに追加できるコメントです。アプリケーションから QuerySettings クラスの logComment メソッドを呼び出して設定できます。showLineNumbers
サーバー設定
サーバー側の設定は、クライアントレベルでは作成時に一度設定できます (Builder の serverSetting メソッドを参照) 。また、オペレーションレベルでも設定できます (オペレーション設定クラスの serverSetting を参照) 。showLineNumbers
setOption メソッド (Client.Builder または操作設定クラス) でオプションを設定する場合、サーバー設定名には clickhouse_setting_ というプレフィックスを付ける必要があります。この場合、com.clickhouse.client.api.ClientConfigProperties#serverSetting() を使用すると便利です。カスタム HTTP ヘッダー
カスタムHTTPヘッダーは、すべての操作 (クライアントレベル) または個別の操作 (オペレーションレベル) に設定できます。操作ごとの設定は、同名の client-level ヘッダーをオーバーライドします。showLineNumbers
setOption (Client.Builder または操作設定クラス) でオプションを設定する場合、ヘッダー名には http_header_ をプレフィックスとして付けてください。ClientConfigProperties.httpHeader(String) を使用すると、このキーを生成できます。
ヘッダー名は単純な String キーであるため、大文字・小文字を統一する必要があります。統一されていない場合、値が重複し、動作は未定義になります。ClientConfigProperties.httpHeader(String) を使用すると、この問題を回避できます。showLineNumbers
ClickHouse Cloud の機能
ClickHouse Cloud に接続する際に適用される機能です。レプリカ対応ルーティング (CLOUD)
ClickHouse Cloud では、関連するHTTPリクエストの送信先を同じレプリカに固定できます。X-ClickHouse-Replica-Tag ヘッダーを送信すると、Cloud プロキシは同じタグを持つすべてのリクエストを同じレプリカに転送します。一時テーブルなどの session スコープのオブジェクトを使用する場合や、レプリカ内のキャッシュの再利用、書き込み後の読み取り整合性が必要な場合に、この機能を使用してください。
詳細: https://clickhouse.com/docs/products/cloud/features/infrastructure/replica-aware-routing.設定する項目: HTTP ヘッダー X-ClickHouse-Replica-Tag (com.clickhouse.client.api.http.ClickHouseHttpProto.HEADER_REPLICA_TAG)。同じレプリカで処理する必要があるすべてのリクエストには、同じタグの値を使用してください。showLineNumbers
QuerySettings、InsertSettings、または CommandSettings にヘッダーを設定してください。JWT認証 (CLOUD)
JWT認証を使用すると、ClickHouse Cloud で JSON Web Token (JWT) によるユーザー認証を行えます。ClickHouse は、既存のデータベースユーザーを使用する代わりに、各トークンに含まれるクレームに基づいて一時ユーザーを動的に作成します。初期設定
クライアントで初期の JWT認証を設定するには、Client インスタンスの構築時に useBearerTokenAuth(token) を使用します (Bearer_ プレフィックスは自動的に付加されます。
HTTP インターフェースのドキュメントを参照してください) 。showLineNumbers
useBearerTokenAuth(token) は、Authorization HTTP ヘッダーに Bearer プレフィックスを自動的に付加します。実行時のトークンの更新
JWT は有効期間が短く、一時ユーザーはトークンの存続期間中しか存在しないため、操作が失敗しないよう、現在のトークンの有効期限が切れる前に新しい JWT トークンを設定してください。クライアントを再作成せずに、既存のClient インスタンスのBearerトークンを実行時に更新できます:showLineNumbers
Client インスタンスでのすべてのリクエストには、更新された JWT トークンが使用されます。共通の定義
ClickHouseFormat
対応フォーマットのenumです。ClickHouseがサポートするすべてのフォーマットを含みます。raw- ユーザーは生データをトランスコードする必要がありますfull- クライアント自身でデータをトランスコードでき、raw データストリームを受け入れます-- このフォーマットでは、ClickHouse はこの操作をサポートしていません
Insert API
insert(String tableName, InputStream data, ClickHouseFormat format)
指定されたフォーマットのバイト列をInputStream として受け取ります。data は format でエンコードされていることが前提です。シグネチャtableName - ターゲットテーブルの名前。data - エンコードされたデータの入力ストリーム。format - データのエンコードに使用するフォーマット。settings - リクエストの設定。戻り値InsertResponse 型の Future — 操作の結果およびサーバー側のメトリクスなどの追加情報。例showLineNumbers
insert(String tableName, List<?> data, InsertSettings settings)
データベースへ書き込みリクエストを送信します。オブジェクトのリストは効率的なフォーマットに変換され、サーバーに送信されます。リスト要素のクラスは、register(Class, TableSchema) メソッドを使用して事前に登録しておく必要があります。シグネチャtableName - ターゲットテーブルの名前。data - コレクションDTO (Data Transfer Object) オブジェクト。settings - リクエストの設定。戻り値InsertResponse 型のFuture — 操作の結果およびサーバーサイドのメトリクスなどの追加情報。例showLineNumbers
InsertSettings
挿入操作の設定オプション。設定方法InsertResponse
insertオペレーションの結果を保持するレスポンスオブジェクトです。クライアントがサーバーからレスポンスを受け取った場合にのみ使用できます。このオブジェクトは、以前のレスポンスのデータをすべて完全に読み取るまで接続を再利用できないため、接続を解放するにはできるだけ早く閉じてください。
クエリ API
フォーマットの選択Client は、サーバーからのレスポンスストリームへの透過的なアクセスを提供します。ユーザーはリクエストで任意の ClickHouse フォーマットを選択し、QueryResponse オブジェクトの InputStream を通じてデータを読み取ることができます。
フォーマットは次の方法で指定できます:QuerySettings#setFormat()を使用すると、リクエストにフォーマットヘッダーが設定されます。- クエリ自体の
FORMAT句で指定します。 - サーバー設定
default_format(/reference/settings/session-settings/default#default_format)
- Client <
0.11.0& ClickHouse <26.8-FORMAT句がリクエストのフォーマットヘッダーよりも優先されます。 - Client >
0.11.0& ClickHouse >26.8- リクエストヘッダーがFORMAT句よりも優先されます。QuerySettingsでフォーマットが指定されていなくても、クライアントがヘッダーを設定するため、クエリ内でフォーマットをオーバーライドできません。
- クライアントの
0.11.0以降では、formatのデフォルト値は操作レベルではなくクライアントレベルで設定されます。これにより、既存のコードは 変更せずに動作し、新しいコードではクライアントのformatをnullに設定することでFORMAT句を使用できます。
query(String sqlQuery)
sqlQuery をそのまま送信します。レスポンスのフォーマットはクエリの設定によって決まります。QueryResponse はレスポンスストリームへの参照を保持し、対応するフォーマットのリーダーによって読み取られる必要があります。シグネチャsqlQuery - 単一のSQLステートメント。クエリはそのままサーバーに送信されます。settings - リクエストの設定。戻り値QueryResponse 型のFuture — 結果データセットおよびサーバーサイドのメトリクスなどの追加情報を含みます。Responseオブジェクトは、データセットを使用した後にクローズする必要があります。例query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)
sqlQuery をそのまま送信します。また、サーバーがSQL式をコンパイルできるように、クエリパラメータも送信します。シグネチャsqlQuery - プレースホルダー {} を含む SQL 式。queryParams - サーバー上で SQL 式を完成させるための変数を格納するマップ。settings - リクエストの設定。戻り値QueryResponse 型のFuture — 結果データセットおよびサーバーサイドのメトリクスなどの追加情報を含みます。Responseオブジェクトは、データセットを使用した後にクローズする必要があります。例showLineNumbers
queryAll(String sqlQuery)
RowBinaryWithNamesAndTypes フォーマットでデータをクエリします。結果をコレクションとして返します。読み取りパフォーマンスはリーダーと同等ですが、データセット全体を保持するためにより多くのメモリが必要になります。シグネチャsqlQuery - サーバーからデータをクエリするためのSQL式。戻り値結果データに行形式でアクセスできる GenericRecord オブジェクトのリストで表される、完全なデータセット。例showLineNumbers
QuerySettings
クエリ操作の設定オプション。設定方法QueryResponse
クエリ実行の結果を保持するレスポンスオブジェクトです。クライアントがサーバーからレスポンスを受け取った場合にのみ使用できます。このオブジェクトは、以前のレスポンスのデータをすべて完全に読み取るまで接続を再利用できないため、接続を解放するにはできるだけ早く閉じてください。
例
共通API
getTableSchema(String table)
table のテーブルスキーマを取得します。シグネチャtable - スキーマデータを取得する対象のテーブル名。database - ターゲットテーブルが定義されているデータベース。戻り値テーブルのカラム一覧を含む TableSchema オブジェクトを返します。getTableSchemaFromQuery(String sql)
SQLステートメントからスキーマを取得します。シグネチャsql - スキーマが返される “SELECT” SQL ステートメント。戻り値sql 式に対応するカラムを含む TableSchema オブジェクトを返します。TableSchema
register(Class<?> clazz, TableSchema schema)
schema を使用してデータの書き込み・読み込みを行う Java クラス向けに、シリアライゼーションおよびデシリアライゼーションのレイヤーをコンパイルします。このメソッドは、getter/setter のペアと対応するカラムに対して、シリアライザーとデシリアライザーを生成します。
カラムの照合は、メソッド名からカラム名を抽出することで行われます。たとえば、getFirstName はカラム first_name または firstname に対応します。シグネチャclazz - データの読み書きに使用するPOJOを表すクラス。schema - POJOプロパティとの照合に使用するデータスキーマ。例showLineNumbers
使用例
完全なサンプルコードは、リポジトリの ‘example` フォルダ に保存されています:- client-v2 - 主なサンプル一式。
- demo-service - Spring Boot アプリケーションでクライアントを使用する方法を示す例。
- demo-kotlin-service - Ktor (Kotlin) アプリケーションでクライアントを使用する方法を示す例。
データの読み取り
データを読み取る一般的な方法は2つあります。- データを含む
InputStreamを持つ低レベルのQueryResponseオブジェクトを返すquery()メソッド。通常はストリーミング読み取りのためにClickHouseBinaryFormatReaderと組み合わせて使用されますが、 ほかのカスタムリーダー実装でも使用できます。QueryResponseでは、結果セットのメタデータとメトリクスにもアクセスできます。 queryAll()メソッドを使用し、各行に簡単にアクセスできるようにGenericRecordを利用します。この場合、結果セット全体がメモリに読み込まれます。queryRecords()メソッドはcom.clickhouse.client.api.query.Recordsを返します。これはGenericRecordオブジェクトのイテレータです。このメソッドはストリーミング方式を採用しており (データはメモリに読み込まれません) 、GenericRecordを使用してデータにアクセスします。
配列の読み取り
ClickHouseBinaryFormatReader のメソッドgetList(...)- 任意のArray(...)をList<T>として読み取ります。柔軟な型付き読み取りの標準的な選択肢です。ネストした配列にも対応しています。getByteArray(...),getShortArray(...),getIntArray(...),getLongArray(...),getFloatArray(...),getDoubleArray(...),getBooleanArray(...)- プリミティブ互換の値で構成される1次元配列に最適です。getStringArray(...)-Array(String)用 (および名前で表される enum の値) 。getObjectArray(...)- ネストされた配列を含む、あらゆるArray(...)の要素型に対応する汎用オプションです。Nullable な値を含む配列や、ネストされた配列を読み取る際に使用します。
GenericRecord メソッドgetList(...)- 任意のArray(...)をList<T>として読み取ります。柔軟な型付き読み取りの標準的な選択肢です。ネストした配列にも対応しています。getByteArray(...),getShortArray(...),getIntArray(...),getLongArray(...),getFloatArray(...),getDoubleArray(...),getBooleanArray(...)- プリミティブ互換の値で構成される1次元配列に最適です。getStringArray(...)-Array(String)用 (および名前で表される enum の値) 。getObjectArray(...)- ネストされた配列を含む、あらゆるArray(...)の要素型に対応する汎用オプションです。Nullable な値を含む配列や、ネストされた配列を読み取る際に使用します。
オブザーバビリティと監視
ClickHouse Java クライアント (V2) は、OpenTelemetry のセマンティック規約と Micrometer メトリクスに基づいて設計された、組み込みのオブザーバビリティ機能を提供します。このクライアントでは、操作の所要時間、スループット、再試行、サーバーの実行統計、接続プールのステータス、および分散トレーシングのスパンを監視できます。クライアント V2 の設定、コネクションプーリング、@Async の境界をまたぐトレースコンテキストの伝播、テレメトリーとの完全なインテグレーションを実装した、本番環境を想定した Spring Boot アプリケーションの完全な例については、このリポジトリの examples/demo-spring-service モジュールを参照してください。Client Builder のオブザーバビリティ API
Client.Builder には、オブザーバビリティとメトリクス収集を設定するための主要なメソッドが3つ用意されています:setMetricsRecorder(MetricsRecorder recorder): 運用メトリクス (所要時間、出現回数、再試行、エラー) をエクスポートするためのメトリクスレコーダーを登録します。明示的に設定しない場合のデフォルトはDefaultMetricsRecorder.NOOPです。setSpanRecorder(SpanRecorder recorder): 分散トレーシング用のスパンレコーダー (操作スパンおよびトランスポートリクエストスパン) を登録します。明示的に設定しない場合のデフォルトはDefaultSpanRecorder.NOOPです。registerClientMetrics(Object registry, String groupName): Apache HttpClient の接続プールのメトリクス (利用可能な接続数、リース中の接続数、保留中のリクエスト数、接続の作成時間など) を Micrometer のMeterRegistryにバインドします。
OpenTelemetrySpanRecorder クラスと MicrometerMetricsRecorder クラスは、client-v2 パッケージの一部として提供されています。ただし、これらを使用するには、ランタイムにおいてアプリケーションのクラスパス上に OpenTelemetry API (io.opentelemetry:opentelemetry-api) および Micrometer (io.micrometer:micrometer-core) ライブラリが存在している必要があります。メインのクライアントアーティファクトには、これらのサードパーティ製の依存関係は同梱されておらず、推移的に取り込まれることもありません。OpenTelemetry のトレーシングや Micrometer のメトリクスを使用するアプリケーションでは、プロジェクトのビルド設定 (pom.xml または build.gradle) でこれらの依存関係を明示的に宣言する必要があります。Builder の設定例- OpenTelemetry エージェント & グローバル自動設定:
- OpenTelemetry Java Agent またはグローバル SDK の自動設定を使用しているアプリケーションでは、
OpenTelemetrySpanRecorderとMicrometerMetricsRecorderを、引数なしのデフォルトコンストラクターでインスタンス化してください。 - デフォルトコンストラクターは、
GlobalOpenTelemetry.get()と Micrometer のMetrics.globalRegistryに自動的にバインドされます。
- OpenTelemetry Java Agent またはグローバル SDK の自動設定を使用しているアプリケーションでは、
- 明示的なクライアントレベルの連携:
- 明示的に作成した
OpenTelemetry、Tracer、または Micrometer のMeterRegistryインスタンスを、レコーダーのコンストラクターに直接渡します。 - 互いに分離された複数のクライアントや、それぞれ独立したテレメトリーシンクを持つ multi-tenant サービスを管理する場合に最適です。
- 明示的に作成した
報告されるメトリクス
オペレーションメトリクス
MetricsRecorder 経由でエクスポートされたメトリクスは、データベースクライアントメトリクスに関する OpenTelemetry のセマンティック規約 (MetricName および MetricAttribute) に準拠します:メトリクスの属性 / タグ
MicrometerMetricsRecorder によって作成されるメーターには、低カーディナリティのタグ (MetricAttribute) が付与されます:コネクションプールのメトリクス
registerClientMetrics(meterRegistry, "groupName") を呼び出すと、HTTP接続プールの Gauge が Micrometer に登録されます:httpcomponents.httpclient.pool.total.max: 設定済みの永続接続の最大許容数。httpcomponents.httpclient.pool.total.connections(state="available"またはstate="leased"のタグ付き): プール内の有効な接続数。httpcomponents.httpclient.pool.total.pending: 空き接続を待機している接続リクエストの数。httpcomponents.httpclient.pool.route.max.default: 設定済みのルートごとのデフォルト最大接続数。httpcomponents.httpclient.connect.time: 接続確立時間の移動平均。
レスポンスメトリクス API
メトリクスレコーダーに加えて、レスポンスオブジェクト (QueryResponse、InsertResponse) からも OperationMetrics を介して詳細な実行統計に直接アクセスできます。送信されるスパン
Client V2 のトレーシングでは、親子の階層構造を持つ 2 種類のスパンが生成されます。- Operation Span: 高レベルのクライアント操作 (
QUERY <database>またはINSERT <database>.<table_name>) を表します。現在のスレッドのトレースコンテキスト (Context.current()) 配下で開始されるため、データベース操作は呼び出し元の有効なトレーススパンに紐付けられます。 - Transport Request Span: 個々の HTTP トランスポートリクエストの試行 (
POST) を表します。対応する操作スパンの子として作成されます。再試行のたびに、操作スパンの配下に新しいトランスポートリクエストスパンが作成されます。
スパンの属性
スパンには標準の OpenTelemetry 属性 (SpanAttribute) が設定されます:非同期境界をまたいだコンテキストの伝播: クライアント V2 は
Context.current() を継承するため、有効なトレーススパンを持つスレッド上で開始された操作は、自動的にそのトレースに組み込まれます。スレッドプール間でタスクを委譲する場合 (例: Spring の @Async やカスタムの ExecutorService) は、OpenTelemetry のコンテキストを明示的に伝播させてください。カスタムレコーダーの開発
独自のオブザーバビリティバックエンドを使用するアプリケーションでは、DefaultMetricsRecorder (メトリクス用) または DefaultSpanRecorder (トレーシング用) を拡張することで、カスタムレコーダーを実装できます。DefaultMetricsRecorder:MetricsRecorderの基本実装です。recordQuerySuccessやrecordQueryFailureなど、必要なコールバックをオーバーライドして使用します。標準のメトリクス名 (MetricName)、単位、および属性の Map (MetricAttribute) を導出するには、MetricsSupport.DEFAULTを使用します。DefaultSpanRecorder:SpanRecorderの基本実装です。startQuerySpan、startInsertSpan、startRequestSpanなどのスパン作成コールバックをオーバーライドして使用します。標準の OpenTelemetry スパン名および属性 (SpanAttribute) を算出するには、SpanSupport.DEFAULTを使用します。
com.clickhouse.client.api.observability.otel.OpenTelemetrySpanRecorder(OpenTelemetry トレーシングとのインテグレーション)com.clickhouse.client.api.observability.micrometer.MicrometerMetricsRecorder(Micrometer メトリクスとのインテグレーション)
移行ガイド
旧クライアント (V1) ではcom.clickhouse.client.ClickHouseClient#builderを起点として使用していました。新クライアント (V2) ではcom.clickhouse.client.api.Client.Builderを用いた同様のパターンを採用しています。主な相違点は以下のとおりです:- 実装の取得に service loader は使用されません。
com.clickhouse.client.api.Clientは、将来的にさまざまな実装に対応するためのファサードクラスです。 - 設定の定義元が少なくなりました。1 つはビルダーに渡され、もう 1 つは操作設定 (
QuerySettings、InsertSettings) にあります。以前のバージョンではノードごとの設定があり、場合によっては 環境変数を読み込んでいました。
設定パラメーターの一致
V1にはconfigurationに関連するenumクラスが3つあります:com.clickhouse.client.config.ClickHouseDefaults- ほとんどのユースケースで設定しておくことが想定される設定パラメータです。USERやPASSWORDなどが該当します。com.clickhouse.client.config.ClickHouseClientOption- クライアント固有の設定パラメータです。HEALTH_CHECK_INTERVALなどが該当します。com.clickhouse.client.http.config.ClickHouseHttpOption- HTTPインターフェイス固有の設定パラメータです。RECEIVE_QUERY_PROGRESSなどがあります。
com.clickhouse.client.config.ClickHouseDefaults#ASYNC と
com.clickhouse.client.config.ClickHouseClientOption#ASYNC に違いはあるのか、など) 。新しい V2 クライアントでは、com.clickhouse.client.api.Client.Builder をすべてのクライアント設定オプションを網羅する単一の Dictionary として使用します。また、すべての設定パラメータ名が列挙された
com.clickhouse.client.api.ClientConfigProperties も用意されています。以下の表に、新しいクライアントでサポートされている旧オプションとその新しい意味を示します。凡例: ✔ = サポート対象、✗ = 非対応- 接続 & 認証
- SSL & セキュリティ
- ソケットオプション
- 圧縮
- プロキシ
- タイムアウトと再試行
- タイムゾーン
- バッファとパフォーマンス
- スレッド & 非同期
- HTTP とヘッダー
- フォーマット & クエリ
- ノードディスカバリ & ロードバランシング
- その他
主な相違点
- Client V2 は、移植性を高めるために独自クラスへの依存を減らしています。たとえば、V2 では、サーバーにデータを書き込む際に
java.io.InputStreamの任意の実装を利用できます。 - Client V2 の
async設定は、デフォルトでoffです。これは、余分なスレッドが作成されず、クライアントをアプリケーション側でより細かく制御できることを意味します。この設定は、ほとんどのユースケースでoffのままにしておくべきです。asyncを有効にすると、リクエストごとに別スレッドが作成されます。これは、アプリケーション側で制御する executor を使用する場合にのみ意味があります (com.clickhouse.client.api.Client.Builder#setSharedOperationExecutorを参照)
データの書き込み
java.io.InputStreamの任意の実装を使用できます。V1 のcom.clickhouse.data.ClickHouseInputStreamもサポートされていますが、推奨はされていません。- 入力ストリームの終端が検出されると、それに応じて処理されます。従来は、リクエストの出力ストリームを閉じる必要がありました。
- 呼び出すメソッドは1つだけです。追加のリクエストオブジェクトを作成する必要はありません。
- すべてのデータのコピーが完了すると、リクエストボディのストリームは自動的に閉じられます。
- 新しい低レベルAPI
com.clickhouse.client.api.Client#insert(java.lang.String, java.util.List<java.lang.String>, com.clickhouse.client.api.DataStreamWriter, com.clickhouse.data.ClickHouseFormat, com.clickhouse.client.api.insert.InsertSettings)が利用できます。com.clickhouse.client.api.DataStreamWriterは、カスタムのデータ書き込みロジックを実装できるように設計されています。たとえば、キューからデータを読み取る ケースです。
データの読み取り
- デフォルトでは、データは
RowBinaryWithNamesAndTypesフォーマットで読み込まれます。現時点で、データのバインディングが必要な場合に対応しているのはこのフォーマットのみです。 - データは、
List<GenericRecord> com.clickhouse.client.api.Client#queryAll(java.lang.String)メソッドを使用して、レコードのコレクションとして読み取ることができます。これにより、データはメモリに読み込まれ、connection は解放されます。追加の処理は必要ありません。GenericRecordを使うとデータにアクセスでき、いくつかの変換も行えます。