Skip to main content
clickhouse-c 是一个适用于 ClickHouse 原生协议的仅头文件 C 客户端。 源代码以及各头文件的参考文档位于 GitHub 仓库 与更高层的客户端不同,它是刻意只提供最少功能的。核心头文件通过你提供的 I/O 回调,对 Native 格式的块进行解码和编码。套接字、TLS 上下文、内存分配器、重试以及连接池都由你自己负责管理。因此它足够轻量,适合嵌入:仅包含 clickhouse.h 不会引入除 libc 之外的任何链接时依赖项。
该库仍在积极开发中。v1 可解码 ClickHouse 的核心类型。 如有局限或缺失的功能,请通过 issue tracker 反馈。 但也请理解,这个库按设计本就有意不提供某些功能。

该库不负责什么

以下这些是刻意不纳入范围的内容。请在你的应用程序中,或借助配套库来处理:
  • HTTP 协议。直接封装 libcurl 以使用 HTTP 接口
  • DNS 解析、端点故障转移、连接池、重试和退避。
  • TLS 上下文生命周期。OpenSSL 后端使用的是你已经建立连接的 SSL
  • 线程处理。每个 chc_client 在设计上都是单线程的。
  • 库内部的 async I/O。阻塞客户端会同步调用 chc_io.read。如果你需要 自身不执行任何 I/O 的事件循环客户端,请使用 ioless client

库的组织方式

clickhouse-c 以一组扁平的头文件形式提供。每个头文件同时包含声明和实现, 并由一个哨兵宏保护。根据构建需要选择相应的头文件。

必需的服务器设置

解码器从传输数据中读取可打印的类型名称,因此它们必须编码为文本。ClickHouse 默认会将它们以文本形式写出,但请在查询中显式固定此设置,以免将其设为二进制的 server 或 session profile 导致解码失败:

将其添加到你的项目中

无需安装任何包,因此你应通过 git 子模块或直接复制的方式,将这些头文件纳入你的源码树中。 恰好只能有一个翻译单元定义 CHC_IMPLEMENTATION 并包含其实现; 其他所有单元都只包含相同的头文件,仅用于声明。
在包含 clickhouse.h 之前,定义 CHC_PROVIDE_STDLIB_ALLOC 以使用 chc_alloc_stdlib。 为 clickhouse-compression.h 定义 CHC_NO_LZ4CHC_NO_ZSTD,以去除对 lz4/zstd 的依赖项。

通过 TCP 连接

要与 ClickHouse 服务器通信,你需要自行建立套接字,将其封装到 chc_io 中,再将其传给 chc_client_init;它会同步执行 Hello 握手。该库不负责 DNS、 故障转移、重连或连接池管理——这些都由调用方处理。
每个 chc_client 都是单线程的,只封装一个连接。该库会同步调用 chc_io 回调;这些回调在底层具体执行什么 (epollio_uringWaitLatchOrSocket) ,由你决定。

运行查询

发送查询,然后持续读取数据包,直到 CHC_PKT_END_OF_STREAM。使用 chc_client_send_query_ex 来 附带所需的服务器级设置;而不带扩展参数的 chc_client_send_query 会发送一个 空的 settings 列表,并继承服务器的默认设置。
服务器异常会以 CHC_PKT_EXCEPTION 数据包的形式到达,而不是作为 chc_client_recv_packet 的非 OK 返回值。只有传输层故障才会返回非 OK。结果中的第一个 CHC_PKT_DATA 数据包是一个头部块,用零行来描述 schema;后面才是数据块。 chc_packet_clear 会释放该数据包中的块或异常——如果要改为自行接管其所有权,请先将数据包上的这些字段设为 NULL。

读取列数据

块采用列式存储。每一列都有一个由 chc_column_layout 返回的物理布局, 你需要根据它进行分派处理;其声明类型由 chc_block_column_type 给出。复合布局可以嵌套,因此 读取 Nullable(Array(String)) 意味着要先解包 Nullable,遍历数组偏移量,然后 切分字符串数据。 下面是一个用于普通数值型、字符串和 Nullable 列的读取器:
CHC_COL_FIXED 数据在传输格式中采用小端序;在大端序主机上,你需要自行对多字节 整数进行字节交换。偏移量和 LowCardinality 键在解码时已转换为主机字节序。 UUIDs 由两个采用小端序的 UInt64 半部组成,IPv4 是一个 4 字节的小端序整数,而 IPv6 采用 网络字节序。DateTime64 的 ticks 是 UTC —— 类型中的 timezone 仅作为元数据。 从不受信任的 peer 摄取数据时,请在遍历每一列之前先调用 chc_column_validatechc_block_read 不会验证跨字段不变量,例如数组偏移量和 LowCardinality 键;否则,伪造的块可能会读取越过内部列边界的数据。

插入数据

使用 chc_build_* 辅助函数构建列,将其追加到 chc_block_builder,然后交给 chc_client_send_data。该构建器使用由调用方提供的存储空间,只记录指针而不进行 复制,因此这些存储空间、列树、类型、名称和 slab 的生命周期都必须长于发送过程。一次 INSERT 会发送 查询,等待服务器的头部块,发送一个或多个数据块,然后再发送一个空 块以终止该流。
chc_build_fixed 接收 n_rows * elem_size 个按小端序排列的字节;chc_build_string 接收打包 slab 上按主机字节序排列的累计 末尾偏移量 (不含结束位置) 。helpers 按值返回列节点。按类型要求嵌套它们:例如,将固定长度或字符串节点传给 chc_build_nullable,再将结果传给 chc_build_array,然后追加数组根节点。Tuple、 LowCardinality、Map 和 Geo 列使用相同的树结构:Map 是 Array(Tuple(K, V)) 一个块中的所有列都必须具有相同的顶层行数。写入器会根据 已解析的 ClickHouse 类型检查这棵树,但调用方必须为每次追加预先分配好 chc_block_col 的存储空间。 你也可以将从 chc_block_column 解码出的列直接追加回去以重新编码,或者调用 chc_block_write_cols 并传入 chc_block_col 数组来跳过 builder。通过 chc_client_send_data 而不是底层的 chc_block_write 传递 builder,可让 client 根据协商好的修订版本设置块 选项并应用压缩。

压缩

chc_client_opts 中传入压缩模式和已初始化的 codec。客户端会解压传入的 Data packets,并压缩传出的数据包。压缩请求头提供了 LZ4ZSTD 适配器; 每次初始化只会填充各自的 slots,因此请同时调用两者以支持任一种模式。
要使用项目未提供绑定的压缩库,请自行实现一个 chc_codec; vtable 在 clickhouse-compression.h 中声明。

TLS

clickhouse-openssl.h 提供了一个基于 SSL_read/SSL_writechc_io 后端实现。OpenSSL 需要由你自行驱动: 该库不会创建 SSL_CTX、验证证书、设置 SNI,也不会调用 SSL_connect / SSL_shutdown。等到 chc_io.read 被调用时,握手必须已经完成。
ClickHouse Cloud 和其他启用了 TLS 的部署都在 9440 端口上使用原生协议。两个后端都支持可选的 check_cancel 回调,该回调会在两次读取之间轮询;同时还支持通过 chc_openssl_io_set_deadline / chc_posix_io_set_deadline 设置 读取截止时间。

Ioless (异步) 客户端

clickhouse-async.h 是面向事件循环的 TCP 客户端的 ioless 变体。它完全不会接触 套接字:你只需提交已接收的字节,并取出它要发送的字节,自己驱动 epollio_uringWaitLatchOrSocket。它的选项、数据包类型以及块构建器都与 阻塞式客户端相同。 chc_async_client_init 不执行任何 I/O,也不会阻塞。后续的握手会以可恢复的 状态机方式运行,每次发送和接收也都是如此。当解析过程超出你已提交的字节时, 调用会返回 CHC_WOULD_BLOCK,而不是阻塞——提交更多入站字节后再次调用, 解析器会从块的中间继续解析。
你的 pump 负责双向传输字节。对于出站方向,chc_async_pending_out 会返回一个指针和长度, 指向队列中待发送的字节;套接字成功发送其中一部分后,调用 chc_async_consume_out 并传入该数量, 支持部分写入。对于入站方向,将从套接字读取的数据交给 chc_async_submit。发送操作永不阻塞,也不会产生 背压,因此要留意待发送数据的长度,并在其增长过大时停止继续发送。 一个可用的 liburing 驱动实现位于 test/test_async_uring.c

内存与分配器

每个入口点都会接收一个 chc_alloc vtable,因此内存分配遵循宿主环境所采用的机制。
在包含 clickhouse.h 之前定义 CHC_PROVIDE_STDLIB_ALLOC,并调用 chc_alloc_stdlib(),以使用 由标准 malloc 支持的分配器。

错误和服务器异常

函数会返回 CHC_OK (0) 或非零的 CHC_ERR_* 代码。该代码即返回值;由调用方在栈上分配的 chc_err 负责携带人类可读的消息。该库绝不会在堆上分配错误对象。
服务器端查询错误并不属于 chc_err 故障。它们会以 CHC_PKT_EXCEPTION 的形式通过 packet stream 传来,并携带 server 的 codedisplay_textstack_trace。请仅将 chc_err 检查用于传输、protocol 和解码故障。

支持的数据类型

块读取器可解码以下类型:
  • Int8Int256, UInt8UInt256
  • Float32, Float64, BFloat16
  • Bool
  • Decimal32, Decimal64, Decimal128, Decimal256
  • Date, Date32, DateTime, DateTime64, Time, Time64
  • String, FixedString(N)
  • UUID, IPv4, IPv6
  • Enum8, Enum16
  • Nullable(T), Array(T), Tuple(...), Map(K, V), Nested(...)
  • LowCardinality(T)
  • Interval
  • QBit(...)
  • Point, Ring, Polygon, MultiPolygon
  • SimpleAggregateFunction(f, T),解码后为其内部的 T
  • JSONObject('json'),在字符串序列化下作为 String 列 (见下文)
JSONObject('json') 在字符串序列化下解码;请在查询中设置 output_format_native_write_json_as_string=1。每个受支持的行都会以 CHC_COL_STRING 列中的一个 JSON 文档形式传入。使用 chc_build_string 构建相同形态; 写入器会输出已解析类型所需的前缀。 VariantDynamicAggregateFunction 目前尚不支持解码,并会返回 CHC_ERR_TYPE; 可作为回退方案,在服务端将它们强制转换为 String
最后修改于 2026年7月23日