用于通过协议与数据库服务器通信的 Java 客户端库。当前实现仅支持 HTTP interface。
该库提供了自有 API,用于向服务器发送请求,同时还提供了处理不同二进制数据格式 (RowBinary* & Native*) 的工具。
使用访问令牌或 Bearer 令牌 (例如 JWT) 进行身份验证,需要调用 通过 SSL 客户端证书进行身份验证,需要分别调用
将产生以下 应用程序可以设置自定义 HTTP 请求头 ⚠️ 当通过 重要:通过 如需按操作单独配置,请在 此后,该 参数参数参数参数参数参数参数参数集成方式应用程序集成可观测性主要有两种模式:V2 插入 TSV 格式数据。
设置
- Maven Central (项目页面) :https://mvnrepository.com/artifact/com.clickhouse/client-v2
- 每夜构建 (代码仓库链接) :https://central.sonatype.com/repository/maven-snapshots/
- Maven
- Gradle (Kotlin)
- Gradle
初始化
Client 对象通过com.clickhouse.client.api.Client.Builder#build() 初始化。每个客户端拥有独立的上下文,客户端之间不共享任何对象。
Builder 提供了多种配置方法,方便快速完成设置。示例:showLineNumbers
Client 实现了 AutoCloseable 接口,不再需要时应将其关闭。身份验证
身份验证在初始化阶段按客户端进行配置。支持三种身份验证方法:密码、访问令牌以及 SSL 客户端证书。通过密码进行身份验证需要调用setUsername(String) 和 setPassword(String) 来设置用户名和密码:showLineNumbers
useBearerTokenAuth(String) 来设置令牌 (对于原始访问令牌,则调用 setAccessToken(String)) :showLineNumbers
setUsername(String)、useSSLAuthentication(boolean)、setClientCertificate(String) 和 setClientKey(String) 来设置用户名、启用 SSL 身份验证、设置客户端证书和客户端密钥:showLineNumbers
在生产环境中,SSL 身份验证往往很难排查,因为 SSL 库返回的很多错误信息都不够充分。例如,如果客户端证书与密钥不匹配,server 会立即终止 connection (对于 HTTP,这会发生在 connection 建立阶段,此时还不会发送任何 HTTP request,因此也不会返回任何响应) 。请使用 openssl 等工具验证证书和密钥:
- 检查密钥完整性:
openssl rsa -in [key-file.key] -check -noout - 检查客户端证书是否包含与用户匹配的 CN:
- 从用户证书中获取 CN:
openssl x509 -noout -subject -in [user.cert] - 验证 database 中是否设置了相同的值:
select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'(该查询会输出auth_params,类似{"common_names":["some_user"]})
- 从用户证书中获取 CN:
连接池
Client 使用 Apache HttpClient 5,并内置 HTTP 连接池。每个操作都会从连接池中借用一个连接,发送请求,以流式方式读取响应,然后将该连接归还到连接池。Client.Builder 中的主要连接池设置:推荐的连接池配置
showLineNumbers
配置
所有设置均通过实例方法 (即配置方法) 定义,使每个值的作用域和上下文一目了然。 主要配置参数在单一作用域 (客户端或操作) 内定义,彼此之间不会相互覆盖。配置在客户端创建时定义。请参阅com.clickhouse.client.api.Client.Builder。客户端配置
- 连接与端点
- 身份验证
- 超时与重试
- 套接字选项
- 压缩
- SSL/安全
- 代理
- HTTP 和请求头
- 服务器设置
- 时区
- 高级
客户端识别
查询日志中有两个字段用于标识发起请求的应用程序:client_name 和 http_user_agent。Native TCP 协议使用 client_name 标识应用程序,HTTP 协议使用 http_user_agent 标识应用程序。Client builder 提供了 setClientName 方法,可为两种协议正确设置相应的值。
字段 http_user_agent 遵循 User-Agent 请求头的通用格式:application-name[/version] [(operating-system; architecture; ...)]。
这组值会在每个 layer 中重复出现:应用程序层、客户端库层、HTTP 客户端库层。由 setClientName 方法设置的内容在列表中排在最前面。例如:showLineNumbers
http_user_agent 值:User-Agent 来标识自身,但 clickhouse-java-v2/0.9.6-SNAPSHOT 部分会自动追加到该请求头的末尾。操作标识
查询日志还有另外两个字段query_id 和 log_comment,可用于标识操作并向查询日志添加额外信息。query_id 是操作的唯一标识符。应用程序可通过调用 QuerySettings 类的 setQueryId 方法来设置该值。showLineNumbers
log_comment 是一个可以添加到查询日志中的注释。应用程序可以通过调用 QuerySettings 类的 logComment 方法来设置此注释。showLineNumbers
服务器设置
服务器端配置可以在创建客户端时统一设置 (参见Builder 的 serverSetting 方法) ,也可以在操作级别单独设置 (参见操作配置类的 serverSetting) 。showLineNumbers
setOption 方法 (Client.Builder 或操作设置类) 设置选项时,server settings 名称应加上 clickhouse_setting_ 前缀。此时 com.clickhouse.client.api.ClientConfigProperties#serverSetting() 会很有帮助。自定义 HTTP 请求头
可以为所有操作 (客户端级别) 或单个操作 (操作级别) 设置自定义 HTTP 请求头。操作级设置会覆盖客户端级别中的同名请求头。showLineNumbers
setOption (Client.Builder 或操作设置类) 设置选项时,请求头名称应以 http_header_ 为前缀。可使用 ClientConfigProperties.httpHeader(String) 生成该键。
由于请求头名称只是普通的 String 键,其大小写必须统一,否则重复的值会导致未定义行为。ClientConfigProperties.httpHeader(String) 可以解决这一问题。showLineNumbers
ClickHouse Cloud 功能
连接到 ClickHouse Cloud 时适用的功能。副本感知路由 (CLOUD)
ClickHouse Cloud 可以将相关的 HTTP 请求固定路由到同一副本。在请求中携带X-ClickHouse-Replica-Tag 请求头,即可让 Cloud proxy 将具有相同标签的所有请求路由到同一副本。此功能适用于使用临时表等会话作用域内的对象、复用副本本地缓存或确保写后读一致性等场景。
了解更多:https://clickhouse.com/docs/products/cloud/features/infrastructure/replica-aware-routing。设置内容: HTTP 请求头 X-ClickHouse-Replica-Tag (com.clickhouse.client.api.http.ClickHouseHttpProto.HEADER_REPLICA_TAG) 。对于应始终由同一副本处理的所有请求,请使用相同的标签值。showLineNumbers
QuerySettings、InsertSettings 或 CommandSettings 上设置该请求头,而非在客户端构建器上设置。JWT 身份验证 (CLOUD)
JWT 身份验证支持在 ClickHouse Cloud 中使用 JSON Web Token (JWT) 对用户进行身份验证。ClickHouse 无需预先创建数据库用户,而是根据每个令牌中携带的声明动态创建临时用户。初始配置
要在客户端上配置初始 JWT 身份验证,请在构建Client 实例时使用 useBearerTokenAuth(token) (该方法会自动添加 Bearer_ 前缀。
(参见 HTTP 接口文档) :showLineNumbers
useBearerTokenAuth(token) 会自动为 Authorization HTTP 请求头的值加上 Bearer 前缀。在运行时更新令牌
由于 JWT 的有效期较短,且临时用户仅在令牌的生命周期内存在,因此应在当前令牌过期之前设置新的 JWT 令牌,以免操作失败。您可以在运行时直接更新现有Client 实例的 Bearer 令牌,而无需重新创建客户端:showLineNumbers
Client 实例上的所有请求都将使用更新后的 JWT 令牌。常用定义
ClickHouseFormat
支持格式的枚举类型,包含 ClickHouse 支持的所有格式。raw- 用户应对原始数据进行转码full- 客户端可以自行转码数据,并接收原始数据流-- ClickHouse 不支持此格式的该操作
插入 API
insert(String tableName, InputStream data, ClickHouseFormat format)
以指定格式接受字节InputStream 形式的数据。data 须以 format 指定的格式进行编码。签名tableName - 目标表名称。data - 已编码数据的输入流。format - 数据编码所使用的格式。settings - 请求设置。返回值InsertResponse 类型的 Future——操作结果及附加信息,例如服务器端指标。示例showLineNumbers
insert(String tableName, List<?> data, InsertSettings settings)
向数据库发送写请求。对象列表将被转换为高效格式后发送至服务器。列表项的类需要预先通过register(Class, TableSchema) 方法注册。签名tableName - 目标表的名称。data - DTO (数据传输对象) 对象集合。settings - 请求设置。返回值InsertResponse 类型的 Future——包含操作结果及服务端指标等附加信息。示例showLineNumbers
InsertSettings
插入操作的配置选项。配置方法InsertResponse
保存插入操作结果的响应对象。仅在客户端收到服务器响应时可用。应尽快关闭此对象以释放连接,因为在完全读取前一个响应的所有数据之前,该连接无法重新使用。
查询 API
格式选择Client 提供对服务器响应流的透明访问。用户可以在请求中自由选择任何 ClickHouse 格式,并通过QueryResponse 对象中的 InputStream
读取数据。
可通过以下方式指定格式:QuerySettings#setFormat()用于设置请求中指定格式的请求头。- 在查询本身的
FORMAT子句中设置。 - 服务器设置
default_format(/reference/settings/session-settings/default#default_format)
- Client <
0.11.0& ClickHouse <26.8-FORMAT子句的优先级高于请求中的格式请求头。 - Client >
0.11.0& ClickHouse >26.8- 请求头的优先级高于FORMAT子句。- 当
QuerySettings中未指定格式时,客户端会设置请求头,导致无法在查询中覆盖格式。
- 当
- 从
0.11.0版本开始,客户端在客户端级别而非操作级别设置默认的format值。这样,现有代码 无需修改即可正常运行,而新代码则可以通过将客户端的format设置为null来使用FORMAT子句。
query(String sqlQuery)
按原样发送sqlQuery。响应格式由查询设置决定。QueryResponse 将保存对响应流的引用,该流应由支持相应格式的读取器 (reader) 读取。签名sqlQuery - 单条 SQL 语句。该查询会按原样发送到服务器。settings - 请求设置。返回值QueryResponse 类型的 Future——包含结果数据集及服务端指标等附加信息。消费完数据集后,应关闭 Response 对象。示例query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)
按原样发送sqlQuery,同时发送查询参数,以便服务器编译 SQL 表达式。签名sqlQuery - 带占位符 {} 的 SQL 表达式。queryParams - 用于在服务器端补全 SQL 表达式的变量映射。settings - 请求设置。返回值QueryResponse 类型的 Future——包含结果数据集及服务端指标等附加信息。消费完数据集后,应关闭 Response 对象。示例showLineNumbers
queryAll(String sqlQuery)
以RowBinaryWithNamesAndTypes 格式查询数据,并以集合形式返回结果。读取性能与使用 reader 时相同,但需要占用更多内存来存储完整的数据集。签名sqlQuery - 用于从服务器查询数据的 SQL 表达式。返回值完整数据集,由一组 GenericRecord 对象列表表示,以行方式访问结果数据。示例showLineNumbers
QuerySettings
查询操作的配置选项。配置方法QueryResponse
保存查询执行结果的响应对象。仅当客户端收到来自服务器的响应时,该对象才可用。应尽快关闭此对象以释放连接,因为在完全读取前一个响应的所有数据之前,该连接无法重新使用。
示例
通用 API
getTableSchema(String table)
获取table 的 schema。签名table - 需要拉取 schema 数据的表名。database - 目标表所在的数据库。返回值返回一个包含表列列表的 TableSchema 对象。getTableSchemaFromQuery(String sql)
从 SQL 语句中拉取 schema。签名sql - 需要返回其 schema 的 “SELECT” SQL 语句。返回值返回一个 TableSchema 对象,其列与 sql 表达式相匹配。TableSchema
register(Class<?> clazz, TableSchema schema)
为 Java 类编译序列化与反序列化 layer,以便通过schema 进行数据读写。该 method 将为 getter/setter 对及其对应列创建序列化器和反序列化器。
列的匹配通过从方法名中提取列名来实现。例如,getFirstName 对应的列为 first_name 或 firstname。签名clazz - 表示用于读取/写入数据的 POJO 的类。schema - 用于匹配 POJO 属性的 schema。示例showLineNumbers
使用示例
完整的示例代码存放在代码仓库的 ‘example` 文件夹中:- client-v2 - 主要示例。
- demo-service - 展示如何在 Spring Boot 应用程序中使用该客户端的示例。
- demo-kotlin-service - 在 Ktor (Kotlin) 应用中使用客户端的示例。
读取数据
读取数据有两种常见方式:- 返回底层
QueryResponse对象的query()方法,该对象包含带有数据的InputStream。通常会结合ClickHouseBinaryFormatReader用于流式读取,但 也可搭配任何其他自定义 reader 实现使用。QueryResponse还提供对结果集元数据和指标的访问。 queryAll()方法,并使用GenericRecord以便更方便地访问行。在这种情况下,整个结果集都会加载到内存中。- 返回
com.clickhouse.client.api.query.Records的queryRecords()方法——它是一个用于遍历GenericRecord对象的迭代器。该方法采用流式方式 (不会将任何数据加载到内存中) ,并通过GenericRecord访问数据。
读取数组
ClickHouseBinaryFormatReader 方法getList(...)- 将任意Array(...)读取为List<T>。这是灵活类型读取的默认推荐选择。支持嵌套数组。getByteArray(...),getShortArray(...),getIntArray(...),getLongArray(...),getFloatArray(...),getDoubleArray(...),getBooleanArray(...)- 最适合用于包含与基本类型兼容值的一维数组。getStringArray(...)- 用于Array(String)(以及以名称形式表示的枚举值) 。getObjectArray(...)- 适用于任意Array(...)元素类型的通用选项,包括嵌套数组。可用于读取包含 Nullable 值和嵌套数组的数组。
GenericRecord 方法getList(...)- 将任意Array(...)读取为List<T>。这是灵活类型读取的默认推荐选择。支持嵌套数组。getByteArray(...),getShortArray(...),getIntArray(...),getLongArray(...),getFloatArray(...),getDoubleArray(...),getBooleanArray(...)- 最适合用于包含与基本类型兼容值的一维数组。getStringArray(...)- 用于Array(String)(以及以名称形式表示的枚举值) 。getObjectArray(...)- 适用于任意Array(...)元素类型的通用选项,包括嵌套数组。可用于读取包含 Nullable 值和嵌套数组的数组。
可观测性与监控
ClickHouse Java 客户端 (V2) 内置了基于 OpenTelemetry 语义约定和 Micrometer 指标设计的可观测性功能,支持监控操作耗时、吞吐量、重试情况、服务器执行统计信息、连接池状态以及分布式链路追踪 span。本代码仓库中的examples/demo-spring-service 模块提供了一个完整的生产级 Spring Boot 应用程序,演示了客户端 V2 配置、连接池、跨 @Async 边界的追踪上下文传播以及完整的遥测数据集成,请参阅该模块了解详情。Client Builder 可观测性 API
Client.Builder 提供了三个主要方法,用于配置可观测性和指标采集:setMetricsRecorder(MetricsRecorder recorder):注册指标记录器,用于导出操作指标 (耗时、计数、重试、错误) 。未显式设置时,默认使用DefaultMetricsRecorder.NOOP。setSpanRecorder(SpanRecorder recorder):注册跨度记录器,用于分布式链路追踪 (操作 span 和传输请求 span) 。未显式设置时,默认使用DefaultSpanRecorder.NOOP。registerClientMetrics(Object registry, String groupName):将 Apache HttpClient 连接池指标 (例如可用连接数、已借出的连接数、待处理请求数以及连接创建耗时) 绑定到 MicrometerMeterRegistry。
OpenTelemetrySpanRecorder 和 MicrometerMetricsRecorder 类随 client-v2 软件包一同提供,但它们在运行时要求应用程序的 classpath 中包含 OpenTelemetry API (io.opentelemetry:opentelemetry-api) 和 Micrometer (io.micrometer:micrometer-core) 库。主客户端制品既不会打包这些第三方依赖项,也不会通过传递依赖引入它们。使用 OpenTelemetry 追踪或 Micrometer 指标的应用程序,必须在项目构建配置 (pom.xml 或 build.gradle) 中显式声明这些依赖项。构建器配置示例- OpenTelemetry Agent & 全局自动配置:
- 对于使用 OpenTelemetry Java 代理或全局 SDK 自动配置的应用程序,请使用默认的无参构造函数实例化
OpenTelemetrySpanRecorder和MicrometerMetricsRecorder。 - 默认构造函数会自动绑定到
GlobalOpenTelemetry.get()和 Micrometer 的Metrics.globalRegistry。
- 对于使用 OpenTelemetry Java 代理或全局 SDK 自动配置的应用程序,请使用默认的无参构造函数实例化
- 显式客户端级集成:
- 将显式创建的
OpenTelemetry、Tracer或 MicrometerMeterRegistry实例直接传入 recorder 构造函数。 - 适合管理多个相互隔离的客户端,或各自拥有独立遥测数据接收端的多租户服务。
- 将显式创建的
上报的指标
运行指标
通过MetricsRecorder 导出的指标遵循 OpenTelemetry 针对数据库客户端指标的语义约定 (MetricName 和 MetricAttribute) :指标属性 / 标签
由MicrometerMetricsRecorder 创建的 Meter 带有低基数标签 (MetricAttribute):连接池指标
调用registerClientMetrics(meterRegistry, "groupName") 时,HTTP 连接池的 Gauge 指标会注册到 Micrometer:httpcomponents.httpclient.pool.total.max:配置的最大持久连接数。httpcomponents.httpclient.pool.total.connections(带有标签state="available"或state="leased") :连接池中的活跃连接数。httpcomponents.httpclient.pool.total.pending:正在等待空闲连接的连接请求数。httpcomponents.httpclient.pool.route.max.default:配置的每个路由默认最大连接数。httpcomponents.httpclient.connect.time:建立连接耗时的滚动平均值。
响应指标 API
除指标记录器外,还可以通过OperationMetrics 直接在响应对象 (QueryResponse、InsertResponse) 上获取详细的执行统计信息:上报的 span
Client V2 中的追踪会生成两种类型的 span,二者按父子层次结构组织:- 操作跨度 (Operation Span):表示高层级的客户端操作 (
QUERY <database>或INSERT <database>.<table_name>) 。该跨度在当前线程的追踪上下文 (Context.current()) 中启动,使数据库操作能够加入调用方当前活跃的 trace span。 - 传输请求跨度 (Transport Request Span):表示单次 HTTP 传输请求尝试 (
POST) 。该跨度作为对应操作跨度的子跨度创建。每次重试都会在操作跨度下新建一个传输请求跨度。
跨度属性
span 中包含标准 OpenTelemetry 属性 (SpanAttribute) :跨异步边界传播上下文: 由于客户端 V2 会继承
Context.current() 中的上下文,在线程上启动的操作会自动加入该线程当前 trace span 所属的 trace。在将任务委派给其他线程池时 (例如使用 Spring @Async 或自定义 ExecutorService) ,请显式传播 OpenTelemetry 上下文:开发自定义 Recorder
如果应用程序使用自定义的可观测性后端,可以通过扩展DefaultMetricsRecorder (用于指标) 或 DefaultSpanRecorder (用于追踪) 来实现自定义记录器。DefaultMetricsRecorder:MetricsRecorder的基础实现。可覆盖recordQuerySuccess或recordQueryFailure等特定回调函数。可使用MetricsSupport.DEFAULT生成标准指标名称 (MetricName) 、单位以及属性 Map (MetricAttribute) 。DefaultSpanRecorder:SpanRecorder的基础实现。可覆盖startQuerySpan、startInsertSpan或startRequestSpan等用于创建跨度的回调函数。可使用SpanSupport.DEFAULT计算标准 OpenTelemetry 跨度名称和属性 (SpanAttribute) 。
com.clickhouse.client.api.observability.otel.OpenTelemetrySpanRecorder(OpenTelemetry 追踪集成)com.clickhouse.client.api.observability.micrometer.MicrometerMetricsRecorder(Micrometer 指标集成)
迁移指南
旧版客户端 (V1) 以com.clickhouse.client.ClickHouseClient#builder 作为起点。新版客户端 (V2) 采用类似的模式,使用 com.clickhouse.client.api.Client.Builder。主要区别如下:- 未使用服务加载器来获取具体实现。
com.clickhouse.client.api.Client是一个门面类,未来可适配各种实现。 - 配置来源更少:一类提供给构建器,另一类在操作设置 (
QuerySettings、InsertSettings) 中。先前版本会为每个节点分别配置,并且在某些情况下会加载 环境变量。
配置参数匹配
V1 中有 3 个与配置相关的枚举类:com.clickhouse.client.config.ClickHouseDefaults- 在大多数用例中都应设置的配置参数,例如USER和PASSWORD。com.clickhouse.client.config.ClickHouseClientOption- 客户端特有的配置参数,例如HEALTH_CHECK_INTERVAL。com.clickhouse.client.http.config.ClickHouseHttpOption- HTTP 接口专用的配置参数,例如RECEIVE_QUERY_PROGRESS。
com.clickhouse.client.config.ClickHouseDefaults#ASYNC 与
com.clickhouse.client.config.ClickHouseClientOption#ASYNC 之间究竟有何区别?) 。新的 V2 客户端以 com.clickhouse.client.api.Client.Builder 作为所有可用客户端配置选项的统一字典。所有配置参数名称均列于
com.clickhouse.client.api.ClientConfigProperties 中。下表列出了新客户端中支持的旧选项及其新含义。图例: ✔ = 支持,✗ = 已丢弃- 连接与认证
- SSL 与安全
- 套接字选项
- 压缩
- 代理
- 超时与重试
- 时区
- 缓冲区与性能
- 线程与异步
- HTTP 和请求头
- 格式与查询
- 节点发现与负载均衡
- 杂项
主要差异
- Client V2 使用更少的专有类,以提高可移植性。例如,V2 可配合
java.io.InputStream的任何实现来 将数据写入服务器。 - Client V2 的
async设置默认值为off。这意味着不会额外创建线程,且应用程序对客户端有更强的控制能力。对于绝大多数用例,此设置都应保持为off。启用async会为每个请求创建一个单独的线程。只有在使用由应用程序控制的 executor 时,这样做才有意义 (请参见com.clickhouse.client.api.Client.Builder#setSharedOperationExecutor)
写入数据
- 可使用
java.io.InputStream的任何实现。支持 V1com.clickhouse.data.ClickHouseInputStream,但不建议使用。 - 一旦检测到输入流结束,就会进行相应处理。在此之前,应关闭请求的输出流。
- 只需调用一个方法。无需另外创建请求对象。
- 请求体流会在所有数据复制完毕后自动关闭。
- 现已提供新的底层 API:
com.clickhouse.client.api.Client#insert(java.lang.String, java.util.List<java.lang.String>, com.clickhouse.client.api.DataStreamWriter, com.clickhouse.data.ClickHouseFormat, com.clickhouse.client.api.insert.InsertSettings)。com.clickhouse.client.api.DataStreamWriter用于实现自定义的数据写入逻辑。例如,从 队列中读取数据。
读取数据
- 默认使用
RowBinaryWithNamesAndTypes格式读取数据。当前在需要进行数据绑定时,仅支持此格式。 - 可以使用
List<GenericRecord> com.clickhouse.client.api.Client#queryAll(java.lang.String)方法,将数据作为记录集合读取。它会将数据读入内存并释放连接,无需额外处理。GenericRecord提供对数据的访问,并支持一些类型转换。