Java 客户端 (V2)

Java 客户端库，用于通过其协议与数据库服务器通信。当前的实现仅支持 HTTP 接口。该库提供了自己的 API 来向服务器发送请求。该库还提供了用于处理不同二进制数据格式（RowBinary* & Native*）的工具。

注意

如果您正在寻找先前版本的 Java 客户端文档，请参阅此处。

设置

Maven Central（项目网页）：https://mvnrepository.com/artifact/com.clickhouse/client-v2
Nightly builds（仓库链接）：https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/

Maven
Gradle (Kotlin)
Gradle

<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>client-v2</artifactId>
    <version>0.7.2</version>
</dependency>

// https://mvnrepository.com/artifact/com.clickhouse/client-v2
implementation("com.clickhouse:client-v2:0.7.2")

// https://mvnrepository.com/artifact/com.clickhouse/client-v2
implementation 'com.clickhouse:client-v2:0.7.2'

初始化

Client 对象通过 com.clickhouse.client.api.Client.Builder#build() 初始化。每个客户端都有自己的上下文，对象之间不共享。Builder 具有用于方便设置的配置方法。

示例

 Client client = new Client.Builder()
                .addEndpoint("https://clickhouse-cloud-instance:8443/")
                .setUsername(user)
                .setPassword(password)
                .build();

Client 是 AutoCloseable，当不再需要时应关闭。

身份验证

身份验证在初始化阶段为每个客户端配置。支持三种身份验证方法：通过密码、通过访问令牌、通过 SSL 客户端证书。

通过密码进行身份验证需要通过调用 setUsername(String) 和 setPassword(String) 设置用户名密码

 Client client = new Client.Builder()
        .addEndpoint("https://clickhouse-cloud-instance:8443/")
        .setUsername(user)
        .setPassword(password)
        .build();

通过访问令牌进行身份验证需要通过调用 setAccessToken(String) 设置访问令牌

 Client client = new Client.Builder()
        .addEndpoint("https://clickhouse-cloud-instance:8443/")
        .setAccessToken(userAccessToken)
        .build();

通过 SSL 客户端证书进行身份验证需要设置用户名，启用 SSL 身份验证，设置客户端证书和客户端密钥，分别通过调用 setUsername(String)、useSSLAuthentication(boolean)、setClientCertificate(String) 和 setClientKey(String)

Client client = new Client.Builder()
        .useSSLAuthentication(true)
        .setUsername("some_user")
        .setClientCertificate("some_user.crt")
        .setClientKey("some_user.key")

注意

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'（查询将输出带有类似 {"common_names":["some_user"]} 的 auth_params）

配置

所有设置都由实例方法（也称为配置方法）定义，这些方法使每个值的范围和上下文清晰明了。主要配置参数在一个范围（客户端或操作）中定义，并且互不覆盖。

配置在客户端创建期间定义。请参阅 com.clickhouse.client.api.Client.Builder。

客户端配置

配置方法	参数	描述
`addEndpoint(String endpoint)`	- `enpoint` - URL 格式化的服务器地址。	向可用服务器列表添加服务器端点。目前仅支持一个端点。
`addEndpoint(Protocol protocol, String host, int port, boolean secure)`	- `protocol` - 连接协议 `com.clickhouse.client.api.enums.Protocol#HTTP`。 - `host` - 服务器的 IP 或主机名。 - `secure` - 通信是否应使用协议的安全版本 (HTTPS)	向可用服务器列表添加服务器端点。目前仅支持一个端点。
`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，超过此 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 Keep Alive 启用了一种机制，该机制将检查连接的活跃性，并有助于检测突然终止的连接。
`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 Cookie 并将其发送回服务器。
`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 压力。如果启用此选项，则读取器将使用预先分配的缓冲区进行数字转码。这是安全的，因为每个读取器都有自己的缓冲区集，并且读取器由一个线程使用。
`httpHeader(String key, String value)`	- `key` - HTTP 标头键。 - `value` - 标头的字符串值。	设置单个 HTTP 标头的值。先前的值将被覆盖。
`httpHeader(String key, Collection values)`	- `key` - HTTP 标头键。 - `values` - 字符串值列表。	设置单个 HTTP 标头的值。先前的值将被覆盖。
`httpHeaders(Map headers)`	- `header` - 包含 HTTP 标头及其值的映射。	一次设置多个 HTTP 标头值。
`serverSetting(String name, String value)`	- `name` - 查询级别设置的名称。 - `value` - 设置的字符串值。	设置要随每个查询传递给服务器的设置。单个操作设置可能会覆盖它。设置列表
`serverSetting(String name, Collection values)`	- `name` - 查询级别设置的名称。 - `values` - 设置的字符串值。	设置要随每个查询传递给服务器的设置。单个操作设置可能会覆盖它。设置列表。此方法对于设置具有多个值的设置很有用，例如角色
`columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy)`	- `strategy` - 列-字段匹配策略的实现	设置用于在注册 DTO 时匹配 DTO 类字段和 DB 列的自定义策略。
`useHTTPBasicAuth(boolean useBasicAuth)`	- `useBasicAuth` - 指示是否应启用该选项的标志	设置是否应将基本 HTTP 身份验证用于用户密码身份验证。默认情况下启用。使用此类型的身份验证可以解决密码包含无法通过 HTTP 标头传输的特殊字符的问题。
`setClientName(String clientName)`	- `clientName` - 表示应用程序名称的字符串	设置有关调用应用程序的其他信息。此字符串将作为客户端名称传递给服务器。在 HTTP 协议的情况下，它将作为 `User-Agent` 标头传递。
`useBearerTokenAuth(String bearerToken)`	- `bearerToken` - 编码的 Bearer 令牌	指定是否使用 Bearer 身份验证以及要使用的令牌。令牌将按原样发送，因此应在传递给此方法之前对其进行编码。

常用定义

ClickHouseFormat

支持的格式的枚举。它包括 ClickHouse 支持的所有格式。

raw - 用户应转码原始数据
full - 客户端可以自行转码数据并接受原始数据流
- - ClickHouse 不支持此格式的操作

此客户端版本支持

格式	输入	输出
TabSeparated	raw	raw
TabSeparatedRaw	raw	raw
TabSeparatedWithNames	raw	raw
TabSeparatedWithNamesAndTypes	raw	raw
TabSeparatedRawWithNames	raw	raw
TabSeparatedRawWithNamesAndTypes	raw	raw
Template	raw	raw
TemplateIgnoreSpaces	raw	-
CSV	raw	raw
CSVWithNames	raw	raw
CSVWithNamesAndTypes	raw	raw
CustomSeparated	raw	raw
CustomSeparatedWithNames	raw	raw
CustomSeparatedWithNamesAndTypes	raw	raw
SQLInsert	-	raw
Values	raw	raw
Vertical	-	raw
JSON	raw	raw
JSONAsString	raw	-
JSONAsObject	raw	-
JSONStrings	raw	raw
JSONColumns	raw	raw
JSONColumnsWithMetadata	raw	raw
JSONCompact	raw	raw
JSONCompactStrings	-	raw
JSONCompactColumns	raw	raw
JSONEachRow	raw	raw
PrettyJSONEachRow	-	raw
JSONEachRowWithProgress	-	raw
JSONStringsEachRow	raw	raw
JSONStringsEachRowWithProgress	-	raw
JSONCompactEachRow	raw	raw
JSONCompactEachRowWithNames	raw	raw
JSONCompactEachRowWithNamesAndTypes	raw	raw
JSONCompactStringsEachRow	raw	raw
JSONCompactStringsEachRowWithNames	raw	raw
JSONCompactStringsEachRowWithNamesAndTypes	raw	raw
JSONObjectEachRow	raw	raw
BSONEachRow	raw	raw
TSKV	raw	raw
Pretty	-	raw
PrettyNoEscapes	-	raw
PrettyMonoBlock	-	raw
PrettyNoEscapesMonoBlock	-	raw
PrettyCompact	-	raw
PrettyCompactNoEscapes	-	raw
PrettyCompactMonoBlock	-	raw
PrettyCompactNoEscapesMonoBlock	-	raw
PrettySpace	-	raw
PrettySpaceNoEscapes	-	raw
PrettySpaceMonoBlock	-	raw
PrettySpaceNoEscapesMonoBlock	-	raw
Prometheus	-	raw
Protobuf	raw	raw
ProtobufSingle	raw	raw
ProtobufList	raw	raw
Avro	raw	raw
AvroConfluent	raw	-
Parquet	raw	raw
ParquetMetadata	raw	-
Arrow	raw	raw
ArrowStream	raw	raw
ORC	raw	raw
One	raw	-
Npy	raw	raw
RowBinary	full	full
RowBinaryWithNames	full	full
RowBinaryWithNamesAndTypes	full	full
RowBinaryWithDefaults	full	-
Native	full	raw
Null	-	raw
XML	-	raw
CapnProto	raw	raw
LineAsString	raw	raw
Regexp	raw	-
RawBLOB	raw	raw
MsgPack	raw	raw
MySQLDump	raw	-
DWARF	raw	-
Markdown	-	raw
Form	raw	-

Insert 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（数据传输对象）对象集合。

settings - 请求设置。

返回值

InsertResponse 类型的 Future - 操作结果和附加信息，例如服务器端指标。

示例

// Important step (done once) - register class to pre-compile object serializer according to the table schema. 
client.register(ArticleViewEvent.class, client.getTableSchema(TABLE_NAME));


List<ArticleViewEvent> events = loadBatch();

try (InsertResponse response = client.insert(TABLE_NAME, events).get()) {
    // handle response, then it will be closed and connection that served request will be released. 
}

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 将保存对响应流的引用，该引用应由支持格式的读取器使用。

签名

CompletableFuture<QueryResponse> query(String sqlQuery, QuerySettings settings)
CompletableFuture<QueryResponse> query(String sqlQuery)

参数

sqlQuery - 单个 SQL 语句。查询按原样发送到服务器。

settings - 请求设置。

返回值

QueryResponse 类型的 Future - 结果数据集和附加信息，例如服务器端指标。在使用数据集后，应关闭 Response 对象。

示例

final String sql = "select * from " + TABLE_NAME + " where title <> '' limit 10";

// Default format is RowBinaryWithNamesAndTypesFormatReader so reader have all information about columns
try (QueryResponse response = client.query(sql).get(3, TimeUnit.SECONDS);) {

    // Create a reader to access the data in a convenient way
    ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);

    while (reader.hasNext()) {
        reader.next(); // Read the next record from stream and parse it

        // get values
        double id = reader.getDouble("id");
        String title = reader.getString("title");
        String url = reader.getString("url");

        // collecting data 
    }
} catch (Exception e) {
    log.error("Failed to read data", e);
}

// put business logic outside of the reading block to release http connection asap.  

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 - 结果数据集和附加信息，例如服务器端指标。在使用数据集后，应关闭 Response 对象。

示例

// define parameters. They will be sent to the server along with the request.   
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()) {

    // Create a reader to access the data in a convenient way
    ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);

    while (reader.hasNext()) {
        reader.next(); // Read the next record from stream and parse it

        // reading data 
    }

} 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("Reading whole table and process record by record");
    final String sql = "select * from " + TABLE_NAME + " where title <> ''";

    // Read whole result set and process it record by record
    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。
`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 类型的时区。

示例

示例代码位于 repo 中
参考 Spring Service 实现

通用 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 语句。

返回值

返回 TableSchema 对象，其中包含与 sql 表达式匹配的列。

TableSchema

register(Class<?> clazz, TableSchema schema)

为 Java Class 编译序列化和反序列化层，以便与 schema 一起用于写入/读取数据。此方法将为 getter/setter 对和相应的列创建序列化器和反序列化器。通过从方法名称中提取列名来找到列匹配项。例如，getFirstName 将用于列 first_name 或 firstname。

签名

void register(Class<?> clazz, TableSchema schema)

参数

clazz - 表示用于读取/写入数据的 POJO 的类。

schema - 用于与 POJO 属性匹配的数据结构。

示例

client.register(ArticleViewEvent.class, client.getTableSchema(TABLE_NAME));

使用示例

完整的示例代码存储在 repo 的 'example' 文件夹中

client-v2 - 主要示例集。
demo-service - 如何在 Spring Boot 应用程序中使用客户端的示例。
demo-kotlin-service - 如何在 Ktor (Kotlin) 应用程序中使用客户端的示例。

设置​

初始化​

身份验证​

配置​

客户端配置​

常用定义​

ClickHouseFormat​

Insert API​

insert(String tableName, InputStream data, ClickHouseFormat format)​

insert(String tableName, List<?> data, InsertSettings settings)​

InsertSettings​

InsertResponse​

Query API​

query(String sqlQuery)​

query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)​

queryAll(String sqlQuery)​

QuerySettings​

QueryResponse​

示例​

通用 API​

getTableSchema(String table)​

getTableSchemaFromQuery(String sql)​

TableSchema​

register(Class<?> clazz, TableSchema schema)​

使用示例​

设置

初始化

身份验证

配置

客户端配置

常用定义

ClickHouseFormat

Insert API

insert(String tableName, InputStream data, ClickHouseFormat format)

insert(String tableName, List<?> data, InsertSettings settings)

InsertSettings

InsertResponse

Query API

query(String sqlQuery)

query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)

queryAll(String sqlQuery)

QuerySettings

QueryResponse

示例

通用 API

getTableSchema(String table)

getTableSchemaFromQuery(String sql)

TableSchema

register(Class<?> clazz, TableSchema schema)

使用示例