> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 将 chDB 用作 ADBC 驱动程序

> 如何通过 Arrow Database Connectivity (ADBC) 使用 chDB

export const ExperimentalBadge = () => {
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#experimental-features" className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Experimental 功能
        </a>;
};

<ExperimentalBadge />

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

[ADBC](https://arrow.apache.org/adbc/) 是一种供应商中立的 API，用于在应用程序与数据库之间传输 Arrow 数据。chDB ADBC 驱动程序通过 ADBC Driver Foundry 分发，可由任何 ADBC 驱动程序管理器加载。

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

<div id="installation">
  ## 安装
</div>

使用 [`dbc`](https://docs.columnar.tech/dbc/) 从 ADBC Driver Foundry 安装驱动程序：

```bash theme={null}
dbc install chdb
```

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

```bash theme={null}
dbc search -v chdb
```

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

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

<div id="connecting-from-python">
  ## 通过 Python 连接
</div>

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

```bash theme={null}
pip install adbc-driver-manager pyarrow
```

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

```python theme={null}
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` | 存储在磁盘上，并持久化到指定目录中 |

<div id="connection-lifecycle">
  ## 连接生命周期
</div>

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

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

<div id="using-python-chdb-package">
  ### 将 ADBC 与 Python chDB 包配合使用
</div>

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

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

<div id="implemented-functionality">
  ## 已实现的功能
</div>

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

<div id="database">
  ### 数据库
</div>

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

<div id="connection">
  ### 连接
</div>

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

<div id="statement">
  ### 语句
</div>

| 函数                                 | 状态   | 备注                                        |
| ---------------------------------- | ---- | ----------------------------------------- |
| `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。

<div id="clickhouse-sql-and-type-behavior">
  ## ClickHouse SQL 和类型行为
</div>

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

<div id="examples">
  ## 示例
</div>

<div id="bulk-ingestion">
  ### 从 Arrow 批量摄取数据
</div>

```python theme={null}
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())
```

<div id="parameters">
  ### 参数
</div>

```python theme={null}
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())
```

<div id="c-example">
  ### C
</div>

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

```c theme={null}
#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);
```

<div id="verification">
  ## 如何验证驱动程序
</div>

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

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

本页中的支持情况表基于这些测试结果。这些测试套件位于 [chdb-core repository](https://github.com/chdb-io/chdb-core/tree/main/programs/local/adbc/validation) 中。