30 KiB
| sidebar_label | sidebar_position | keywords | description | slug | ||||
|---|---|---|---|---|---|---|---|---|
| Client V2 | 2 |
|
Java ClickHouse Connector v2 | /ja/integrations/java/client-v2 |
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock';
Java クライアント (V2)
DBサーバーとそのプロトコルを介して通信するためのJavaクライアントライブラリです。現在の実装はHTTPインターフェースのみをサポートしています。このライブラリは、サーバーにリクエストを送信するための独自のAPIを提供します。また、さまざまなバイナリデータ形式（RowBinary* & Native*）で作業するためのツールも提供します。
セットアップ
- Maven Central (プロジェクトウェブページ): https://mvnrepository.com/artifact/com.clickhouse/client-v2
- ナイトリービルド (リポジトリリンク): https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/
<dependency>
<groupId>com.clickhouse</groupId>
<artifactId>client-v2</artifactId>
<version>0.6.5</version>
</dependency>
// https://mvnrepository.com/artifact/com.clickhouse/client-v2
implementation("com.clickhouse:client-v2:0.6.5")
// https://mvnrepository.com/artifact/com.clickhouse/client-v2
implementation 'com.clickhouse:client-v2:0.6.5'
初期化
com.clickhouse.client.api.Client.Builder#build()によってクライアントオブジェクトが初期化されます。各クライアントは独自のコンテキストを持ち、オブジェクト間で共有されません。ビルダーには便利な設定のためのメソッドが用意されています。
例:
Client client = new Client.Builder()
.addEndpoint("https://clickhouse-cloud-instance:8443/")
.setUsername(user)
.setPassword(password)
.build();
ClientはAutoCloseableであり、不要になったら閉じる必要があります。
設定
すべての設定はインスタンスメソッド（設定メソッドとして知られる）によって定義され、それぞれの値のスコープとコンテキストを明確にします。 主要な設定パラメータは一つのスコープ（クライアントまたは操作）に定義され、互いにオーバーライドされません。
設定はクライアント作成時に定義されます。com.clickhouse.client.api.Client.Builderを参照してください。
共通定義
ClickHouseFormat
サポートされるフォーマットの列挙です。ClickHouseがサポートするすべてのフォーマットを含みます。
raw- ユーザーは生データをトランスコードする必要がありますfull- クライアントはデータを自分でトランスコードでき、生データストリームを受け入れます-- このフォーマットではClickHouseでは操作サポートされていません
このクライアントバージョンがサポートするもの:
データ挿入API
insert(String tableName, InputStream data, ClickHouseFormat format)
指定されたフォーマットでエンコードされたバイトのInputStreamとしてデータを受け入れます。dataがformatでエンコードされていることが期待されます。
シグネチャ
CompletableFuture<InsertResponse> insert(String tableName, InputStream data, ClickHouseFormat format, InsertSettings settings)
CompletableFuture<InsertResponse> insert(String tableName, InputStream data, ClickHouseFormat format)
パラメータ
tableName - 対象テーブル名。
data - エンコードされたデータの入力ストリーム。
format - データがエンコードされた形式。
settings - リクエスト設定。
戻り値
InsertResponse型のFuture - 操作結果とサーバサイドのメトリクスなどの追加情報。
例
try (InputStream dataStream = getDataStream()) {
try (InsertResponse response = client.insert(TABLE_NAME, dataStream, ClickHouseFormat.JSONEachRow,
insertSettings).get(3, TimeUnit.SECONDS)) {
log.info("Insert finished: {} rows written", response.getMetrics().getMetric(ServerMetrics.NUM_ROWS_WRITTEN).getLong());
} catch (Exception e) {
log.error("Failed to write JSONEachRow data", e);
throw new RuntimeException(e);
}
}
insert(String tableName, List data, InsertSettings settings)
データベースに書き込みリクエストを送信します。オブジェクトのリストは効率的な形式に変換され、その後サーバーに送信されます。リストアイテムのクラスは、事前にregister(Class, TableSchema)メソッドを使用して登録する必要があります。
シグネチャ
client.insert(String tableName, List<?> data, InsertSettings settings)
client.insert(String tableName, List<?> data)
パラメータ
tableName - 対象のテーブル名。
data - DTO (Data Transfer Object) オブジェクトのコレクション。
settings - リクエスト設定。
戻り値
InsertResponse型のFuture - 操作結果とサーバサイドのメトリクスなどの追加情報。
例
// 重要なステップ（1回だけ実行）：テーブルスキーマに従ってオブジェクトシリアライザを事前コンパイルするためにクラスを登録。
client.register(ArticleViewEvent.class, client.getTableSchema(TABLE_NAME));
List<ArticleViewEvent> events = loadBatch();
try (InsertResponse response = client.insert(TABLE_NAME, events).get()) {
// 応答を処理し、リクエストをサーブした後に閉じられ、接続が解放されます。
}
InsertSettings
挿入操作のための設定オプション。
設定メソッド
- setQueryId(String queryId)
- 操作に割り当てられるクエリIDを設定します
- setDeduplicationToken(String token)
- 重複除外トークンを設定します。このトークンはサーバーに送信され、クエリを識別するために使用されます。
- waitEndOfQuery(Boolean waitEndOfQuery)
- クエリの終了を待ってから応答を送信するようサーバーにリクエストします。
- setInputStreamCopyBufferSize(int size)
- コピー時のバッファサイズ。ユーザー提供の入力ストリームから出力ストリームへの書き込み操作中に使用されるバッファです。
InsertResponse
挿入操作の結果を保持する応答オブジェクトです。このオブジェクトはサーバーから応答を受け取った場合にのみ利用可能です。
:::note このオブジェクトは、前の応答のデータがすべて読み取られるまで接続が再利用できないため、できるだけ早く閉じて接続を解放する必要があります。 :::
- OperationMetrics getMetrics()
- 操作メトリクスを含むオブジェクトを返します
- String getQueryId()
- アプリケーションによって操作に割り当てられたクエリ ID（操作設定またはサーバーによって）を返します。
クエリAPI
query(String sqlQuery)
sqlQueryをそのまま送信します。応答フォーマットはクエリ設定によって設定されます。QueryResponseは、対応するフォーマットのリーダーが消費すべき応答ストリームへの参照を保持します。
シグネチャ
CompletableFuture<QueryResponse> query(String sqlQuery, QuerySettings settings)
CompletableFuture<QueryResponse> query(String sqlQuery)
パラメータ
sqlQuery - 単一のSQLステートメント。クエリはそのままサーバーに送信されます。
settings - リクエスト設定。
戻り値
QueryResponse型のFuture - 結果データセットとサーバサイドのメトリクスなどの追加情報を含みます。データセットを消費した後に応答オブジェクトを閉じる必要があります。
例
final String sql = "select * from " + TABLE_NAME + " where title <> '' limit 10";
// デフォルトフォーマットはRowBinaryWithNamesAndTypesFormatReaderであるため、リーダーはすべてのカラム情報を持っています
try (QueryResponse response = client.query(sql).get(3, TimeUnit.SECONDS);) {
// データに便利にアクセスするためのリーダーを作成
ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);
while (reader.hasNext()) {
reader.next(); // ストリームから次のレコードを読み取り、解析する
// 値を取得
double id = reader.getDouble("id");
String title = reader.getString("title");
String url = reader.getString("url");
// データを収集
}
} catch (Exception e) {
log.error("Failed to read data", e);
}
// ビジネスロジックは可能な限り早くHTTP接続を解放するように、読取りブロックの外に置いてください。
query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)
sqlQueryをそのまま送信します。さらに、クエリパラメータを送信し、サーバーがSQL式をコンパイルできるようにします。
シグネチャ
CompletableFuture<QueryResponse> query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)
パラメータ
sqlQuery - {}を含むSQL式。
queryParams - サーバーでSQL式を完成させるための変数のマップ。
settings - リクエスト設定。
戻り値
QueryResponse型のFuture - 結果データセットとサーバサイドのメトリクスなどの追加情報を含みます。データセットを消費した後に応答オブジェクトを閉じる必要があります。
例
// パラメータを定義。それらはリクエストと一緒にサーバーに送信されます。
Map<String, Object> queryParams = new HashMap<>();
queryParams.put("param1", 2);
try (QueryResponse queryResponse =
client.query("SELECT * FROM " + table + " WHERE col1 >= {param1:UInt32}", queryParams, new QuerySettings()).get()) {
// データに便利にアクセスするためのリーダーを作成
ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);
while (reader.hasNext()) {
reader.next(); // ストリームから次のレコードを読み取り、解析する
// データを読み取る
}
} catch (Exception e) {
log.error("Failed to read data", e);
}
queryAll(String sqlQuery)
RowBinaryWithNamesAndTypes形式でデータをクエリします。結果をコレクションとして返します。読み取りパフォーマンスはリーダーと同じですが、全データセットを保持するためにはより多くのメモリが必要です。
シグネチャ
List<GenericRecord> queryAll(String sqlQuery)
パラメータ
sqlQuery - サーバーからデータをクエリするためのSQL式。
戻り値
結果データを行スタイルでアクセスするためにGenericRecordオブジェクトのリストで表現された完全なデータセットを返します。
例
try {
log.info("テーブル全体を読み取り、レコードごとに処理中");
final String sql = "select * from " + TABLE_NAME + " where title <> ''";
// 完全な結果セットを読み取り、レコードごとに処理
client.queryAll(sql).forEach(row -> {
double id = row.getDouble("id");
String title = row.getString("title");
String url = row.getString("url");
log.info("id: {}, title: {}, url: {}", id, title, url);
});
} catch (Exception e) {
log.error("Failed to read data", e);
}
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を参照してください。
QueryResponse
クエリ実行の結果を保持する応答オブジェクトです。このオブジェクトはサーバーからの応答を受け取った場合にのみ利用可能です。
:::note このオブジェクトは、前の応答のデータが完全に読み込まれるまで接続を再利用できないため、できるだけ早く閉じて接続を解放する必要があります。 :::
- ClickHouseFormat getFormat()
- 応答のデータがエンコードされているフォーマットを返します。
- InputStream getInputStream()
- 指定された形式での非圧縮バイトストリームを返します。
- OperationMetrics getMetrics()
- 操作メトリクスを含むオブジェクトを返します
- String getQueryId()
- アプリケーションによって操作に割り当てられたクエリ ID（操作設定またはサーバーによって）を返します。
- TimeZone getTimeZone()
- 応答でのDate/DateTime型を処理するために使用するタイムゾーンを返します。
例
共通API
getTableSchema(String table)
tableのスキーマを取得します。
シグネチャ
TableSchema getTableSchema(String table)
TableSchema getTableSchema(String table, String database)
パラメータ
table - スキーマデータを取得するためのテーブル名。
database - 対象のテーブルが定義されているデータベース。
戻り値
テーブルカラムのリストを持つTableSchemaオブジェクトを返します。
getTableSchemaFromQuery(String sql)
SQLステートメントからスキーマを取得します。
シグネチャ
TableSchema getTableSchemaFromQuery(String sql)
パラメータ
sql - スキーマを返すべき"SELECT" SQLステートメント。
戻り値
sql式に一致するカラムを持つTableSchemaオブジェクトを返します。
TableSchema
register(Class clazz, TableSchema schema)
Javaクラス用に書き込み/読み込みデータとするSerDeレイヤーをコンパイルします。このメソッドは、ゲッター/セッターペアと対応するカラムのためにシリアライザとデシリアライザを作成します。
カラムの一致はメソッド名からその名前を抽出することで見つけられます。例えば、getFirstNameはカラム first_nameまたはfirstnameに対応します。
シグネチャ
void register(Class<?> clazz, TableSchema schema)
パラメータ
clazz - データの読み書きに使用されるPOJOを表すクラス。
schema - POJOプロパティと一致させるためのデータスキーマ。
例
client.register(ArticleViewEvent.class, client.getTableSchema(TABLE_NAME));
使用例
完全な例のコードは、 example フォルダにリポジトリ内に保存されています：
- client-v2 - 主な例のセット。
- demo-service - Spring Bootアプリケーションでクライアントを使用する方法の例。
- demo-kotlin-service - Ktor (Kotlin) アプリケーションでクライアントを使用する方法の例。