Java 客户端
Java 客户端库通过其协议与数据库服务器进行通信。目前的实现仅支持 HTTP 接口。该库提供自己的 API 来向服务器发送请求。该库还提供处理不同二进制数据格式的工具（RowBinary* 和 Native*）。
安装
- Maven Central（项目网页）：https://mvnrepository.com/artifact/com.clickhouse/client-v2
- 夜间构建（仓库链接）： https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/
- Maven
- Gradle (Kotlin)
- Gradle
初始化
Client 对象通过 com.clickhouse.client.api.Client.Builder#build() 初始化。每个客户端都有自己的上下文，没有对象在它们之间共享。构建器提供了方便设置的配置方法。
示例：
Client 是 AutoCloseable 的，使用后应关闭。
认证
在初始化阶段为每个客户端配置认证。支持三种认证方法：通过密码、通过访问令牌、通过 SSL 客户端证书。
通过密码认证需要调用 setUsername(String) 和 setPassword(String) 设置用户名和密码：
通过访问令牌认证需要调用 setAccessToken(String) 来设置访问令牌：
通过 SSL 客户端证书认证需要相应地调用 setUsername(String)、useSSLAuthentication(boolean)、setClientCertificate(String) 和 setClientKey(String) 设置用户名、启用 SSL 认证、设置客户端证书和客户端密钥：
在生产环境中，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"]}）。
- 从用户证书中获取 CN -
配置
所有设置通过实例方法（即配置方法）定义，这使得每个值的作用域和上下文变得清晰。主要配置参数在一个作用域（客户端或操作）中定义，并且不会相互覆盖。
配置在客户端创建时定义。请参见 com.clickhouse.client.api.Client.Builder。
客户端配置
| 配置方法 | 参数 | 描述 |
|---|---|---|
addEndpoint(String endpoint) | - endpoint - 格式为 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），在此之后连接将被视为不活动 |
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 cookies 并将其发送回服务器。 |
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 - 指示如果选项应启用的标志 | 大多数数据集包含编码为小字节序列的数字数据。默认情况下，读取器将分配所需的缓冲区，将数据读取到其中，然后转换为目标数字类。这可能会导致显著的 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。 |
useHTTPBasicAuth(boolean useBasicAuth) | - useBasicAuth - 指示如果选项应启用的标志 | 设置是否应使用基本 HTTP 认证进行用户-密码身份验证。默认启用。使用此类型的身份验证可以解决包含特殊字符的密码无法通过 HTTP 头传输的问题。 |
setClientName(String clientName) | - clientName - 表示应用程序名称的字符串 | 设置关于调用应用程序的附加信息。此字符串将作为客户端名称传递到服务器。在 HTTP 协议情况下，它将作为 User-Agent 头传递。 |
useBearerTokenAuth(String bearerToken) | - bearerToken - 编码的持有者令牌 | 指定是否使用持有者认证以及使用什么令牌。令牌将保持不变地发送，因此应在传递此方法之前进行编码。 |
常见定义
ClickHouseFormat
支持的 格式 的枚举。它包括 ClickHouse 支持的所有格式。
raw- 用户应转换原始数据full- 客户端可以自行转换数据，并接受原始数据流-- ClickHouse 不支持此格式的操作
此客户端版本支持：
插入 API
insert(String tableName, InputStream data, ClickHouseFormat format)
将数据作为指定格式的字节 InputStream 接受。预计 data 是以 format 编码的。
签名
参数
tableName - 目标表名称。
data - 编码数据的输入流。
format - 数据编码的格式。
settings - 请求设置。
返回值
InsertResponse 类型的 Future - 操作结果和额外信息，如服务器端指标。
示例
insert(String tableName, List<?> data, InsertSettings settings)
向数据库发送写入请求。对象列表被转换为高效格式，然后发送到服务器。列表项的类应通过 register(Class, TableSchema) 方法事先注册。
签名
参数
tableName - 目标表的名称。
data - DTO（数据传输对象）对象的集合。
settings - 请求设置。
返回值
InsertResponse 类型的 Future - 操作结果和额外信息，如服务器端指标。
示例
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 将持有指向应由读取器消耗的响应流的引用，以支持该格式。
签名
参数
sqlQuery - 单个 SQL 语句。查询以原样发送到服务器。
settings - 请求设置。
返回值
QueryResponse 类型的未来结果数据集和附加信息，如服务器端指标。在消费数据集后，应关闭响应对象。
示例
query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)
按原样发送 sqlQuery。此外，将发送查询参数，以便服务器可以编译 SQL 表达式。
签名
参数
sqlQuery - 带有占位符 {} 的 SQL 表达式。
queryParams - 用于补全服务器上 SQL 表达式的变量映射。
settings - 请求设置。
返回值
QueryResponse 类型的未来结果数据集和附加信息，如服务器端指标。在消费数据集后，应关闭响应对象。
示例
queryAll(String sqlQuery)
以 RowBinaryWithNamesAndTypes 格式查询数据。将结果作为集合返回。读取性能与读取器相同，但需要更多的内存来保存整个数据集。
签名
参数
sqlQuery - 从服务器查询数据的 SQL 表达式。
返回值
由 GenericRecord 对象列表表示的完整数据集，提供按行访问结果数据的功能。
示例
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() | 返回应用于处理响应中的日期/日期时间类型的时区。 |
Examples
Common API
getTableSchema(String table)
获取 table 的表架构。
签名
参数
table - 要获取架构数据的表名。
database - 定义目标表的数据库。
返回值
返回包含表列列表的 TableSchema 对象。
getTableSchemaFromQuery(String sql)
从 SQL 语句获取架构。
签名
参数
sql - 应返回其架构的 "SELECT" SQL 语句。
返回值
返回一个 TableSchema 对象，其中的列与 sql 表达式匹配。
TableSchema
register(Class<?> clazz, TableSchema schema)
为用于使用 schema 写入/读取数据的 Java 类编译序列化和反序列化层。该方法将为配对的 getter/setter 及相应列创建序列化器和反序列化器。
通过从方法名称中提取列名来找到列匹配。例如，getFirstName 将对应于列 first_name 或 firstname。
签名
参数
clazz - 代表用于读/写数据的 POJO 的类。
schema - 用于与 POJO 属性匹配的数据架构。
示例
Usage Examples
完整示例代码存储在 example 文件夹 中：
- client-v2 - 示例的主要集合。
- demo-service - 如何在 Spring Boot 应用程序中使用客户端的示例。
- demo-kotlin-service - 如何在 Ktor (Kotlin) 应用程序中使用客户端的示例。
