将 chDB 用作 ADBC 驱动程序

ADBC 驱动程序属于 Experimental 功能。其行为和选项可能会因发行版而异。

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 连接

安装 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())

`uri`	数据库
`chdb://`	内存中
`chdb:///absolute/path`	存储在磁盘上，并持久化到指定目录中

连接生命周期

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

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

将 ADBC 与 Python chDB 包配合使用

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

已实现的功能

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

数据库

函数	状态	说明
`AdbcDatabaseNew` / `Init` / `Release`	支持
`AdbcDatabaseSetOption`	支持	`uri`、`path` 和 `chdb.*` 引擎选项

连接

函数	状态	说明
`AdbcConnectionNew` / `Init` / `Release`	支持
`AdbcConnectionGetInfo`	支持
`AdbcConnectionGetObjects`	支持	支持所有深度
`AdbcConnectionGetTableSchema`	支持
`AdbcConnectionGetTableTypes`	支持
`AdbcConnectionGetOption`	支持	包含当前的 `db_schema`
`AdbcConnectionSetOption`	部分支持	必须启用自动提交；不支持更改 `db_schema`
`AdbcConnectionCommit` / `Rollback`	不适用	ClickHouse 语句自动提交；没有可提交或回滚的传统事务
`AdbcConnectionGetStatistics`	尚未支持	驱动不提供表统计信息
`AdbcConnectionReadPartition`	不适用	驱动不生成分布式结果分区
`AdbcConnectionCancel`	尚未支持	ADBC 尚不支持通过 chDB 取消查询

语句

函数	状态	备注
`AdbcStatementNew` / `Release`	支持
`AdbcStatementSetSqlQuery`	支持	ClickHouse SQL
`AdbcStatementPrepare`	支持
`AdbcStatementBind` / `BindStream`	支持	位置参数 `?`
`AdbcStatementGetParameterSchema`	支持
`AdbcStatementExecuteQuery`	支持	流式传输 Arrow record batch
`AdbcStatementSetOption`	支持	批量摄取，见下文
`AdbcStatementExecuteSchema`	尚未支持	执行后目前可获取结果 schema
`AdbcStatementExecutePartitions`	不适用	结果以进程内 Arrow stream 的形式返回
`AdbcStatementSetSubstraitPlan`	不适用	chDB 接受 ClickHouse SQL，不接受 Substrait plan
`AdbcStatementCancel`	尚未支持	ADBC 尚未提供 chDB 查询取消功能

批量摄取支持 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 类型：

Arrow 类型	存储为	读回为
`binary`, `large_binary`, `binary_view`	`String`	`string`
`fixed_size_binary` (批量摄取到新表)	`FixedString(n)`	`fixed_size_binary`
`large_string`, `string_view`	`String`	`string`
`float16`	`Float32`	`float`
`time32` / `time64` / `timestamp`	`DateTime64(n)`	`timestamp`

二进制数据存储为 String，并按 UTF-8 读回。因此，非有效 UTF-8 的载荷不支持作为可往返转换的 binary 值。

示例

从 Arrow 批量摄取数据

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())

C

执行 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 中。

开始使用

语言集成

DataStore

配置

调试

开发者指南

技术参考文档

安装

通过 Python 连接

连接生命周期

将 ADBC 与 Python chDB 包配合使用

已实现的功能

数据库

连接

语句

ClickHouse SQL 和类型行为

示例

从 Arrow 批量摄取数据

参数

C

如何验证驱动程序

​安装

​通过 Python 连接

​连接生命周期

​将 ADBC 与 Python chDB 包配合使用

​已实现的功能

​数据库

​连接

​语句

​ClickHouse SQL 和类型行为

​示例

​从 Arrow 批量摄取数据

​参数

​C

​如何验证驱动程序

安装

通过 Python 连接

连接生命周期

将 ADBC 与 Python chDB 包配合使用

已实现的功能

数据库

连接

语句

ClickHouse SQL 和类型行为

示例

从 Arrow 批量摄取数据

参数

C

如何验证驱动程序