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'

クラスパスに jar を追加する必要があるアプリケーションで JDBC ドライバーを使用している場合は、次の場所から jar をダウンロードしてクラスパスに追加する必要があります：

• Maven Central からダウンロードし、クラスパスに追加します
  • バージョン 0.9.4 以降は、アーティファクト https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc-all が利用可能です。
  • すべての shaded 依存関係を含む JAR を取得するには、修飾子 all を指定してください。
• または公式リポジトリのこちらからダウンロードできます

設定

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

注記

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

com.clickhouse.jdbc.Driver は新しい JDBC 実装です。 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 エンコードする必要はありません。自動的にエンコードされます。

クライアント識別

リクエストの発信元アプリケーションを識別する方法は2つあります：接続プロパティで com.clickhouse.client.api.ClientConfigProperties#CLIENT_NAME を設定するか、java.sql.Connection#setClientInfo(String name, String value) メソッドを使用してください。

Properties properties = new Properties();
properties.setProperty(ClientConfigProperties.CLIENT_NAME.getKey(), "my-app-01");
Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties);

conn.setClientInfo(com.clickhouse.jdbc.ClientInfoProperties.APPLICATION_NAME.getKey(), "my-app-01");

どちらの方法でも、クエリログの http_user_agent の値は以下のようになります:

my-app-01/1.0 clickhouse-java-v2/0.9.6-SNAPSHOT (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4

操作の識別

JDBCドライバーは各操作に対して query_id を生成します（現時点では、サーバー例外に含まれています）。

操作に対して log_comment を設定するには、com.clickhouse.jdbc.StatementImpl#getLocalSettings メソッドを使用します。これには、 Statement または PreparedStatement を事前に com.clickhouse.jdbc.StatementImpl にキャストする必要があります。

StatementImpl stmt = (StatementImpl) conn.createStatement();
stmt.getLocalSettings().logComment("some-comment");

注意: localSettings はスレッド間で共有されるため、このアプローチはステートメントのシングルスレッド使用にのみ有効です。

サポートされるデータ型

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 として取得したり、その逆に Float64 を Int8 として取得することも可能です。
  • 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

• Date / 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	com.clickhouse.data.Tuple
Map	JAVA_OBJECT	java.util.Map
Nested	ARRAY	java.sql.Array

• 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 は異なる型の要素を含めることができるため Object[] にマッピングされており、List を使用することは妥当ではありません。
• Tuple は getObject(columnIndex, Array.class) メソッドを使用することで Array として読み取ることができます。この場合、Array#baseTypeName は Tuple カラムの定義を返します。

配列の書き込み

java.sql.Connection#createArrayOf を使用して java.sql.Array オブジェクトをインスタンス化してください。このオブジェクトは、異なるデータベース間で配列の扱いを統一するために設計されています。 Array のファクトリメソッドに設定を渡すには、Connection オブジェクトが必要です。

このメソッドは 2 つの引数を受け取ります：

• typeName - 配列要素の型名。たとえば Array(Int32) -> "Int32"。
• elements - 配列の実際の要素。例えば [[1, 2, 3], [4, 5, 6]] -> new Integer[][] {{1, 2, 3}, {4, 5, 6}}。

Tuple は Object[] または java.sql.Struct として表現できます（タプルの書き込み方法については以下を参照してください）。

例

try (Connection conn = ...) {
    Array array = conn.createArrayOf("Int32", new Integer[][] {{1, 2, 3}, {4, 5, 6}});
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (arr) VALUES (?)")) {
        ps.setArray(1, array);
        ps.executeUpdate();
    }
}

配列の読み取り

Array オブジェクトを読み取るには ResultSet#getArray(columnIndex) を使用してください。このオブジェクトを使用して、任意のネスト深度の配列にアクセスできます。 Array#getResultSet() メソッドを使用すると、配列要素を java.sql.ResultSet としてより統一的な方法で読み取ることができます。配列要素の正確な型が不明な場合に有用です。

例

try (Connection conn = ...) {
    try (PreparedStatement ps = conn.prepareStatement("SELECT ?::Array(Int32)")) {
        ps.setArray(1, array);
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Array array = rs.getArray(1);

                Object[] arr = (Object[]) array;
                Arrays.stream(arr).forEach(this::handleArrayElement);

                // or by using `ResultSet`
                ResultSet resultSet = array.getResultSet();
                while (resultSet.next()) {
                    // ...
                }
            }
        }
    } 
}

Tuple の書き込み

タプルは com.clickhouse.data.Tuple オブジェクトにマッピングされ、setObject(columnIndex, tuple) メソッドを呼び出してこのオブジェクトとして書き込む必要があります。 移植性を高めるために、タプルの書き込みには java.sql.Struct オブジェクトを使用することも可能です。

例

try (Connection conn = ...) {
    Tuple tuple = new Tuple(1, "test", LocalDate.parse("2026-03-02"));
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (tuple) VALUES (?)")) {
        ps.setObject(1, tuple);
        ps.executeUpdate();
    }
}

try (Connection conn = ...) {
    Struct struct = conn.createStruct("Tuple(Int32, String, Date)", new Object[] {1, "test", LocalDate.parse("2026-03-02")});
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (tuple) VALUES (?)")) {
        ps.setStruct(1, struct);
        ps.executeUpdate();
    }
}

Tuple の読み取り

メソッド getObject(columnIndex) は Object[] を返します。getObject(columnIndex, Array.class) メソッドを使用することで、タプルを java.sql.Array として読み取ることができます。

例

try (Connection conn = ...) {
    try (PreparedStatement stmt = conn.prepareStatement("SELECT ?::Tuple(String, Int32, Date)")) {
        Array tuple = conn.createArrayOf("Tuple(String, Int32, Date)",  new Object[]{"test", 123, LocalDate.parse("2026-03-02")});
        stmt.setObject(1, tuple);
        try (ResultSet rs = stmt.executeQuery()) {
            rs.next();
            Array dbTuple = rs.getArray(1);
            Assert.assertEquals(dbTuple, tuple);
            Object arr = rs.getObject(1);
            Assert.assertEquals(arr, tuple.getArray());
        }
    }
}

Mapの書き込み

Map 型はキーと値のペアを必要とするため（java.sql.Struct はキーと値のペアをサポートしないため）、java.collections.Map オブジェクトとしてのみ書き込むことができます。

例

try (Connection conn = ...) {
    Map<String, Integer> map = new HashMap<>();
    map.put("key1", 1);
    map.put("key2", 2);
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (map) VALUES (?)")) {
        ps.setObject(1, map);
        ps.executeUpdate();
    }
}

Mapの読み取り

Map は getObject(columnIndex, Map.class) メソッドを使用することで java.collections.Map オブジェクトとして読み取ることができます。

例

try (Connection conn = ...) {
    try (PreparedStatement ps = conn.prepareStatement("SELECT ?::Map(String, Int32)")) {
        ps.setStruct(1, struct);
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Map<String, Integer> map = rs.getObject(1, Map.class);
                // ...
            }
        }
    }
}

Nested 型への書き込み

java.sql.Connection#createStruct を使用して java.sql.Struct オブジェクトをインスタンス化します。このオブジェクトは、複数のデータベース間でネストされたデータの扱いを統一するために設計されています。 Struct のファクトリメソッドに設定を渡すには、Connection オブジェクトが必要です。

このメソッドは 2 つの引数を受け取ります：

• typeName - ネストされた要素の型名。例えば Nested(Tuple(Int32, String)) -> "Nested(Tuple(Int32, String))"。
• elements - 実際のネスト要素です。たとえば [1, 'test'] -> new Object[] {1, 'test'} と指定します。

例

try (Connection conn = ...) {
    Struct struct = conn.createStruct("Nested(Tuple(Int32, String))", new Object[] {1, 'test'});
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (nested) VALUES (?)")) {
        ps.setStruct(1, struct);
        ps.executeUpdate();
    }
}

Nested 型の読み取り

Nested オブジェクトを読み取るには、ResultSet#getStruct(columnIndex, StructDescriptor) を使用します。このオブジェクトを使うと、どれだけ深くネストされていてもアクセスできます。 Struct#getResultSet() メソッドを使用すると、ネストされた要素を java.sql.ResultSet と同様の、より一貫した方法で読み取ることができます。 これは、ネストされた要素の正確な型が不明な場合に有用です。

例

try (Connection conn = ...) {
    try (PreparedStatement ps = conn.prepareStatement("SELECT ?::Nested(Tuple(Int32, String))")) {
        ps.setStruct(1, struct);
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Struct struct = rs.getStruct(1);
                Object[] tuple = (Object[]) struct;
                Arrays.stream(tuple).forEach(this::handleTupleElement);

                // or by using `ResultSet`
                ResultSet resultSet = struct.getResultSet();
                while (resultSet.next()) {
                    // ...
                }
            }
        }
    }
}

地理型

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 が返されます。
• getObject(columnIndex, String.class) メソッドを使用することで、UUID を String として読み書きできます。
• IPv4 と IPv6 は JDBC の標準型ではありませんが、JDK には含まれています。デフォルトでは、getObject() メソッドから java.net.Inet4Address と java.net.Inet6Address のオブジェクトが返されます。
• getObject(columnIndex, String.class) メソッドを使用すると、IPv4 および IPv6 を String 型として読み書きできます。

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

日付/時刻およびタイムスタンプの処理における一般的な落とし穴とドライバーのロジックについては、日付/時刻ガイドを参照してください。

接続の作成

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で実行時間が長くなる大規模な挿入（INSERT）を行う際、次のようなJDBCタイムアウトエラーが発生することがあります:

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

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

Mac OS

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 から解析されます。

Example:

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 として読み取られます。
• 文字列は UTF-8 エンコーディングで保存されます。

日付/時刻型

ClickHouse 型	V1 との互換性	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
Nested	❌	ARRAY	java.sql.Array	STRUCT	java.sql.Struct

• In V2 では、Array は JDBC との互換性を維持するため、デフォルトで java.sql.Array にマッピングされます。これは返される配列値の型情報をより多く持たせることも目的としており、型推論に役立ちます。
• V2 では Array が getResultSet() メソッドを実装し、元の配列と同一の内容を持つ java.sql.ResultSet を返します。
• V1 では Map に対して STRUCT を使用していますが、常に java.util.Map オブジェクトを返します。V2 では、Map を JAVA_OBJECT にマッピングすることでこの問題を解消しています。
• V1 は Tuple に対して STRUCT を使用しますが、常に List<Object> 型のオブジェクトを返します。V2 では Tuple を OTHER にマッピングし、デフォルトで Object[] を返します。
• V2ではタプルの書き込みに使用する com.clickhouse.data.Tuple#Tuple が導入されました。これにより、値がタプルか配列かを容易に判別できます。
• PreparedStatement#setBytes と ResultSet#getBytes はコレクション型に対しては使用できません。これらのメソッドはバイナリ文字列を扱うためのものです。
• 通常、Array 型の読み書きには java.sql.Array を使用します。JDBC ドライバはこの方式を完全にサポートしています。
• V2 では Nested は Array にマッピングされ、タプルの配列として扱われます。
• V2 では java.sql.Struct に対するサポートは部分的なものにとどまります。Struct は Array 型と非常によく似た型であり、キーと値のペアをサポートしないためです。Struct は Tuple 値の書き込みに使用できます。

地理型

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 アドレスを数値として読み取ることはサポートされていません。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
}

入力テーブル関数の使用

高いパフォーマンスを発揮できるオプション:

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 関数のドキュメント を可能な限り参照してください

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

このオプションは小規模な INSERT 処理にのみ推奨されます。長大な 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コネクタは、HttpClient、HttpURLConnection、およびApache HttpClientの3つのHTTPライブラリをサポートしています。

注記

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で実行時間が長くなる大規模な挿入（INSERT）を行う際、次のようなJDBCタイムアウトエラーが発生することがあります:

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

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

Mac OS

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();
}