JDBC ドライバー

v0.8+

注記

clickhouse-jdbcは最新のJavaクライアントを使用して標準JDBCインターフェースを実装しています。 パフォーマンスまたは直接アクセスが重要な場合は、最新のJavaクライアントを直接使用することを推奨します。

環境要件

• OpenJDK バージョン 8 以上

セットアップ

Maven

<!-- https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -->
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.9.6</version>
    <classifier>all</classifier>
</dependency>

Gradle (Kotlin)

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation("com.clickhouse:clickhouse-jdbc:0.9.6:all")

Gradle

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation 'com.clickhouse:clickhouse-jdbc:0.9.6:all'

設定

ドライバークラス: com.clickhouse.jdbc.ClickHouseDriver

注記

com.clickhouse.jdbc.ClickHouseDriverは、新旧のJDBC実装に対するファサードクラスです。デフォルトでは新しいJDBC実装が使用されます。 接続プロパティでclickhouse.jdbc.v1プロパティをtrueに設定することにより、古いJDBC実装を使用できます。

com.clickhouse.jdbc.Driver is new JDBC implementation. com.clickhouse.jdbc.DriverV1は旧JDBC実装です。

URL構文: jdbc:(ch|clickhouse)[:<protocol>]://endpoint[:port][/<database>][?param1=value1&param2=value2][#tag1,tag2,...]、例:

• jdbc:clickhouse:http://localhost:8123
• jdbc:clickhouse:https://localhost:8443?ssl=true

URL構文に関して、以下の点に注意してください:

• URL には エンドポイントを 1 つだけ 指定できます
• プロトコルがデフォルトの 'HTTP' でない場合は、明示的に指定する必要があります
• デフォルトの '8123' 以外のポートを使用する場合は、そのポート番号を明示的に指定する必要があります
• ドライバはポート番号からプロトコルを推測しないため、必ずプロトコルを明示的に指定してください
• プロトコルを指定している場合は、ssl パラメータは不要です。

接続プロパティ

主要な設定パラメータはJavaクライアントで定義されています。これらはそのままドライバに渡してください。ドライバには、クライアント設定には含まれない独自のプロパティがあり、以下に記載されています。

ドライバープロパティ:

プロパティ	デフォルト値	説明
disable_frameworks_detection	true	User-Agent に基づいたフレームワーク検出を無効化する
jdbc_ignore_unsupported_values	false	ドライバーの動作に影響しない箇所では SQLFeatureNotSupportedException を抑制します
clickhouse.jdbc.v1	false	新しい JDBC 実装ではなく、旧 JDBC 実装を使用する
default_query_settings	null	クエリ操作に対してデフォルトのクエリ設定を渡せるようにする
jdbc_resultset_auto_close	true	Statement のクローズ時に ResultSet を自動的にクローズします
beta.row_binary_for_simple_insert	false	RowBinary writer ベースの PreparedStatement 実装を使用します。INSERT INTO ... VALUES クエリでのみ使用できます。
jdbc_resultset_auto_close	true	Statement のクローズ時に ResultSet を自動的にクローズします
jdbc_use_max_result_rows	false	サーバープロパティ max_result_rows を使用して、クエリが返す行数を制限できるようにします。有効にすると、ユーザー設定のオーバーフローモードを上書きします。詳細は JavaDoc を参照してください。
jdbc_sql_parser	JAVACC	使用する SQL パーサーを構成します。指定可能な値: ANTLR4, ANTLR4_PARAMS_PARSER, JAVACC。

サーバー設定

すべてのサーバー設定には clickhouse_setting_ のプレフィックスを付ける必要があります（クライアント設定と同様）。

Properties config = new Properties();
config.setProperty("user", "default");
config.setProperty("password", getPassword());

// set server setting
config.put(ClientConfigProperties.serverSetting("allow_experimental_time_time64_type"), "1");

Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", config);

設定例:

Properties properties = new Properties();
properties.setProperty("user", "default");
properties.setProperty("password", getPassword());
properties.setProperty("client_name", "my-app-01"); // when http protocol is used it will be `http_user_agent` in the query log but not `client_name`.

Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties);

以下のJDBC URLと同等になります:

jdbc:ch:http://localhost:8123/?user=default&password=password&client_name=my-app-01 
// credentials shoud be passed in `Properties`. Here it is just for example.

注記: JDBC URLやプロパティをURLエンコードする必要はありません。自動的にエンコードされます。

サポートされるデータ型

JDBCドライバは、基盤となるJavaクライアントと同じデータ形式をサポートしています。

JDBC型マッピング

以下のマッピングが適用されます:

• ResultSet#getObject(columnIndex) メソッドは、対応する Java クラスのオブジェクトを返します（Int8 -> java.lang.Byte、Int16 -> java.lang.Short など）。
• ResultSetMetaData#getColumnType(columnIndex) メソッドは対応する JDBC 型を返します（Int8 -> java.lang.Byte、Int16 -> java.lang.Short など）。

マッピングを変更する方法はいくつかあります:

• ResultSet#getObject(columnIndex, class) - メソッドは値を class 型に変換しようと試みます。この変換にはいくつか制限があります。詳細は各セクションを参照してください。

数値型

ClickHouse型	JDBC型	Javaクラス
Int8	TINYINT	java.lang.Byte
Int16	SMALLINT	java.lang.Short
Int32	INTEGER	java.lang.Integer
Int64	BIGINT	java.lang.Long
Int128	OTHER	java.math.BigInteger
Int256	OTHER	java.math.BigInteger
UInt8	OTHER	java.lang.Short
UInt16	OTHER	java.lang.Integer
UInt32	OTHER	java.lang.Long
UInt64	OTHER	java.math.BigInteger
UInt128	OTHER	java.math.BigInteger
UInt256	OTHER	java.math.BigInteger
Float32	REAL	java.lang.Float
Float64	DOUBLE	java.lang.Double
Decimal32	DECIMAL	java.math.BigDecimal
Decimal64	DECIMAL	java.math.BigDecimal
Decimal128	DECIMAL	java.math.BigDecimal
Decimal256	DECIMAL	java.math.BigDecimal
Bool	BOOLEAN	java.lang.Boolean

• 数値型は相互に変換可能です。そのため、Int8 を Float64 として取得したり、その逆も可能です:
  • rs.getObject(1, Float64.class) は、Int8 カラムの値を Float64 型の値として返します。
  • rs.getLong(1) は、Int8 カラムの値を Long 型の値として返します。
  • rs.getByte(1) は、Int16 カラムの値が Byte の範囲に収まる場合、その値を Byte 型の値として返します。
• より広い型からより狭い型への変換は、データ破損のリスクがあるため推奨されません。
• Bool 型も数値型として扱うことができます。
• すべての数値型は java.lang.String として読み出すことができます。

文字列型

ClickHouse型	JDBC型	Javaクラス
String	VARCHAR	java.lang.String
FixedString	VARCHAR	java.lang.String

• String は java.lang.String 型または byte[] 型としてのみ取得できます。
• FixedString はそのまま読み出されますが、不足分はカラムの長さに達するまでゼロバイト（\0）でパディングされます。（たとえば、FixedString(10) で 'John' を指定した場合、'John\0\0\0\0\0\0\0\0\0' として読み取られます。）

Enum型

ClickHouse型	JDBC型	Javaクラス
Enum8	OTHER	java.lang.String
Enum16	OTHER	java.lang.String

• Enum8 および Enum16 は、デフォルトで java.lang.String にマッピングされます。
• Enum の値は、対応する getter メソッドまたは getObject(columnIndex, Integer.class) メソッドを使用して数値として読み取ることができます。
• Enum16 は内部的に short にマッピングされ、Enum8 は byte にマッピングされます。Enum16 を byte として読み取ることは、データ破損のリスクがあるため避けるべきです。
• Enum の値は文字列または数値として PreparedStatement に設定できます。

日付/時刻型

ClickHouse 型	JDBC 型	Java クラス
Date	DATE	java.sql.Date
Date32	DATE	java.sql.Date
DateTime	TIMESTAMP	java.sql.Timestamp
DateTime64	TIMESTAMP	java.sql.Timestamp
Time	TIME	java.sql.Time
Time64	TIME	java.sql.Time

• 日付／時刻型は、JDBC との互換性を高めるために java.sql 型へマッピングされます。ただし、ResultSet#getObject(columnIndex, Class<T>) の第 2 引数に対応するクラスを指定することで、java.time.LocalDate、java.time.LocalDateTime、java.time.LocalTime を取得することもできます。
  • rs.getObject(1, java.time.LocalDate.class) は、Date カラムの java.time.LocalDate 型の値を返します。
  • rs.getObject(1, java.time.LocalDateTime.class) は、DateTime カラムの java.time.LocalDateTime 型の値を返します。
  • rs.getObject(1, java.time.LocalTime.class) は、Time カラムの java.time.LocalTime 型の値を返します。
• Date, Date32, Time, Time64 はサーバーのタイムゾーン設定の影響を受けません。
• DateTime、DateTime64 はサーバーまたはセッションのタイムゾーンの影響を受けます。
• DateTime および DateTime64 は、getObject(colIndex, ZonedDateTime.class) を使用することで ZonedDateTime として取得できます。

コレクション型

ClickHouse 型	JDBC 型	Java クラス
Array	ARRAY	java.sql.Array
Tuple	OTHER	Object[]
Map	JAVA_OBJECT	java.util.Map

• Array は、JDBC との互換性を保つため、デフォルトでは java.sql.Array にマッピングされます。これは、返される配列値に関する情報をより詳細に持たせるためでもあり、型推論に役立ちます。
• Array は getResultSet() メソッドを実装しており、元の配列と同一の内容を持つ java.sql.ResultSet を返します。
• コレクション型は java.lang.String として読み取ってはいけません。これはデータを表現する適切な方法ではないためです（例: 配列内の文字列値に引用符が付与されないなど）。
• Map は、値は getObject(columnIndex, Class<T>) メソッドでのみ読み取ることができるため、JAVA_OBJECT にマッピングされます。
  • Map は名前付きカラムを持たないため、java.sql.Struct ではありません。
• Tuple は異なる型を含み得るため、List を使うのは適切ではなく、Object[] にマッピングされます。
• Tuple は getObject(columnIndex, Array.class) メソッドを使用することで Array として取得できます。この場合、Array#baseTypeName は Tuple 型カラムの定義を返します。

地理型

ClickHouse 型	JDBC 型	Java クラス
Point	OTHER	double[]
Ring	OTHER	double[][]
Polygon	OTHER	double[][][]
MultiPolygon	OTHER	double[][][][]

Nullable型とLowCardinality型

• Nullable と LowCardinality は、他の型をラップする特殊な型です。
• Nullable は、ResultSetMetaData での型名の返され方に影響します。

特殊型

ClickHouse 型	JDBC 型	Java クラス
UUID	OTHER	java.util.UUID
IPv4	OTHER	java.net.Inet4Address
IPv6	OTHER	java.net.Inet6Address
JSON	OTHER	java.lang.String
AggregateFunction	OTHER	（バイナリ表現）
SimpleAggregateFunction	（ラップされた型）	（ラップされたクラス）

• UUID は JDBC の標準型ではありませんが、JDK の一部です。デフォルトでは、getObject() メソッドで java.util.UUID が返されます。
• UUID は、getObject(columnIndex, String.class) メソッドを使用することで、String 型として読み取りおよび書き込みができます。
• IPv4 と IPv6 は JDBC 標準の型ではありません。ただし、JDK の一部です。デフォルトでは、getObject() メソッドで java.net.Inet4Address と java.net.Inet6Address が返されます。
• getObject(columnIndex, String.class) メソッドを使用すると、IPv4 と IPv6 を String として読み書きできます。

日付、時刻、タイムゾーンの処理

java.sql.Date、java.sql.Time、および java.sql.Timestamp はタイムゾーンの計算を複雑にする可能性があります。これらはもちろんサポートされていますが、 java.time パッケージの使用を検討してください。ZonedDateTime および OffsetDateTime は、java.sql.Timestamp、java.sql.Date、java.sql.Time の優れた代替手段です。

Date vs DateTime

Date はタイムゾーンなしで保存されますが、DateTime はタイムゾーン付きで保存されます。注意を怠ると予期しない結果を招く可能性があります。

接続の作成

String url = "jdbc:ch://my-server:8123/system";

Properties properties = new Properties();
DataSource dataSource = new DataSource(url, properties);//DataSource or DriverManager are the main entry points
try (Connection conn = dataSource.getConnection()) {
... // do something with the connection

認証情報と設定の指定

String url = "jdbc:ch://localhost:8123?jdbc_ignore_unsupported_values=true&socket_timeout=10";

Properties info = new Properties();
info.put("user", "default");
info.put("password", "password");
info.put("database", "some_db");

//Creating a connection with DataSource
DataSource dataSource = new DataSource(url, info);
try (Connection conn = dataSource.getConnection()) {
... // do something with the connection
}

//Alternate approach using the DriverManager
try (Connection conn = DriverManager.getConnection(url, info)) {
... // do something with the connection
}

単純なステートメント

try (Connection conn = dataSource.getConnection(...);
    Statement stmt = conn.createStatement()) {
    ResultSet rs = stmt.executeQuery("select * from numbers(50000)");
    while(rs.next()) {
        // ...
    }
}

Insert

try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable VALUES (?, ?)")) {
    ps.setString(1, "test"); // id
    ps.setObject(2, LocalDateTime.now()); // timestamp
    ps.addBatch();
    ...
    ps.executeBatch(); // stream everything on-hand into ClickHouse
}

HikariCP

// connection pooling won't help much in terms of performance,
// because the underlying implementation has its own pool.
// for example: HttpURLConnection has a pool for sockets
HikariConfig poolConfig = new HikariConfig();
poolConfig.setConnectionTimeout(5000L);
poolConfig.setMaximumPoolSize(20);
poolConfig.setMaxLifetime(300_000L);
poolConfig.setDataSource(new ClickHouseDataSource(url, properties));

try (HikariDataSource ds = new HikariDataSource(poolConfig);
     Connection conn = ds.getConnection();
     Statement s = conn.createStatement();
     ResultSet rs = s.executeQuery("SELECT * FROM system.numbers LIMIT 3")) {
    while (rs.next()) {
        // handle row
        log.info("Integer: {}, String: {}", rs.getInt(1), rs.getString(1));//Same column but different types
    }
}

詳細情報

詳細については、GitHubリポジトリおよびJavaクライアントのドキュメントを参照してください。

トラブルシューティング

ログ

このドライバはログ記録に slf4j を使用し、classpath 上で最初に利用可能な実装を使用します。

大量挿入時のJDBCタイムアウトの解決

ClickHouseで実行時間の長い大規模なインサート処理を実行する際、次のようなJDBCタイムアウトエラーが発生することがあります:

Caused by: java.sql.SQLException: Read timed out, server myHostname [uri=https://hostname.aws.clickhouse.cloud:8443]

これらのエラーはデータ挿入プロセスを中断し、システムの安定性に影響を与える可能性があります。この問題に対処するには、クライアントOS上のいくつかのタイムアウト設定を調整する必要がある場合があります。

macOS

macOSでは、以下の設定を調整することで問題を解決できます:

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1

Linux

Linuxでは、同等の設定のみでは問題が解決しない場合があります。Linuxにおけるソケットキープアライブ設定の処理方法の違いにより、追加の手順が必要です。以下の手順に従ってください:

1. /etc/sysctl.conf または関連する設定ファイルで、次の Linux カーネルパラメータを調整します:

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1
• net.ipv4.tcp_keepalive_intvl: 75
• net.ipv4.tcp_keepalive_probes: 9
• net.ipv4.tcp_keepalive_time: 60（この値をデフォルトの 300 秒から引き下げることを検討してもよいでしょう）

2. カーネルパラメータを変更したら、以下のコマンドを実行して変更を適用します。

sudo sysctl -p

これらの設定を行った後、クライアントがソケット上でKeep Aliveオプションを有効にしていることを確認する必要があります:

properties.setProperty("socket_keepalive", "true");

移行ガイド

主な変更点

機能	V1（旧）	V2（新）
トランザクション対応	一部サポートあり	サポートなし
レスポンスのカラム名の変更	一部サポートあり	サポートなし
複数文 SQL	サポートなし	利用不可
名前付きパラメーター	サポートあり	サポートなし（JDBC 仕様に準拠していないため）
PreparedStatement を用いたデータストリーミング	サポートあり	サポートなし

• JDBC V2 はより軽量な実装として設計されており、その分一部の機能が削除されています。
  • ストリーミングデータは JDBC 仕様および Java の仕様には含まれていないため、JDBC V2 ではサポートされていません。
• JDBC V2 では明示的な構成が必要です。フェイルオーバー用のデフォルト設定はありません。
  • プロトコルは URL で明示的に指定する必要があります。ポート番号に基づく暗黙的なプロトコル判別は行われません。

設定の変更

列挙型は2つのみです:

• com.clickhouse.jdbc.DriverProperties - ドライバー固有の設定プロパティです。
• com.clickhouse.client.api.ClientConfigProperties - クライアントの構成プロパティを表します。クライアント構成の変更については、Java クライアントのドキュメントを参照してください。

接続プロパティは次のように解析されます:

• URL はまずプロパティとして解析され、その指定内容が他のすべてのプロパティより優先されます。
• ドライバーのプロパティはクライアント側に渡されません。
• エンドポイント（ホスト、ポート、プロトコル）は URL から解析されます。

例:

String url = "jdbc:ch://my-server:8443/default?" +
            "jdbc_ignore_unsupported_values=true&" +
            "socket_rcvbuf=800000";

Properties properties = new Properties();
properties.setProperty("socket_rcvbuf", "900000");
try (Connection conn = DriverManager.getConnection(url, properties)) {
    // Connection will use socket_rcvbuf=800000 and jdbc_ignore_unsupported_values=true
    // Endpoints: my-server:8443 protocol: http (not secure)
    // Database: default
}

データ型の変更

数値型

ClickHouse 型	V1 との互換性	JDBC 型 (V2)	Java クラス (V2)	JDBC 型 (V1)	Java クラス (V1)
Int8	✅	TINYINT	java.lang.Byte	TINYINT	java.lang.Byte
Int16	✅	SMALLINT	java.lang.Short	SMALLINT	java.lang.Short
Int32	✅	INTEGER	java.lang.Integer	INTEGER	java.lang.Integer
Int64	✅	BIGINT	java.lang.Long	BIGINT	java.lang.Long
Int128	✅	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
Int256	✅	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
UInt8	❌	OTHER	java.lang.Short	OTHER	com.clickhouse.data.value.UnsignedByte
UInt16	❌	OTHER	java.lang.Integer	OTHER	com.clickhouse.data.value.UnsignedShort
UInt32	❌	OTHER	java.lang.Long	OTHER	com.clickhouse.data.value.UnsignedInteger
UInt64	❌	OTHER	java.math.BigInteger	OTHER	com.clickhouse.data.value.UnsignedLong
UInt128	✅	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
UInt256	✅	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
Float32	✅	REAL	java.lang.Float	REAL	java.lang.Float
Float64	✅	DOUBLE	java.lang.Double	DOUBLE	java.lang.Double
Decimal32	✅	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Decimal64	✅	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Decimal128	✅	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Decimal256	✅	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Bool	✅	BOOLEAN	java.lang.Boolean	BOOLEAN	java.lang.Boolean

• 最大の違いは、ポータビリティを高めるために符号なし型が標準的な Java 型にマッピングされる点です。

文字列型

ClickHouse 型	V1 との互換性	JDBC 型 (V2)	Java クラス (V2)	JDBC 型 (V1)	Java クラス (V1)
String	✅	VARCHAR	java.lang.String	VARCHAR	java.lang.String
FixedString	✅	VARCHAR	java.lang.String	VARCHAR	java.lang.String

• FixedString は両方のバージョンで、そのままの値として読み取られます。たとえば 'John' に対する FixedString(10) は 'John\0\0\0\0\0\0\0\0\0' として読み込まれます。
• PreparedStatement#setBytes が使用されると、unhex('<hex_string>') に変換され、その後 String 型として扱われます。

日付/時刻型

ClickHouse 型	変更有無	JDBC 型 (V2)	Java クラス (V2)	JDBC 型 (V1)	Java クラス (V1)
Date	❌	DATE	java.sql.Date	DATE	java.time.LocalDate
Date32	❌	DATE	java.sql.Date	DATE	java.time.LocalDate
DateTime	❌	TIMESTAMP	java.sql.Timestamp	TIMESTAMP	java.time.OffsetDateTime
DateTime64	❌	TIMESTAMP	java.sql.Timestamp	TIMESTAMP	java.time.OffsetDateTime
Time	✅	TIME	java.sql.Time	新しい型/サポート対象外	新しい型/サポート対象外
Time64	✅	TIME	java.sql.Time	新しい型/サポート対象外	新しい型/サポート対象外

• Time と Time64 は、新しい型として V2 でのみサポートされています。
• DateTime と DateTime64 は、JDBC との互換性を高めるために java.sql.Timestamp にマッピングされます。

Enum型

ClickHouse 型	V1 との互換性	JDBC 型 (V2)	Java クラス (V2)	JDBC 型 (V1)	Java クラス (V1)
Enum	✅	VARCHAR	java.lang.String	OTHER	java.lang.String
Enum8	✅	VARCHAR	java.lang.String	OTHER	java.lang.String
Enum16	✅	VARCHAR	java.lang.String	OTHER	java.lang.String

コレクション型

ClickHouse 型	V1 との互換性	JDBC 型 (V2)	Java クラス (V2)	JDBC 型 (V1)	Java クラス (V1)
Array	❌	ARRAY	java.sql.Array	ARRAY	Object[] またはプリミティブ型の配列
Tuple	❌	OTHER	Object[]	STRUCT	java.sql.Struct
Map	❌	JAVA_OBJECT	java.util.Map	STRUCT	java.util.Map

• V2 では、Array は JDBC との互換性を維持するため、デフォルトで java.sql.Array にマッピングされます。これは、返却される配列値に関する情報をより多く提供し、型推論に役立てるためでもあります。
• V2 では Array が getResultSet() メソッドを実装し、元の配列と同一の内容を持つ java.sql.ResultSet を返します。
• V1 は Map に対して STRUCT を使用しますが、常に java.util.Map オブジェクトを返します。V2 では、Map を JAVA_OBJECT にマッピングすることでこの問題を解消しています。そもそも Map には名前付きカラムが存在しないため、STRUCT は Map に対して無効です。
• V1 は Tuple に対して STRUCT を使用しますが、常に List<Object> オブジェクトを返します。V2 では Tuple を OTHER にマッピングし、Object[] を返すことでこの問題を修正しています。これは、要素として異なる型が含まれ得るため、List を使用するのは妥当ではないためです。
• PreparedStatement#setBytes と ResultSet#getBytes はコレクション型では使用できません。これらのメソッドはバイナリ文字列を扱うために設計されています。
• 通常、Array 型の読み書きには java.sql.Array が使われます。JDBC ドライバはこれを完全にサポートしています。

地理型

ClickHouse 型	V1 との互換性	JDBC 型 (V2)	Java クラス (V2)	JDBC 型 (V1)	Java クラス (V1)
Point	✅	OTHER	double[]	OTHER	double[]
Ring	✅	OTHER	double[][]	OTHER	double[][]
Polygon	✅	OTHER	double[][][]	OTHER	double[][][]
MultiPolygon	✅	OTHER	double[][][][]	OTHER	double[][][][]

Nullable型とLowCardinality型

• Nullable と LowCardinality は、他の型をラップする特殊な型です。
• V2 でもこれらの型には変更はありません。

特殊型

ClickHouse 型	V1 との互換性	JDBC 型 (V2)	Java クラス (V2)	JDBC 型 (V1)	Java クラス (V1)
JSON	❌	OTHER	java.lang.String	サポートなし	サポートなし
AggregateFunction	✅	OTHER	（バイナリ表現）	OTHER	（バイナリ表現）
SimpleAggregateFunction	✅	（ラップされた型）	（ラップされたクラス）	（ラップされた型）	（ラップされたクラス）
UUID	✅	OTHER	java.util.UUID	VARCHAR	java.util.UUID
IPv4	✅	OTHER	java.net.Inet4Address	VARCHAR	java.net.Inet4Address
IPv6	✅	OTHER	java.net.Inet6Address	VARCHAR	java.net.Inet6Address
Dynamic	❌	OTHER	java.Object	サポートなし	サポートなし
Variant	❌	OTHER	java.Object	サポートなし	サポートなし

• V1 は UUID に対して VARCHAR を使用しますが、常に java.util.UUID オブジェクトを返します。V2 では、UUID を OTHER にマッピングすることでこの問題を解消し、java.util.UUID オブジェクトを返します。
• V1 では IPv4 と IPv6 に対して VARCHAR を使用しますが、戻り値は常に java.net.Inet4Address および java.net.Inet6Address オブジェクトです。V2 では、IPv4 と IPv6 を OTHER にマッピングすることでこの問題を解消し、java.net.Inet4Address および java.net.Inet6Address オブジェクトを返します。
• Dynamic と Variant は V2 で導入された新しい型です。V1 ではサポートされていません。
• JSON は Dynamic 型に基づくため、V2 でのみサポートされています。
• IPv4およびIPv6の値は、getBytes(columnIndex) メソッドを使用して byte[] として読み取ることもできます。ただし、これらの型については専用クラスの使用を推奨します。
• V2 では、IP アドレスを数値として読み取ることはサポートされていません。これは、その変換は InetAddress クラスによる実装の方が適切と判断されているためです。

データベースメタデータの変更

• V2 ではデータベースの名称として Schema という用語のみを使用します。Catalog という用語は今後の利用のために予約されています。
• V2 は DatabaseMetaData.supportsTransactions() および DatabaseMetaData.supportsSavepoints() に対して false を返します。これは今後の開発で変更される予定です。

clickhouse-jdbcは標準のJDBCインターフェースを実装しています。clickhouse-client上に構築されており、カスタム型マッピング、トランザクションサポート、標準的な同期UPDATEおよびDELETE文などの追加機能を提供するため、レガシーアプリケーションやツールと容易に使用できます。

注記

最新のJDBC（0.7.2）バージョンはClient-V1を使用しています

clickhouse-jdbc APIは同期的であり、一般的にはより多くのオーバーヘッド(例:SQLの解析や型のマッピング/変換など)が発生します。パフォーマンスが重要な場合、またはClickHouseへのより直接的なアクセス方法を希望する場合は、clickhouse-clientの使用を検討してください。

環境要件

• OpenJDK バージョン 8 以上

セットアップ

Maven

<!-- https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -->
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.7.2</version>
    <!-- すべての依存関係を含む Uber JAR を使用します。JAR を小さくするには classifier を http に変更してください -->
    <classifier>shaded-all</classifier>
</dependency>

Gradle (Kotlin)

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
// すべての依存関係を含む Uber JAR を使用します。JAR を小さくするには classifier を http に変更してください
implementation("com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all")

Gradle

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
// すべての依存関係を含む Uber JAR を使用します。JAR を小さくするには classifier を http に変更してください
implementation 'com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all'

バージョン 0.5.0 以降、クライアントにバンドルされた Apache HTTP Client を使用しています。このパッケージには共有バージョンが存在しないため、ロガーを依存関係として追加する必要があります。

Maven

<!-- https://mvnrepository.com/artifact/org.slf4j/slf4j-api -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.16</version>
</dependency>

Gradle (Kotlin)

// https://mvnrepository.com/artifact/org.slf4j/slf4j-api
implementation("org.slf4j:slf4j-api:2.0.16")

Gradle

// https://mvnrepository.com/artifact/org.slf4j/slf4j-api
implementation 'org.slf4j:slf4j-api:2.0.16'

設定

ドライバークラス: com.clickhouse.jdbc.ClickHouseDriver

URL構文: jdbc:(ch|clickhouse)[:<protocol>]://endpoint1[,endpoint2,...][/<database>][?param1=value1&param2=value2][#tag1,tag2,...]、例:

• jdbc:ch://localhost は jdbc:clickhouse:http://localhost:8123 と同じです。
• jdbc:ch:https://localhost は jdbc:clickhouse:http://localhost:8443?ssl=true&sslmode=STRICT と同等です。
• jdbc:ch:grpc://localhost は jdbc:clickhouse:grpc://localhost:9100 と同じです。

接続プロパティ:

プロパティ	デフォルト値	説明
continueBatchOnError	false	エラー発生時にバッチ処理を継続するかどうか
createDatabaseIfNotExist	false	データベースが存在しない場合に自動作成するかどうか
custom_http_headers		カンマ区切りで指定するカスタム HTTP ヘッダー。例：User-Agent=client1,X-Gateway-Id=123
custom_http_params		カンマ区切りのカスタム HTTP クエリパラメータ。例: extremes=0,max_result_rows=100
nullAsDefault	0	0 - null 値をそのまま扱い、null 非許容カラムに null を挿入しようとした場合は例外をスローする; 1 - null 値をそのまま扱い、挿入時の null チェックを無効化する; 2 - クエリおよび挿入の両方で、null を対応するデータ型のデフォルト値に置き換える
jdbcCompliance	true	標準的な同期 UPDATE/DELETE と疑似トランザクションをサポートするかどうか
typeMappings		ClickHouse データ型と Java クラスの対応付けをカスタマイズします。これは、getColumnType() と getObject(Class<>?>) の両方の結果に影響します。例：UInt128=java.lang.String,UInt256=java.lang.String
wrapperObject	false	getObject() が Array / Tuple 型に対して java.sql.Array / java.sql.Struct を返すかどうかを指定します。

注記: 詳細についてはJDBC固有の設定を参照してください。

サポートされるデータ型

JDBCドライバは、クライアントライブラリと同じデータ形式をサポートしています。

注記

• AggregatedFunction - ⚠️ SELECT * FROM table ... はサポートされません
• 10進数 - 一貫性を保つため、21.9 以降では SET output_format_decimal_trailing_zeros=1 を設定します
• Enum - 文字列型および整数型の両方として扱える
• UInt64 - client-v1 では long にマッピングされます

接続の作成

String url = "jdbc:ch://my-server/system"; // use http protocol and port 8123 by default

Properties properties = new Properties();

ClickHouseDataSource dataSource = new ClickHouseDataSource(url, properties);
try (Connection conn = dataSource.getConnection("default", "password");
    Statement stmt = conn.createStatement()) {
}

単純なステートメント

try (Connection conn = dataSource.getConnection(...);
    Statement stmt = conn.createStatement()) {
    ResultSet rs = stmt.executeQuery("select * from numbers(50000)");
    while(rs.next()) {
        // ...
    }
}

Insert

注記

• Statement ではなく PreparedStatement を使用してください

使用は容易ですが、input関数と比較してパフォーマンスが劣ります(以下を参照):

try (PreparedStatement ps = conn.prepareStatement("insert into mytable(* except (description))")) {
    ps.setString(1, "test"); // id
    ps.setObject(2, LocalDateTime.now()); // timestamp
    ps.addBatch(); // parameters will be write into buffered stream immediately in binary format
    ...
    ps.executeBatch(); // stream everything on-hand into ClickHouse
}

inputテーブル関数を使用する

高いパフォーマンス特性を持つオプション:

try (PreparedStatement ps = conn.prepareStatement(
    "insert into mytable select col1, col2 from input('col1 String, col2 DateTime64(3), col3 Int32')")) {
    // The column definition will be parsed so the driver knows there are 3 parameters: col1, col2 and col3
    ps.setString(1, "test"); // col1
    ps.setObject(2, LocalDateTime.now()); // col2, setTimestamp is slow and not recommended
    ps.setInt(3, 123); // col3
    ps.addBatch(); // parameters will be write into buffered stream immediately in binary format
    ...
    ps.executeBatch(); // stream everything on-hand into ClickHouse
}

• 可能な限り input 関数のドキュメント を参照してください

プレースホルダーを使用した挿入

このオプションは小規模な挿入にのみ推奨されます。長いSQL式が必要となり、クライアント側で解析されてCPUとメモリを消費するためです:

try (PreparedStatement ps = conn.prepareStatement("insert into mytable values(trim(?),?,?)")) {
    ps.setString(1, "test"); // id
    ps.setObject(2, LocalDateTime.now()); // timestamp
    ps.setString(3, null); // description
    ps.addBatch(); // append parameters to the query
    ...
    ps.executeBatch(); // issue the composed query: insert into mytable values(...)(...)...(...)
}

DateTimeとタイムゾーンの取り扱い

java.sql.Timestampの代わりにjava.time.LocalDateTimeまたはjava.time.OffsetDateTimeを、java.sql.Dateの代わりにjava.time.LocalDateを使用してください。

try (PreparedStatement ps = conn.prepareStatement("select date_time from mytable where date_time > ?")) {
    ps.setObject(2, LocalDateTime.now());
    ResultSet rs = ps.executeQuery();
    while(rs.next()) {
        LocalDateTime dateTime = (LocalDateTime) rs.getObject(1);
    }
    ...
}

AggregateFunctionの取り扱い

注記

現時点では、groupBitmap のみサポートされています。

// batch insert using input function
try (ClickHouseConnection conn = newConnection(props);
        Statement s = conn.createStatement();
        PreparedStatement stmt = conn.prepareStatement(
                "insert into test_batch_input select id, name, value from input('id Int32, name Nullable(String), desc Nullable(String), value AggregateFunction(groupBitmap, UInt32)')")) {
    s.execute("drop table if exists test_batch_input;"
            + "create table test_batch_input(id Int32, name Nullable(String), value AggregateFunction(groupBitmap, UInt32))engine=Memory");
    Object[][] objs = new Object[][] {
            new Object[] { 1, "a", "aaaaa", ClickHouseBitmap.wrap(1, 2, 3, 4, 5) },
            new Object[] { 2, "b", null, ClickHouseBitmap.wrap(6, 7, 8, 9, 10) },
            new Object[] { 3, null, "33333", ClickHouseBitmap.wrap(11, 12, 13) }
    };
    for (Object[] v : objs) {
        stmt.setInt(1, (int) v[0]);
        stmt.setString(2, (String) v[1]);
        stmt.setString(3, (String) v[2]);
        stmt.setObject(4, v[3]);
        stmt.addBatch();
    }
    int[] results = stmt.executeBatch();
    ...
}

// use bitmap as query parameter
try (PreparedStatement stmt = conn.prepareStatement(
    "SELECT bitmapContains(my_bitmap, toUInt32(1)) as v1, bitmapContains(my_bitmap, toUInt32(2)) as v2 from {tt 'ext_table'}")) {
    stmt.setObject(1, ClickHouseExternalTable.builder().name("ext_table")
            .columns("my_bitmap AggregateFunction(groupBitmap,UInt32)").format(ClickHouseFormat.RowBinary)
            .content(new ByteArrayInputStream(ClickHouseBitmap.wrap(1, 3, 5).toBytes()))
            .asTempTable()
            .build());
    ResultSet rs = stmt.executeQuery();
    Assert.assertTrue(rs.next());
    Assert.assertEquals(rs.getInt(1), 1);
    Assert.assertEquals(rs.getInt(2), 0);
    Assert.assertFalse(rs.next());
}

HTTPライブラリの設定

ClickHouse JDBCコネクタは、以下の3つのHTTPライブラリをサポートしています:HttpClient、HttpURLConnection、およびApache HttpClient。

注記

HttpClient は JDK 11 以降でのみサポートされています。

JDBCドライバーはデフォルトでHttpClientを使用します。以下のプロパティを設定することで、ClickHouse JDBCコネクタが使用するHTTPライブラリを変更できます:

properties.setProperty("http_connection_provider", "APACHE_HTTP_CLIENT");

対応する値の一覧は以下の通りです:

プロパティ値	HTTPライブラリ
HTTP_CLIENT	HttpClient
HTTP_URL_CONNECTION	HttpURLConnection
APACHE_HTTP_CLIENT	Apache HttpClient

SSLでClickHouseに接続する

SSLを使用してClickHouseへの安全なJDBC接続を確立するには、JDBCプロパティにSSLパラメータを含めるよう設定する必要があります。通常、JDBC URLまたはPropertiesオブジェクトにsslmodeやsslrootcertなどのSSLプロパティを指定します。

SSLプロパティ

名前	デフォルト値	指定可能な値	説明
ssl	false	true, false	接続で SSL/TLS を有効にするかどうか
sslmode	strict	strict, none	サーバーの SSL/TLS 証明書を検証するかどうか
sslrootcert			SSL/TLS ルート証明書ファイルへのパス
sslcert			SSL/TLS 証明書ファイルへのパス
sslkey			PKCS#8 形式の RSA 鍵
key_store_type		JKS, PKCS12	KeyStore/TrustStore ファイルの種類または形式を指定します
trust_store			TrustStore ファイルへのパス
key_store_password			KeyStore 設定で指定された KeyStore ファイルへアクセスする際に必要なパスワード

これらのプロパティにより、JavaアプリケーションがClickHouseサーバーと暗号化接続で通信することが保証され、転送中のデータセキュリティが向上します。

  String url = "jdbc:ch://your-server:8443/system";

  Properties properties = new Properties();
  properties.setProperty("ssl", "true");
  properties.setProperty("sslmode", "strict"); // NONE to trust all servers; STRICT for trusted only
  properties.setProperty("sslrootcert", "/mine.crt");
  try (Connection con = DriverManager
          .getConnection(url, properties)) {

      try (PreparedStatement stmt = con.prepareStatement(

          // place your code here

      }
  }

大量挿入時のJDBCタイムアウトの解決

ClickHouseで実行時間の長い大規模なインサート処理を実行する際、次のようなJDBCタイムアウトエラーが発生することがあります:

Caused by: java.sql.SQLException: Read timed out, server myHostname [uri=https://hostname.aws.clickhouse.cloud:8443]

これらのエラーはデータ挿入プロセスを中断し、システムの安定性に影響を与える可能性があります。この問題に対処するには、クライアントOS上のいくつかのタイムアウト設定を調整する必要があります。

macOS

macOSでは、以下の設定を調整することで問題を解決できます:

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1

Linux

Linuxでは、同等の設定のみでは問題が解決しない場合があります。Linuxにおけるソケットキープアライブ設定の処理方法の違いにより、追加の手順が必要です。以下の手順に従ってください:

1. /etc/sysctl.conf または関連する設定ファイルで、以下の Linux カーネルパラメータを調整します：

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1
• net.ipv4.tcp_keepalive_intvl: 75
• net.ipv4.tcp_keepalive_probes: 9
• net.ipv4.tcp_keepalive_time: 60（デフォルトの 300 秒から値を下げることも検討できます）

2. カーネルパラメーターを変更したら、次のコマンドを実行して変更を適用します:

sudo sysctl -p

これらの設定を行った後、クライアントがソケット上でKeep Aliveオプションを有効にしていることを確認する必要があります:

properties.setProperty("socket_keepalive", "true");

注記

現在、ソケットのキープアライブを設定する際は、Apache HTTP Clientライブラリを使用する必要があります。clickhouse-javaがサポートする他の2つのHTTPクライアントライブラリでは、ソケットオプションの設定が許可されていないためです。詳細なガイドについては、HTTPライブラリの設定を参照してください。

または、JDBC URLに同等のパラメータを追加することもできます。

JDBCドライバーのデフォルトのソケットおよび接続タイムアウトは30秒です。大規模なデータ挿入操作をサポートするために、タイムアウトを延長できます。ClickHouseClientのoptionsメソッドを使用し、ClickHouseClientOptionで定義されているSOCKET_TIMEOUTおよびCONNECTION_TIMEOUTオプションを指定してください:

final int MS_12H = 12 * 60 * 60 * 1000; // 12 h in ms
final String sql = "insert into table_a (c1, c2, c3) select c1, c2, c3 from table_b;";

try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP)) {
    client.read(servers).write()
        .option(ClickHouseClientOption.SOCKET_TIMEOUT, MS_12H)
        .option(ClickHouseClientOption.CONNECTION_TIMEOUT, MS_12H)
        .query(sql)
        .executeAndWait();
}