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 以一组扁平的头文件形式提供。每个头文件同时包含声明和实现,
并由一个哨兵宏保护。根据构建需要选择相应的头文件。
必需的服务器设置
将其添加到你的项目中
CHC_IMPLEMENTATION 并包含其实现;
其他所有单元都只包含相同的头文件,仅用于声明。
clickhouse.h 之前,定义 CHC_PROVIDE_STDLIB_ALLOC 以使用 chc_alloc_stdlib。
为 clickhouse-compression.h 定义 CHC_NO_LZ4 或 CHC_NO_ZSTD,以去除对 lz4/zstd 的依赖项。
通过 TCP 连接
chc_io 中,再将其传给
chc_client_init;它会同步执行 Hello 握手。该库不负责 DNS、
故障转移、重连或连接池管理——这些都由调用方处理。
chc_client 都是单线程的,只封装一个连接。该库会同步调用 chc_io
回调;这些回调在底层具体执行什么 (epoll、io_uring、
WaitLatchOrSocket) ,由你决定。
运行查询
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_validate。
chc_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,并压缩传出的数据包。压缩请求头提供了 LZ4 和 ZSTD 适配器;
每次初始化只会填充各自的 slots,因此请同时调用两者以支持任一种模式。
chc_codec;
vtable 在 clickhouse-compression.h 中声明。
TLS
clickhouse-openssl.h 提供了一个基于 SSL_read/SSL_write 的 chc_io 后端实现。OpenSSL 需要由你自行驱动:
该库不会创建 SSL_CTX、验证证书、设置 SNI,也不会调用 SSL_connect /
SSL_shutdown。等到 chc_io.read 被调用时,握手必须已经完成。
check_cancel 回调,该回调会在两次读取之间轮询;同时还支持通过 chc_openssl_io_set_deadline / chc_posix_io_set_deadline 设置
读取截止时间。
Ioless (异步) 客户端
clickhouse-async.h 是面向事件循环的 TCP 客户端的 ioless 变体。它完全不会接触
套接字:你只需提交已接收的字节,并取出它要发送的字节,自己驱动 epoll、
io_uring 或 WaitLatchOrSocket。它的选项、数据包类型以及块构建器都与
阻塞式客户端相同。
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 的 code、display_text 和 stack_trace。请仅将
chc_err 检查用于传输、protocol 和解码故障。
支持的数据类型
Int8–Int256,UInt8–UInt256Float32,Float64,BFloat16BoolDecimal32,Decimal64,Decimal128,Decimal256Date,Date32,DateTime,DateTime64,Time,Time64String,FixedString(N)UUID,IPv4,IPv6Enum8,Enum16Nullable(T),Array(T),Tuple(...),Map(K, V),Nested(...)LowCardinality(T)IntervalQBit(...)Point,Ring,Polygon,MultiPolygonSimpleAggregateFunction(f, T),解码后为其内部的TJSON和Object('json'),在字符串序列化下作为String列 (见下文)
JSON 和 Object('json') 在字符串序列化下解码;请在查询中设置
output_format_native_write_json_as_string=1。每个受支持的行都会以
CHC_COL_STRING 列中的一个 JSON 文档形式传入。使用 chc_build_string 构建相同形态;
写入器会输出已解析类型所需的前缀。
Variant、Dynamic、AggregateFunction 目前尚不支持解码,并会返回 CHC_ERR_TYPE;
可作为回退方案,在服务端将它们强制转换为 String。