将 chDB 用作 ADBC 驱动程序

ADBC 是一种供应商中立的 API，用于在应用程序与数据库之间传输 Arrow 数据。chDB ADBC 驱动程序通过 ADBC Driver Foundry 分发，可由任何 ADBC 驱动程序管理器加载。

结果以 Arrow record batch 的形式传递，无需逐行转换。应用程序可通过 Python 或任何其他支持 ADBC 驱动程序管理器的语言使用同一驱动程序。

使用 dbc 从 ADBC Driver Foundry 安装驱动程序：

dbc install chdb

chDB 发布的首个 dbc 软件包版本为 26.7.0。要查看可用版本，请运行：

dbc search -v chdb

可通过 ADBC 驱动程序管理器按名称 chdb 加载已安装的驱动程序。

支持在 x86-64 和 arm64 架构的 Linux 和 macOS 上运行。

安装 Python ADBC 驱动程序管理器：

pip install adbc-driver-manager pyarrow

然后按名称加载通过 dbc 安装的 chDB 驱动程序：

from adbc_driver_manager import dbapi

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT number FROM numbers(3)")
        print(cur.fetch_arrow_table())

连接处于打开状态时，chDB 会在每个进程中运行一个嵌入式引擎。请注意以下规则：

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

dbc 包会安装独立的原生 ADBC 驱动程序。它与 Python chdb 包加载的原生库彼此独立。

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

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

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

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 值。

import pyarrow as pa

from adbc_driver_manager import dbapi

table = pa.table({"id": [1, 2, 3], "name": ["a", "b", "c"]})

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.adbc_ingest("events", table, mode="create")
        cur.execute("SELECT count() FROM events")
        print(cur.fetchone())

from adbc_driver_manager import dbapi

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT number FROM numbers(10) WHERE number > ?", (7,))
        print(cur.fetch_arrow_table())

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

#include <arrow-adbc/adbc.h>
#include <arrow-adbc/adbc_driver_manager.h>

struct AdbcDatabase database = {0};
struct AdbcError error = {0};

AdbcDatabaseNew(&database, &error);
AdbcDatabaseSetOption(&database, "driver", "chdb", &error);
AdbcDatabaseSetOption(&database, "uri", "chdb://", &error);
AdbcDatabaseInit(&database, &error);

chDB ADBC 发布构建会在 Linux x86-64 和 arm64，以及 macOS x86-64 和 arm64 平台上，针对原生驱动程序运行两个外部测试套件：

• Apache Arrow ADBC 一致性测试套件，用于检查 C 契约
• ADBC Driver Foundry 验证测试套件，用于检查 SQL 层面的行为、类型往返转换、元数据和批量摄取

本页中的支持情况表基于这些测试结果。这些测试套件位于 chdb-core repository 中。