跳转到主要内容
ADBC 驱动程序属于 Experimental 功能。其行为和选项可能会因发行版而异。
ADBC 是一种供应商中立的 API,用于在应用程序与数据库之间传输 Arrow 数据。chDB ADBC 驱动程序通过 ADBC Driver Foundry 分发,可由任何 ADBC 驱动程序管理器加载。 结果以 Arrow record batch 的形式传递,无需逐行转换。应用程序可通过 Python 或任何其他支持 ADBC 驱动程序管理器的语言使用同一驱动程序。

安装

使用 dbc 从 ADBC Driver Foundry 安装驱动程序:
chDB 发布的首个 dbc 软件包版本为 26.7.0。要查看可用版本,请运行:
可通过 ADBC 驱动程序管理器按名称 chdb 加载已安装的驱动程序。 支持在 x86-64 和 arm64 架构的 Linux 和 macOS 上运行。

通过 Python 连接

安装 Python ADBC 驱动程序管理器:
然后按名称加载通过 dbc 安装的 chDB 驱动程序:

连接生命周期

连接处于打开状态时,chDB 会在每个进程中运行一个嵌入式引擎。请注意以下规则:
  • 同一进程中所有同时打开的 ADBC 连接必须解析到相同的存储路径。
  • 支持多个连接访问该路径,包括由不同线程并发使用的连接。对于并发查询,请为每个工作线程使用独立的连接,而不要在同一个连接上同时执行多个操作。
  • 关闭最后一个连接会关闭嵌入式引擎。后续连接可以再次启动该引擎,也可以使用不同的存储路径,但反复关闭和启动会耗费时间和内存。需要重复执行操作时,请至少保持一个连接处于打开状态。
  • 同一时间,只有一个操作系统进程可以打开指定的磁盘目录。请为每个进程使用独立的目录,或使用内存数据库。

将 ADBC 与 Python chDB 包配合使用

dbc 包会安装独立的原生 ADBC 驱动程序。它与 Python chdb 包加载的原生库彼此独立。 在同一 Python 进程中,不应预期由 dbc 加载的 ADBC 连接与常规 chdb 连接会共享内存中的表或引擎状态。对于给定的数据库路径,同一时间只能使用 ADBC 驱动程序或 Python chdb API;不要让两者同时打开同一个磁盘路径。要在两个 API 之间传输数据,请先关闭其中一方的所有连接,再打开另一方,或者通过 Arrow 或文件显式传递数据。

已实现的功能

尚未支持 表示该 ADBC 驱动程序能力尚未实现,但后续可以添加。不适用 表示该功能不适用于当前的 chDB 或 ClickHouse 执行模型。

数据库

连接

语句

批量摄取支持 create、append、create_append 和 replace 模式,可写入默认 database 或指定 database。

ClickHouse SQL 和类型行为

chDB 使用 ClickHouse SQL 及其类型系统。通过 ADBC 访问 chDB 时,同样适用以下 ClickHouse 语义:
  • 列默认不允许为 NULL,除非声明为 Nullable(...)。绑定到普通 String 列的带类型 NULL 将存储为空字符串,而不是 NULL。
  • 使用 ClickHouse 标识符引用方式;示例中使用反引号。
  • ClickHouse 数据库映射到 ADBC db_schema。其上没有 catalog 层,因此不适用以 catalog 为作用域的操作。
  • Decimal 不接受负标度,Date32 的范围为 1900-01-01 至 2299-12-31。
  • 未指定时区的 DateTime64 会按 engine 时区解释。
  • 当前的 ClickHouse Arrow 输出不表示 Time 类型,因此无法通过 ADBC 读回。
某些 Arrow 类型会保留其值,但读回时会变为不同的 Arrow 类型: 二进制数据存储为 String,并按 UTF-8 读回。因此,非有效 UTF-8 的载荷不支持作为可往返转换的 binary 值。

示例

从 Arrow 批量摄取数据

参数

C

执行 dbc install chdb 后,C 驱动管理器可通过名称识别该驱动程序:

如何验证驱动程序

chDB ADBC 发布构建会在 Linux x86-64 和 arm64,以及 macOS x86-64 和 arm64 平台上,针对原生驱动程序运行两个外部测试套件:
  • Apache Arrow ADBC 一致性测试套件,用于检查 C 契约
  • ADBC Driver Foundry 验证测试套件,用于检查 SQL 层面的行为、类型往返转换、元数据和批量摄取
本页中的支持情况表基于这些测试结果。这些测试套件位于 chdb-core repository 中。