Javaクライアント
Javaクライアントライブラリは、プロトコルを介してDBサーバーと通信するためのものです。現在の実装は、HTTPインターフェースのサポートのみを提供しています。このライブラリは、サーバーにリクエストを送信するための独自のAPIを提供し、さまざまなバイナリデータフォーマット（RowBinary* & Native*）で作業するためのツールも提供しています。
セットアップ
- Maven Central（プロジェクトウェブページ）： https://mvnrepository.com/artifact/com.clickhouse/client-v2
- ナイトリービルド（リポジトリリンク）： https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/
- Maven
- Gradle (Kotlin)
- Gradle
初期化
Clientオブジェクトは com.clickhouse.client.api.Client.Builder#build() によって初期化されます。各クライアントには独自のコンテキストがあり、オブジェクトは共有されません。Builderには、便利な設定用のメソッドがあります。
例:
Client は AutoCloseable であり、不要になったときは閉じる必要があります。
認証
認証は初期化段階でクライアントごとに設定されます。サポートされている認証方法は3つあり：パスワードによる認証、アクセストークンによる認証、SSLクライアント証明書による認証です。
パスワードによる認証は、setUsername(String) と setPassword(String) を呼び出してユーザー名とパスワードを設定します：
アクセストークンによる認証は、setAccessToken(String) を呼び出してアクセストークンを設定します：
SSLクライアント証明書による認証は、ユーザー名を設定し、SSL認証を有効にし、クライアント証明書およびクライアントキーをそれぞれ setUsername(String)、useSSLAuthentication(boolean)、setClientCertificate(String)、setClientKey(String) を呼び出して設定する必要があります：
SSL認証は、SSLライブラリからの多くのエラーが十分な情報を提供しないため、本番環境でのトラブルシューティングが難しい場合があります。たとえば、クライアント証明書とキーが一致しない場合、サーバーは接続を即座に終了します（HTTPの場合、これは接続初期化段階であり、HTTPリクエストは送信されないため、レスポンスは送信されません）。
opensslなどのツールを使用して証明書とキーを検証してください：
- キーの整合性を確認する：
openssl rsa -in [key-file.key] -check -noout - ユーザーの証明書からCNを取得する： -
openssl x509 -noout -subject -in [user.cert] - DB内で同じ値が設定されていることを確認する：
select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'（クエリは{"common_names":["some_user"]}のようなauth_paramsを出力します）。
設定
すべての設定はインスタンスメソッド（いわゆる設定メソッド）によって定義され、各値のスコープとコンテキストが明確になります。主要な設定パラメータは1つのスコープ（クライアントまたは操作）で定義され、互いに上書きされることはありません。
設定はクライアント作成時に定義されます。 com.clickhouse.client.api.Client.Builder を参照してください。
クライアント設定
| 設定メソッド | 引数 | 説明 |
|---|---|---|
addEndpoint(String endpoint) | - enpoint - サーバーアドレスのURL形式。 | 利用可能なサーバーのエンドポイントにサーバーエンドポイントを追加します。現在は1つのエンドポイントのみがサポートされています。 |
addEndpoint(Protocol protocol, String host, int port, boolean secure) | - protocol - 接続プロトコル com.clickhouse.client.api.enums.Protocol#HTTP.- host - サーバーのIPまたはホスト名。- secure - 通信にプロトコルの安全なバージョン（HTTPS）を使用する必要があるかどうか。 | 利用可能なサーバーのエンドポイントにサーバーエンドポイントを追加します。現在は1つのエンドポイントのみがサポートされています。 |
setOption(String key, String value) | - key - クライアント設定オプションの文字列キー。- value - オプションの文字列値。 | クライアントオプションの生の値を設定します。プロパティファイルからの設定を読み込むときに便利です。 |
setUsername(String username) | - username - 認証時に使用するユーザー名。 | 選択された認証メソッドのユーザー名を設定します。 |
setPassword(String password) | - password - パスワード認証用の秘密値。 | パスワード認証用の秘密を設定し、実質的に認証メソッドを選択します。 |
setAccessToken(String accessToken) | - accessToken - アクセストークンの文字列表現。 | 対応する認証メソッドで認証するためのアクセストークンを設定します。 |
useSSLAuthentication(boolean useSSLAuthentication) | - useSSLAuthentication - SSL認証を使用するかどうかを示すフラグ。 | SSLクライアント証明書を認証メソッドとして設定します。 |
enableConnectionPool(boolean enable) | - enable - オプションを有効にするかどうかを示すフラグ。 | コネクションプールが有効かどうかを設定します。 |
setConnectTimeout(long timeout, ChronoUnit unit) | - timeout - 一定の時間単位でのタイムアウト。- unit - timeoutの時間単位。 | すべてのアウトゴーイング接続の接続初期化タイムアウトを設定します。これはソケット接続の取得待機時間に影響します。 |
setConnectionRequestTimeout(long timeout, ChronoUnit unit) | - timeout - 一定の時間単位でのタイムアウト。- unit - timeoutの時間単位。 | 接続リクエストタイムアウトを設定します。これはプールから接続を取得する場合のみに影響します。 |
setMaxConnections(int maxConnections) | - maxConnections - 接続の数。 | 各サーバーエンドポイントに対してクライアントがオープンできる接続の数を設定します。 |
setConnectionTTL(long timeout, ChronoUnit unit) | - timeout - 一定の時間単位でのタイムアウト。- unit - timeoutの時間単位。 | 接続が非アクティブと見なされる接続TTLを設定します。 |
setKeepAliveTimeout(long timeout, ChronoUnit unit) | - timeout - 一定の時間単位でのタイムアウト。- unit - timeoutの時間単位。 | HTTP接続のキープアライブタイムアウトを設定します。このオプションは、タイムアウトをゼロに設定することでキープアライブを無効にすることもできます - 0 |
setConnectionReuseStrategy(ConnectionReuseStrategy strategy) | - strategy - 列挙型 com.clickhouse.client.api.ConnectionReuseStrategy 定数。 | コネクションプールが使用すべき戦略を選択します：LIFO（接続がプールに戻されたときにすぐに再使用されるべき場合）またはFIFO（接続が利用可能になる順に使用される場合）。戻った接続は即座に使用されません。 |
setSocketTimeout(long timeout, ChronoUnit unit) | - timeout - 一定の時間単位でのタイムアウト。- unit - timeoutの時間単位。 | 読み取りおよび書き込み操作に影響を与えるソケットタイムアウトを設定します。 |
setSocketRcvbuf(long size) | - size - バイト数。 | TCPソケットの受信バッファサイズを設定します。このバッファはJVMメモリの外部です。 |
setSocketSndbuf(long size) | - size - バイト数。 | TCPソケットの送信バッファサイズを設定します。このバッファはJVMメモリの外部です。 |
setSocketKeepAlive(boolean value) | - value - オプションが有効にすべきかどうかを示すフラグ。 | クライアントによって生成されたすべてのTCPソケットに対してSO_KEEPALIVEオプションを設定します。TCPキープアライブは、接続の生存をチェックするメカニズムを有効にし、突然終了した接続を検出するのに役立ちます。 |
setSocketTcpNodelay(boolean value) | - value - オプションが有効にすべきかどうかを示すフラグ。 | クライアントによって生成されたすべてのTCPソケットに対してSO_NODELAYオプションを設定します。このTCPオプションは、ソケットができるだけ早くデータをプッシュすることを可能にします。 |
setSocketLinger(int secondsToWait) | - secondsToWait - 待機する秒数。 | クライアントによって生成されたすべてのTCPソケットのラングタイムを設定します。 |
compressServerResponse(boolean enabled) | - enabled - オプションが有効にすべきかどうかを示すフラグ。 | サーバーがレスポンスを圧縮すべきかどうかを設定します。 |
compressClientRequest(boolean enabled) | - enabled - オプションが有効にすべきかどうかを示すフラグ。 | クライアントがリクエストを圧縮すべきかどうかを設定します。 |
useHttpCompression(boolean enabled) | - enabled - オプションが有効にすべきかどうかを示すフラグ。 | クライアント/サーバー間の通信にHTTP圧縮を使用するかどうかを設定します。対応するオプションが有効になっている場合。 |
setLZ4UncompressedBufferSize(int size) | - size - バイト数。 | データストリームの未圧縮部分を受け取るためのバッファのサイズを設定します。バッファが過小評価されている場合、新しいものが作成され、対応する警告がログに表示されます。 |
setDefaultDatabase(String database) | - database - データベースの名前。 | デフォルトのデータベースを設定します。 |
addProxy(ProxyType type, String host, int port) | - type - プロキシの種類。- host - プロキシのホスト名またはIPアドレス。- port - プロキシポート。 | サーバーとの通信に使用されるプロキシを設定します。プロキシが認証を要求する場合は、プロキシを設定する必要があります。 |
setProxyCredentials(String user, String pass) | - user - プロキシのユーザー名。- pass - パスワード。 | プロキシへの認証に使用されるユーザーの認証情報を設定します。 |
setExecutionTimeout(long timeout, ChronoUnit timeUnit) | - timeout - 一定の時間単位でのタイムアウト。- timeUnit - timeoutの時間単位。 | クエリの最大実行タイムアウトを設定します。 |
setHttpCookiesEnabled(boolean enabled) | - enabled - オプションが有効にすべきかどうかを示すフラグ。 | HTTPクッキーが記憶され、サーバーに戻されるべきかどうかを設定します。 |
setSSLTrustStore(String path) | - path - ローカル（クライアント側）システム上のファイルパス。 | クライアントがサーバーホストの検証にSSLトラストストアを使用すべきかどうかを設定します。 |
setSSLTrustStorePassword(String password) | - password - 秘密値。 | setSSLTrustStore(String path)で指定されたSSLトラストストアを解除するために使用されるパスワードを設定します。 |
setSSLTrustStoreType(String type) | - type - トラストストアタイプ名。 | setSSLTrustStore(String path)で指定されたトラストストアのタイプを設定します。 |
setRootCertificate(String path) | - path - ローカル（クライアント側）システム上のファイルパス。 | クライアントが指定されたルート（CA）証明書を使用してサーバーホストを検証すべきか設定します。 |
setClientCertificate(String path) | - path - ローカル（クライアント側）システム上のファイルパス。 | SSL接続を開始する際に使用されるクライアント証明書のパスを設定します。SSL認証のために使用されます。 |
setClientKey(String path) | - path - ローカル（クライアント側）システム上のファイルパス。 | サーバーとのSSL通信を暗号化するために使用されるクライアントプライベートキーを設定します。 |
useServerTimeZone(boolean useServerTimeZone) | - useServerTimeZone - オプションが有効にすべきかどうかを示すフラグ。 | デコード時にクライアントがサーバーのタイムゾーンを使用するべきかどうかを設定します。DateTimeおよびDateカラムの値。これが有効になっている場合、サーバータイムゾーンはsetServerTimeZone(String timeZone)で設定する必要があります。 |
useTimeZone(String timeZone) | - timeZone - javaの有効なタイムゾーンIDの文字列値（java.time.ZoneIdを参照）。 | デコード時に指定されたタイムゾーンを使用すべきかどうかを設定します。DateTimeおよびDateカラムの値。サーバータイムゾーンを上書きします。 |
setServerTimeZone(String timeZone) | - timeZone - javaの有効なタイムゾーンIDの文字列値（java.time.ZoneIdを参照）。 | サーバー側のタイムゾーンを設定します。デフォルトではUTCタイムゾーンが使用されます。 |
useAsyncRequests(boolean async) | - async - オプションが有効にすべきかどうかを示すフラグ。 | クライアントがリクエストを別スレッドで実行するべきかどうかを設定します。これはデフォルトでは無効です。アプリケーションはマルチスレッドタスクを整理する方法をよりよく知っており、タスクを別スレッドで実行してもパフォーマンスは向上しません。 |
setSharedOperationExecutor(ExecutorService executorService) | - executorService - エグゼキューターサービスのインスタンス。 | 操作タスクのためのエグゼキューターサービスを設定します。 |
setClientNetworkBufferSize(int size) | - size - バイト数。 | ソケットとアプリケーション間でデータを往復するために使用されるアプリケーションメモリ空間のバッファのサイズを設定します。大きな値はTCPスタックへのシステムコールを減らしますが、各接続にどれだけのメモリが消費されるかに影響します。このバッファもGCの影響を受けるため、接続が短命です。また、大きな連続メモリブロックの割り当ては問題となる可能性があります。デフォルトは300,000バイトです。 |
retryOnFailures(ClientFaultCause ...causes) | - causes - com.clickhouse.client.api.ClientFaultCauseの列挙定数。 | 復旧可能または再試行可能な障害タイプを設定します。 |
setMaxRetries(int maxRetries) | - maxRetries - 再試行の数。 | retryOnFailures(ClientFaultCause ...causes)で定義された失敗に対する最大再試行回数を設定します。 |
allowBinaryReaderToReuseBuffers(boolean reuse) | - reuse - オプションが有効にすべきかどうかを示すフラグ。 | ほとんどのデータセットには、小さなバイト列としてエンコードされた数値データが含まれています。デフォルトでは、リーダーは必要なバッファを割り当て、データをそこに読み込み、次にターゲットのNumberクラスに変換します。これにより、多くの小さなオブジェクトが割り当てられ解除されるため、かなりのGC圧力がかかる可能性があります。このオプションが有効になっている場合、リーダーは再利用可能なバッファを使用して数値を変換します。これは安全です。各リーダーは独自のバッファセットを持ち、リーダーは1つのスレッドによって使用されます。 |
httpHeader(String key, String value) | - key - HTTPヘッダのキー。- value - ヘッダの文字列値。 | 1つのHTTPヘッダの値を設定します。以前の値は上書きされます。 |
httpHeader(String key, Collection values) | - key - HTTPヘッダのキー。- values - 文字列値のリスト。 | 1つのHTTPヘッダの値を設定します。以前の値は上書きされます。 |
httpHeaders(Map headers) | - header - HTTPヘッダとその値のマップ。 | 複数のHTTPヘッダ値を一度に設定します。 |
serverSetting(String name, String value) | - name - クエリレベル設定の名前。- value - 設定の文字列値。 | 各クエリと共にサーバーに渡す設定を設定します。個別の操作設定がこれを上書きすることがあります。設定のリスト |
serverSetting(String name, Collection values) | - name - クエリレベル設定の名前。- values - 設定の文字列値。 | 各クエリと共にサーバーに渡す設定を設定します。個別の操作設定がこれを上書きすることがあります。設定のリスト。このメソッドは、複数の値を持つ設定を設定するのに便利です。たとえば、roles |
columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy) | - strategy - カラムとフィールドの一致戦略の実装。 | DTOクラスフィールドとDBカラムを登録する際に使用されるカスタム戦略を設定します。 |
useHTTPBasicAuth(boolean useBasicAuth) | - useBasicAuth - オプションが有効にすべきかどうかを示すフラグ。 | ユーザー名とパスワードによる認証に基本HTTP認証を使用すべきかどうかを設定します。デフォルトは有効です。この認証方式を使用すると、HTTPヘッダを転送できない特殊文字を含むパスワードの問題が解決されます。 |
setClientName(String clientName) | - clientName - アプリケーション名を表す文字列。 | 呼び出すアプリケーションに関する追加情報を設定します。この文字列は、クライアント名としてサーバーに渡されます。HTTPプロトコルの場合、User-Agentヘッダーとして渡されます。 |
useBearerTokenAuth(String bearerToken) | - bearerToken - エンコードされたベアラートークン。 | ベアラー認証を使用し、どのトークンを使用するかを指定します。トークンはそのまま送信されるため、このメソッドに渡す前にエンコードする必要があります。 |
一般定義
ClickHouseFormat
サポートされているフォーマットの列挙型です。ClickHouseがサポートするすべてのフォーマットを含んでいます。
raw- ユーザーは生データをトランスコーディングする必要があります。full- クライアントは自身でデータをトランスコードでき、生データストリームを受け入れます。-- ClickHouseがこのフォーマットに対してサポートしていない操作。
このクライアントバージョンでは次のフォーマットがサポートされています：
インサートAPI
insert(String tableName, InputStream data, ClickHouseFormat format)
指定されたフォーマットの InputStream バイトとしてデータを受け付けます。data は format でエンコードされていると期待されます。
シグネチャ
パラメータ
tableName - 対象のテーブル名。
data - エンコードされたデータの入力ストリーム。
format - データがエンコードされているフォーマット。
settings - リクエスト設定。
返り値
InsertResponse 型の Future - 操作の結果とサーバー側のメトリクスのような追加情報。
例
insert(String tableName, List<?> data, InsertSettings settings)
データベースに書き込みリクエストを送信します。オブジェクトのリストは効率的なフォーマットに変換されてからサーバーに送信されます。リストアイテムのクラスは、register(Class, TableSchema) メソッドを使用して事前に登録する必要があります。
シグネチャ
パラメータ
tableName - 対象テーブルの名前。
data - コレクションDTO（データ転送オブジェクト）オブジェクト。
settings - リクエスト設定。
返り値
InsertResponse 型の Future - 操作の結果とサーバー側のメトリクスのような追加情報。
例
InsertSettings
挿入操作のための設定オプション。
設定メソッド
| メソッド | 説明 |
|---|---|
setQueryId(String queryId) | 操作に割り当てられるクエリIDを設定します。デフォルト: null。 |
setDeduplicationToken(String token) | 重複排除トークンを設定します。このトークンはサーバーに送信され、クエリを識別するのに使用できます。デフォルト: null。 |
setInputStreamCopyBufferSize(int size) | コピーバッファサイズ。バッファは、ユーザー提供の入力ストリームから出力ストリームにデータをコピーする際に使用されます。デフォルト: 8196。 |
serverSetting(String name, String value) | 操作のための個別のサーバー設定を設定します。 |
serverSetting(String name, Collection values) | 複数の値を持つ個別のサーバー設定を設定します。コレクションのアイテムは String 値でなければなりません。 |
setDBRoles(Collection dbRoles) | 操作を実行する前に設定されるDBロールを設定します。コレクションのアイテムは String 値でなければなりません。 |
setOption(String option, Object value) | 生の形式で設定オプションを設定します。これはサーバー設定ではありません。 |
InsertResponse
挿入操作の結果を保持するレスポンスオブジェクト。クライアントがサーバーからレスポンスを受け取ったときのみ利用可能です。
このオブジェクトは可能な限り早くクローズして、接続を解放する必要があります。以前のレスポンスのすべてのデータが完全に読み取られるまで、接続は再利用できません。
| メソッド | 説明 |
|---|---|
OperationMetrics getMetrics() | 操作メトリクスを持つオブジェクトを返します。 |
String getQueryId() | アプリケーションによって操作に割り当てられたクエリIDを返します（操作設定またはサーバーによって）。 |
Query API
query(String sqlQuery)
sqlQuery をそのまま送信します。レスポンスフォーマットはクエリ設定によって設定されます。QueryResponse は、サポートされているフォーマットのために、読む必要のあるレスポンスストリームへの参照を保持します。
シグネチャ
パラメータ
sqlQuery - 単一のSQLステートメント。クエリはそのままサーバーに送信されます。
settings - リクエスト設定。
返り値
QueryResponse 型の Future - 結果データセットおよびサーバー側メトリクスのような追加情報。レスポンスオブジェクトはデータセットを消費した後にクローズする必要があります。
例
query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)
sqlQuery をそのまま送り、サーバーがSQL式をコンパイルできるようにクエリパラメータも追加で送信します。
シグネチャ
パラメータ
sqlQuery - プレースホルダー {} を持つSQL式。
queryParams - サーバーでSQL式を完成させるための変数のマップ。
settings - リクエスト設定。
返り値
QueryResponse 型の Future - 結果データセットおよびサーバー側メトリクスのような追加情報。レスポンスオブジェクトはデータセットを消費した後にクローズする必要があります。
例
queryAll(String sqlQuery)
RowBinaryWithNamesAndTypes フォーマットでデータをクエリします。結果はコレクションとして返されます。読み取りパフォーマンスはリーダーと同じですが、全データセットを保持するためにはより多くのメモリが必要です。
シグネチャ
パラメータ
sqlQuery - サーバーからデータをクエリするためのSQL式。
返り値
結果データに行スタイルでアクセスを提供する GenericRecord オブジェクトのリストとして表される完全なデータセット。
例
QuerySettings
クエリ操作のための設定オプション。
設定メソッド
| メソッド | 説明 |
|---|---|
setQueryId(String queryId) | 操作に割り当てられるクエリIDを設定します。 |
setFormat(ClickHouseFormat format) | レスポンスフォーマットを設定します。完全なリストについては RowBinaryWithNamesAndTypes を参照してください。 |
setMaxExecutionTime(Integer maxExecutionTime) | サーバー上の操作実行時間を設定します。読み取りタイムアウトには影響しません。 |
waitEndOfQuery(Boolean waitEndOfQuery) | サーバーにレスポンスを送信する前にクエリの終了を待つようリクエストします。 |
setUseServerTimeZone(Boolean useServerTimeZone) | サーバーのタイムゾーン（クライアント設定を参照）が、操作の結果のデータ/時間型を解析するために使用されます。デフォルトは false。 |
setUseTimeZone(String timeZone) | サーバーに timeZone を使用して時間変換を行うようリクエストします。詳細は session_timezone を参照してください。 |
serverSetting(String name, String value) | 操作のための個別のサーバー設定を設定します。 |
serverSetting(String name, Collection values) | 複数の値を持つ個別のサーバー設定を設定します。コレクションのアイテムは String 値でなければなりません。 |
setDBRoles(Collection dbRoles) | 操作を実行する前に設定されるDBロールを設定します。アイテムのコレクションは String 値でなければなりません。 |
setOption(String option, Object value) | 生の形式で設定オプションを設定します。これはサーバー設定ではありません。 |
QueryResponse
クエリ実行の結果を保持するレスポンスオブジェクト。クライアントがサーバーからレスポンスを受け取ったときのみ利用可能です。
このオブジェクトは可能な限り早くクローズして、接続を解放する必要があります。以前のレスポンスのすべてのデータが完全に読み取られるまで、接続は再利用できません。
| メソッド | 説明 |
|---|---|
ClickHouseFormat getFormat() | レスポンスでデータがエンコードされているフォーマットを返します。 |
InputStream getInputStream() | 指定されたフォーマットでのデータの非圧縮バイトストリームを返します。 |
OperationMetrics getMetrics() | 操作メトリクスを持つオブジェクトを返します。 |
String getQueryId() | アプリケーションによって操作に割り当てられたクエリIDを返します（操作設定またはサーバーによって）。 |
TimeZone getTimeZone() | レスポンス内の Date/DateTime タイプを処理するために使用するべきタイムゾーンを返します。 |
Examples
Common API
getTableSchema(String table)
table のテーブルスキーマを取得します。
シグネチャ
パラメータ
table - スキーマデータを取得するテーブル名。
database - 対象テーブルが定義されているデータベース。
返り値
テーブルカラムのリストを持つ TableSchema オブジェクトを返します。
getTableSchemaFromQuery(String sql)
SQLステートメントからスキーマを取得します。
シグネチャ
パラメータ
sql - スキーマを返すべき "SELECT" SQL ステートメント。
返り値
sql 式に一致するカラムを持つ TableSchema オブジェクトを返します。
TableSchema
register(Class<?> clazz, TableSchema schema)
データを書き込み/読み込みに使うためのJavaクラスのシリアル化とデシリアル化レイヤーをコンパイルします。メソッドは、ペアゲッター/セッターと対応するカラムのためのシリアライザーとデシリアライザーを作成します。
カラムの一致は、メソッド名からその名前を抽出することによって見つけられます。例えば、getFirstName はカラム first_name または firstname に対応します。
シグネチャ
パラメータ
clazz - データの読み書きに使用するPOJOを表すクラス。
schema - POJOプロパティと一致させるために使用するデータスキーマ。
例
Usage Examples
完全な例のコードはリポジトリの 'example' フォルダ に保存されています：
- client-v2 - 主要な例のセット。
- demo-service - Spring Boot アプリケーションでのクライアントの使用例。
- demo-kotlin-service - Ktor (Kotlin) アプリケーションでのクライアントの使用例。
