Java 客户端

v0.8+

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

设置

Maven Central（项目网页）: https://mvnrepository.com/artifact/com.clickhouse/client-v2
每日构建（仓库链接）: https://central.sonatype.com/repository/maven-snapshots/
旧每日构建工件库（仓库链接）: https://s01.oss.sonatype.org/content/repositories/snapshots/

Maven
Gradle (Kotlin)
Gradle

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

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

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

初始化

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 客户端证书进行认证需要通过调用 setUsername(String)、useSSLAuthentication(boolean)、setClientCertificate(String) 和 setClientKey(String) 分别设置用户名、启用 SSL 认证、设置客户端证书和客户端密钥：

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'（查询将输出 auth_params，如 {"common_names":["some_user"]}）

配置

所有设置均通过实例方法（也称为配置方法）来定义，这使得每个值的范围和上下文清晰明确。主要配置参数在一个范围内定义（客户端或操作），并且不会相互覆盖。

配置在客户端创建过程中定义。请参见 com.clickhouse.client.api.Client.Builder。

客户端配置

配置方法	参数	描述
`addEndpoint(String endpoint)`	- `endpoint` - 格式化为 URL 的服务器地址。	将一个服务器端点添加到可用服务器列表。目前仅支持一个端点。默认: `none` 枚举: `none` 键: `none`
`addEndpoint(Protocol protocol, String host, int port, boolean secure)`	- `protocol` - 连接协议 `com.clickhouse.client.api.enums.Protocol#HTTP`。 - `host` - 服务器的 IP 地址或主机名。 - `secure` - 如果通信应使用协议的安全版本（HTTPS）	将一个服务器端点添加到可用服务器列表。目前仅支持一个端点。默认: `none` 枚举: `none` 键: `none`
`setOption(String key, String value)`	- `key` - 客户端配置选项的字符串键。 - `value` - 选项的字符串值	设置客户端选项的原始值。读取配置时从属性文件中提取时很有用。
`setUsername(String username)`	- `username` - 在认证过程中使用的用户的用户名	为进一步配置选择的认证方法设置用户名默认: `default` 枚举: `ClientConfigProperties.USER` 键: `user`
`setPassword(String password)`	- `password` - 用于密码认证的秘密值	为密码认证设置秘密，并有效选择为认证方法默认: - 枚举: `ClientConfigProperties.PASSWORD` 键: `password`
`setAccessToken(String accessToken)`	- `accessToken` - 访问令牌的字符串表示	设置访问令牌以通过设置的相应认证方法进行身份验证默认: - 枚举: `ClientConfigProperties.ACCESS_TOKEN` 键: `access_token`
`useSSLAuthentication(boolean useSSLAuthentication)`	- `useSSLAuthentication` - 表示是否应使用 SSL 认证的标志	将 SSL 客户端证书作为认证方法。默认: - 枚举: `ClientConfigProperties.SSL_AUTH` 键: `ssl_authentication`
`enableConnectionPool(boolean enable)`	- `enable` - 表示是否应该启用该选项的标志	设置连接池是否启用默认: `true` 枚举: `ClientConfigProperties.CONNECTION_POOL_ENABLED` 键: `connection_pool_enabled`
`setConnectTimeout(long timeout, ChronoUnit unit)`	- `timeout` - 以某种时间单位表示的超时时间。 - `unit` - `timeout` 的时间单位	设置任何外出连接的连接初始化超时时间。此项会影响获得套接字连接时的等待时间。默认: - 枚举: `ClientConfigProperties.CONNECTION_TIMEOUT` 键: `connection_timeout`
`setConnectionRequestTimeout(long timeout, ChronoUnit unit)`	- `timeout` - 以某种时间单位表示的超时时间。 - `unit` - `timeout` 的时间单位	设置连接请求超时时间。此项仅对从池中获取连接有效。默认: `10000` 枚举: `ClientConfigProperties.CONNECTION_REQUEST_TIMEOUT` 键: `connection_request_timeout`
`setMaxConnections(int maxConnections)`	- `maxConnections` - 连接数	设置客户端可以向每个服务器端点开放的连接数。默认: `10` 枚举: `ClientConfigProperties.HTTP_MAX_OPEN_CONNECTIONS` 键: `max_open_connections`
`setConnectionTTL(long timeout, ChronoUnit unit)`	- `timeout` - 以某种时间单位表示的超时时间。 - `unit` - `timeout` 的时间单位	设置连接的生存时间，超出后连接将被视为不活动的默认: `-1` 枚举: `ClientConfigProperties.CONNECTION_TTL` 键: `connection_ttl`
`setKeepAliveTimeout(long timeout, ChronoUnit unit)`	- `timeout` - 以某种时间单位表示的超时时间。 - `unit` - `timeout` 的时间单位	设置 HTTP 连接的保持存活超时时间。此选项可以通过将超时时间设置为零 - `0` 来禁用保持连接默认: - 枚举: `ClientConfigProperties.HTTP_KEEP_ALIVE_TIMEOUT` 键: `http_keep_alive_timeout`
`setConnectionReuseStrategy(ConnectionReuseStrategy strategy)`	- `strategy` - 枚举 `com.clickhouse.client.api.ConnectionReuseStrategy` 常量	选择连接池应使用的策略：`LIFO` 如果连接应在返回池后立即重用，或 `FIFO` 按照可用顺序使用连接（返回的连接不会立即使用）。默认: `FIFO` 枚举: `ClientConfigProperties.CONNECTION_REUSE_STRATEGY` 键: `connection_reuse_strategy`
`setSocketTimeout(long timeout, ChronoUnit unit)`	- `timeout` - 以某种时间单位表示的超时时间。 - `unit` - `timeout` 的时间单位	设置影响读写操作的套接字超时时间默认: `0` 枚举: `ClientConfigProperties.SOCKET_OPERATION_TIMEOUT` 键: `socket_timeout`
`setSocketRcvbuf(long size)`	- `size` - 以字节为单位的大小	设置 TCP 套接字接收缓冲区。此缓冲区位于 JVM 内存外。默认: `8196` 枚举: `ClientConfigProperties.SOCKET_RCVBUF_OPT` 键: `socket_rcvbuf`
`setSocketSndbuf(long size)`	- `size` - 以字节为单位的大小	设置 TCP 套接字发送缓冲区。此缓冲区位于 JVM 内存外。默认: `8196` 枚举: `ClientConfigProperties.SOCKET_SNDBUF_OPT` 键: `socket_sndbuf`
`setSocketKeepAlive(boolean value)`	- `value` - 表示该选项应启用的标志。	为客户端创建的每个 TCP 套接字设置选项 `SO_KEEPALIVE`。 TCP 保持活动启用机制，可以检查连接的存活状态，并帮助检测意外终止的连接。默认: - 枚举: `ClientConfigProperties.SOCKET_KEEPALIVE_OPT` 键: `socket_keepalive`
`setSocketTcpNodelay(boolean value)`	- `value` - 表示该选项应启用的标志。	为客户端创建的每个 TCP 套接字设置选项 `SO_NODELAY`。此 TCP 选项将使套接字尽快推送数据。默认: - 枚举: `ClientConfigProperties.SOCKET_TCP_NO_DELAY_OPT` 键: `socket_tcp_nodelay`
`setSocketLinger(int secondsToWait)`	- `secondsToWait` - 等待的秒数。	为客户端创建的每个 TCP 套接字设置保持时间。默认: - 枚举: `ClientConfigProperties.SOCKET_LINGER_OPT` 键: `socket_linger`
`compressServerResponse(boolean enabled)`	- `enabled` - 表示该选项应启用的标志	设置服务器是否应压缩其响应。默认: `true` 枚举: `ClientConfigProperties.COMPRESS_SERVER_RESPONSE` 键: `compress`
`compressClientRequest(boolean enabled)`	- `enabled` - 表示该选项应启用的标志	设置客户端是否应压缩其请求。默认: `false` 枚举: `ClientConfigProperties.COMPRESS_CLIENT_REQUEST` 键: `decompress`
`useHttpCompression(boolean enabled)`	- `enabled` - 表示该选项应启用的标志	设置 HTTP 压缩是否应在客户端/服务器通信中使用（如果启用相应选项）
`appCompressedData(boolean enabled)`	- `enabled` - 表示该选项应启用的标志	告诉客户端压缩将由应用程序处理。默认: `false` 枚举: `ClientConfigProperties.APP_COMPRESSED_DATA` 键: `app_compressed_data`
`setLZ4UncompressedBufferSize(int size)`	- `size` - 以字节为单位的大小	设置将接收数据流非压缩部分的缓冲区大小。如果缓冲区估计不足，将创建一个新缓冲区，并在日志中出现相应警告。默认: `65536` 枚举: `ClientConfigProperties.COMPRESSION_LZ4_UNCOMPRESSED_BUF_SIZE` 键: `compression.lz4.uncompressed_buffer_size`
`disableNativeCompression`	- `disable` - 表示是否应禁用该选项的标志	禁用本地压缩。如果设置为 true，则将禁用本地压缩。默认: `false` 枚举: `ClientConfigProperties.DISABLE_NATIVE_COMPRESSION` 键: `disable_native_compression`
`setDefaultDatabase(String database)`	- `database` - 数据库的名称	设置默认数据库。默认: `default` 枚举: `ClientConfigProperties.DATABASE` 键: `database`
`addProxy(ProxyType type, String host, int port)`	- `type` - 代理类型。 - `host` - 代理主机名或 IP 地址。 - `port` - 代理端口	设置用于与服务器通信的代理。如果代理需要认证，则需要设置代理。默认: - 枚举: `ClientConfigProperties.PROXY_TYPE` 键: `proxy_type` 默认: - 枚举: `ClientConfigProperties.PROXY_HOST` 键: `proxy_host` 默认: - 枚举: `ClientConfigProperties.PROXY_PORT` 键: `proxy_port`
`setProxyCredentials(String user, String pass)`	- `user` - 代理用户名。 - `pass` - 密码	设置用户凭证以通过代理进行身份验证。默认: - 枚举: `ClientConfigProperties.PROXY_USER` 键: `proxy_user` 默认: - 枚举: `ClientConfigProperties.PROXY_PASSWORD` 键: `proxy_password`
`setExecutionTimeout(long timeout, ChronoUnit timeUnit)`	- `timeout` - 以某种时间单位表示的超时时间。 - `timeUnit` - `timeout` 的时间单位	设置查询的最大执行超时时间默认: `0` 枚举: `ClientConfigProperties.MAX_EXECUTION_TIME` 键: `max_execution_time`
`setHttpCookiesEnabled(boolean enabled)`	`enabled` - 表示该选项应启用的标志	设置是否应记住 HTTP Cookie 并发送回服务器。
`setSSLTrustStore(String path)`	`path` - 本地（客户端）系统上的文件路径	设置客户端是否应使用 SSL 信任存储进行服务器主机验证。默认: - 枚举: `ClientConfigProperties.SSL_TRUST_STORE` 键: `trust_store`
`setSSLTrustStorePassword(String password)`	`password` - 秘密值	设置用于解锁 `setSSLTrustStore(String path)` 所指定的 SSL 信任存储的密码默认: - 枚举: `ClientConfigProperties.SSL_KEY_STORE_PASSWORD` 键: `key_store_password`
`setSSLTrustStoreType(String type)`	`type` - 信任存储类型名称	设置由 `setSSLTrustStore(String path)` 指定的信任存储的类型。默认: - 枚举: `ClientConfigProperties.SSL_KEYSTORE_TYPE` 键: `key_store_type`
`setRootCertificate(String path)`	`path` - 本地（客户端）系统上的文件路径	设置客户端是否应使用指定的根（CA）证书进行服务器主机验证。默认: - 枚举: `ClientConfigProperties.CA_CERTIFICATE` 键: `sslrootcert`
`setClientCertificate(String path)`	`path` - 本地（客户端）系统上的文件路径	设置在初始化 SSL 连接时使用的客户端证书路径，并用于 SSL 身份验证。默认: - 枚举: `ClientConfigProperties.SSL_CERTIFICATE` 键: `sslcert`
`setClientKey(String path)`	`path` - 本地（客户端）系统上的文件路径	设置用于加密与服务器通信的 SSL 客户端私钥。默认: - 枚举: `ClientConfigProperties.SSL_KEY` 键: `ssl_key`
`useServerTimeZone(boolean useServerTimeZone)`	`useServerTimeZone` - 表示该选项应启用的标志	设置客户端是否应在解码 DateTime 和 Date 列值时使用服务器时区。如果启用，则服务器时区应通过 `setServerTimeZone(String timeZone)` 设置默认: `true` 枚举: `ClientConfigProperties.USE_SERVER_TIMEZONE` 键: `use_server_time_zone`
`useTimeZone(String timeZone)`	`timeZone` - 有效的 Java 时区 ID 的字符串值（见 `java.time.ZoneId`）	设置在解码 DateTime 和 Date 列值时是否应使用指定的时区。将覆盖服务器时区。默认: - 枚举: `ClientConfigProperties.USE_TIMEZONE` 键: `use_time_zone`
`setServerTimeZone(String timeZone)`	`timeZone` - 有效的 Java 时区 ID 的字符串值（见 `java.time.ZoneId`）	设置服务器端时区。默认为使用 UTC 时区。默认: `UTC` 枚举: `ClientConfigProperties.SERVER_TIMEZONE` 键: `server_time_zone`
`useAsyncRequests(boolean async)`	`async` - 表示该选项应启用的标志。	设置客户端是否应在单独的线程中执行请求。默认情况下禁用，因为应用程序更清楚如何组织多线程任务，在单独线程中运行任务不会提高性能。默认: `false` 枚举: `ClientConfigProperties.ASYNC_OPERATIONS` 键: `async`
`setSharedOperationExecutor(ExecutorService executorService)`	`executorService` - 执行器服务的实例。	设置操作任务的执行器服务。默认: `none` 枚举: `none` 键: `none`
`setClientNetworkBufferSize(int size)`	- `size` - 以字节为单位的大小	设置在应用程序内存空间中使用的缓冲区大小，用于在套接字和应用程序之间来回复制数据。更大的缓冲区减少与 TCP 栈的系统调用，但会影响每个连接所消耗的内存。此缓冲区也会受到 GC 的影响，因为连接的生命周期较短。此外，请注意，分配大的连续内存块可能会出现问题。默认: `300000` 枚举: `ClientConfigProperties.CLIENT_NETWORK_BUFFER_SIZE` 键: `client_network_buffer_size`
`retryOnFailures(ClientFaultCause ...causes)`	- `causes` - `com.clickhouse.client.api.ClientFaultCause` 的枚举常量	设置可恢复/可重试的故障类型。默认: `NoHttpResponse,ConnectTimeout,ConnectionRequestTimeout` 枚举: `ClientConfigProperties.CLIENT_RETRY_ON_FAILURE` 键: `client_retry_on_failures`
`setMaxRetries(int maxRetries)`	- `maxRetries` - 重试次数	设置重试次数，适用于由 `retryOnFailures(ClientFaultCause ...causes)` 定义的故障默认: `3` 枚举: `ClientConfigProperties.RETRY_ON_FAILURE` 键: `retry`
`allowBinaryReaderToReuseBuffers(boolean reuse)`	- `reuse` - 表示该选项应启用的标志	大多数数据集包含编码为小字节序列的数值数据。默认情况下，读取器将分配所需的缓冲区，将数据读入该缓冲区，然后转换为目标数字类。这可能会导致 GC 压力，因为会分配和释放许多小对象。如果启用此选项，则读取器将使用预分配的缓冲区进行数字跨境转换。这是安全的，因为每个读取器都有自己的一组缓冲区，读取器由一个线程使用。
`httpHeader(String key, String value)`	- `key` - HTTP 头部键。 - `value` - 头部的字符串值。	为单个 HTTP 头设置值。以前的值将被覆盖。默认: `none` 枚举: `none` 键: `none`
`httpHeader(String key, Collection values)`	- `key` - HTTP 头部键。 - `values` - 字符串值的列表。	为单个 HTTP 头设置值。以前的值将被覆盖。默认: `none` 枚举: `none` 键: `none`
`httpHeaders(Map headers)`	- `header` - 带有 HTTP 头及其值的映射。	同时设置多个 HTTP 头值。默认: `none` 枚举: `none` 键: `none`
`serverSetting(String name, String value)`	- `name` - 查询级别设置的名称。 - `value` - 设置的字符串值。	设置需随每个查询传递给服务器的设置。单个操作设置可能会覆盖它。下列为设置列表默认: `none` 枚举: `none` 键: `none`
`serverSetting(String name, Collection values)`	- `name` - 查询级别设置的名称。 - `values` - 设置的字符串值。	设置需随每个查询传递给服务器的设置。单个操作设置可能会覆盖它。下列为设置列表。此方法适用于设置具有多个值的设置，例如角色默认: `none` 枚举: `none` 键: `none`
`columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy)`	- `strategy` - 列与方法匹配策略的实现	设置自定义策略，用于在注册 DTO 时匹配 DTO 类字段和数据库列。默认: `none` 枚举: `none` 键: `none`
`useHTTPBasicAuth(boolean useBasicAuth)`	- `useBasicAuth` - 表示该选项应启用的标志	设置是否应使用基本 HTTP 认证进行用户密码认证。默认启用。使用这种类型的认证可解决包含特殊字符的密码无法通过 HTTP 头进行传输的问题。默认: `true` 枚举: `ClientConfigProperties.HTTP_USE_BASIC_AUTH` 键: `http_use_basic_auth`
`setClientName(String clientName)`	- `clientName` - 表示应用程序名称的字符串	设置有关调用应用程序的其他信息。此字符串将作为客户端名称传递给服务器。在 HTTP 协议的情况下，将作为 `User-Agent` 头传递。默认: - 枚举: `ClientConfigProperties.CLIENT_NAME` 键: `client_name`
`useBearerTokenAuth(String bearerToken)`	- `bearerToken` - 编码的承载令牌	指定是否使用承载认证及使用的令牌。令牌将原样发送，因此应在传递给此方法之前进行编码。默认: - 枚举: `ClientConfigProperties.BEARERTOKEN_AUTH` 键: `bearer_token`
`registerClientMetrics(Object registry, String name)`	- `registry` - Micrometer 注册实例 - `name` - 监测组名称	在 Micrometer (https://micrometer.io/) 注册实例中注册传感器。
`setServerVersion(String version)`	- `version` - 服务器版本的字符串值	设置服务器版本以避免版本检测。默认: - 枚举: `ClientConfigProperties.SERVER_VERSION` 键: `server_version`
`typeHintMapping(Map typeHintMapping)`	- `typeHintMapping` - 类型提示映射	设置 ClickHouse 类型的类型提示映射。例如，可以将多维数组表示为 Java 容器，而不是自身的数组对象。默认: - 枚举: `ClientConfigProperties.TYPE_HINT_MAPPING` 键: `type_hint_mapping`
`sslSocketSNI(String sni)`	- `sni` - 服务器名称的字符串值	设置用于 SSL/TLS 连接中的 SNI（服务器名称指示）的服务器名称。默认: - 枚举: `ClientConfigProperties.SSL_SOCKET_SNI` 键: `ssl_socket_sni`

服务器设置

服务器端设置可以在客户端级别一次性设置（请参见 Builder 的 serverSetting 方法）或在操作级别（请参见操作设置类的 serverSetting）。

 try (Client client = new Client.Builder().addEndpoint(Protocol.HTTP, "localhost", mockServer.port(), false)
        .setUsername("default")
        .setPassword(ClickHouseServerForTest.getPassword())
        .compressClientRequest(true)

        // Client level
        .serverSetting("max_threads", "10")
        .serverSetting("async_insert", "1")
        .serverSetting("roles", Arrays.asList("role1", "role2"))

        .build()) {

	// Operation level
	QuerySettings querySettings = new QuerySettings();
	querySettings.serverSetting("session_timezone", "Europe/Zurich");

	...
}

当通过 setOption 方法设置选项（无论是 Client.Builder 还是操作设置类）时，服务器设置名称应以 clickhouse_setting_ 为前缀。此时，com.clickhouse.client.api.ClientConfigProperties#serverSetting() 可能会派上用场。

自定义 HTTP 头

自定义 HTTP 头可以为所有操作（客户端级别）或单个操作（操作级别）进行设定。


QuerySettings settings = new QuerySettings()
    .httpHeader(HttpHeaders.REFERER, clientReferer)
    .setQueryId(qId);

当通过 setOption 方法设置选项（无论是 Client.Builder 还是操作设置类）时，自定义头名称应以 http_header_ 为前缀。此时，com.clickhouse.client.api.ClientConfigProperties#httpHeader() 可能会派上用场。

常见定义

ClickHouseFormat

支持格式的枚举 supported formats。它包括 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 - collection 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)`	在执行操作之前设置数据库角色。集合的项目应为 `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 - 结果数据集和额外信息，例如服务器端指标。响应对象在消费数据集后应关闭。

示例

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 - 结果数据集和额外信息，例如服务器端指标。响应对象在消费数据集后应关闭。

示例


// 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 response =
        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)`	在执行操作之前设置数据库角色。集合的项目应为 `String` 值。
`setOption(String option, Object value)`	以原始格式设置配置选项。这不是服务器设置。

QueryResponse

包含查询执行结果的响应对象。仅当客户端从服务器获得响应时才可用。

备注

该对象应尽快关闭，以释放连接，因为在读取了先前响应的所有数据之前，连接无法重用。

方法	描述
`ClickHouseFormat getFormat()`	返回响应数据编码的格式。
`InputStream getInputStream()`	返回以指定格式的未压缩字节数据流。
`OperationMetrics getMetrics()`	返回操作指标的对象。
`String getQueryId()`	返回为操作分配的查询 ID（通过操作设置或服务器分配）。
`TimeZone getTimeZone()`	返回应在响应中处理 Date/DateTime 类型时使用的时区。

Examples

示例代码可在 repo 中找到
参考 Spring 服务实现

Common 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 类能够与 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));

Usage Examples

完整示例代码存储在 example 文件夹中：

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

设置​

初始化​

认证​

配置​

客户端配置​

服务器设置​

自定义 HTTP 头​

常见定义​

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​

Examples​

Common API​

getTableSchema(String table)​

getTableSchemaFromQuery(String sql)​

TableSchema​

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

Usage Examples​

设置

初始化

认证

配置

客户端配置

服务器设置

自定义 HTTP 头

常见定义

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

Examples

Common API

getTableSchema(String table)

getTableSchemaFromQuery(String sql)

TableSchema

register(Class<?> clazz, TableSchema schema)

Usage Examples