ADBC API 标准¶

本文档总结了 ADBC API 的通用功能集，仅供参考。

如需 ADBC API 的权威定义，请参考以下来源：

有关 C/C++ 的详细信息，请参阅 adbc.h。
有关 Go 的详细信息，请参阅源代码。
有关 Java 的详细信息，请参阅源代码，特别是 org.apache.arrow.adbc.core 包。

adbc.h 被视为权威标准。

数据库¶

数据库持有由多个连接共享的状态。通常，这意味着通用配置和缓存。对于内存数据库，它提供了一个持有内存数据库所有权的地方。

C/C++: AdbcDatabase
Go: Driver
Java: org.apache.arrow.adbc.core.AdbcDatabase

连接¶

连接是对数据库的单个逻辑连接。

C/C++: AdbcConnection
Go: Connection
Java: org.apache.arrow.adbc.core.AdbcConnection

自动提交¶

默认情况下，连接预期以自动提交模式运行；即查询在执行后立即生效。这可以被禁用以支持手动提交/回滚调用，但并非所有实现都支持这一点。

C/C++: ADBC_CONNECTION_OPTION_AUTOCOMMIT
Go: OptionKeyAutoCommit
Java: org.apache.arrow.adbc.core.AdbcConnection#setAutoCommit(boolean)

元数据¶

ADBC 公开关于数据库的各种元数据，例如存在的目录（catalog）、模式（schema）和表，以及表的 Arrow 模式等。

统计信息¶

注意

自 API 版本 1.1.0 起

ADBC 公开表/列统计信息，例如（唯一）行数、最小值/最大值等。其目标是使 ADBC 在联邦场景中工作得更好，即当一个查询引擎想要从另一个数据库读取 Arrow 数据时。拥有可用的统计信息可以让“外部”查询计划器在连接顺序等方面做出更好的选择，甚至决定完全跳过读取数据。

语句¶

语句持有与查询执行相关的状态。它们既代表一次性查询，也代表预编译语句（prepared statements）。它们可以被重用，尽管这样做会使该语句之前的记录集失效。（参见并发与线程安全。）

C/C++: AdbcStatement
Go: Statement
Java: org.apache.arrow.adbc.core.AdbcStatement

批量摄取¶

ADBC 提供显式工具将 Arrow 数据批次注入数据库表。对于支持此功能的数据库，这可以避免典型的绑定-插入循环带来的开销。此外，这（基本）使用户无需了解其数据库正确的 SQL 语法。

C/C++: ADBC_INGEST_OPTION_TARGET_TABLE 及相关选项。
Go: OptionKeyIngestTargetTable
Java: org.apache.arrow.adbc.core.AdbcConnection#bulkIngest(String, org.apache.arrow.adbc.core.BulkIngestMode)

取消¶

注意

自 API 版本 1.1.0 起

查询（以及隐式表示查询的操作，如获取统计信息）可以被取消。

分区结果集¶

ADBC 允许驱动程序向客户端显式公开分区和/或分布式记录集。（这类似于 Flight RPC/Flight SQL 中的功能。）客户端可以利用这一点将记录集上的计算分发到多个线程、进程或机器上。

C/C++: AdbcStatementExecutePartitions()
Go: Statement.ExecutePartitions
Java: org.apache.arrow.adbc.core.AdbcStatement#executePartitioned()

原则上，供应商可以按可用顺序返回分区执行的结果，而不是一次性返回。增量执行允许驱动程序实现这一点。启用后，每次调用 ExecutePartitions 将返回可用的读取端点，而不是阻塞以检索所有端点。

注意

自 API 版本 1.1.0 起

生命周期与使用¶

基本用法¶

../_images/AdbcStatementBasicUsage.mmd.svg — 预编译语句和绑定参数是可选的。¶

消费记录集¶

../_images/AdbcStatementConsumeResultSet.mmd.svg — 这等同于从许多 Arrow 库所称的 RecordBatchReader 进行读取。¶

批量数据注入¶

../_images/AdbcStatementBulkIngest.mmd.svg — 无需预编译语句。¶

仅更新查询（无记录集）¶

../_images/AdbcStatementUpdate.mmd.svg — 预编译语句和绑定参数是可选的。¶

分区执行¶

../_images/AdbcStatementPartitioned.mmd.svg — 这与 Arrow Flight RPC 中的数据获取类似（设计使然）。参见 “下载数据”。¶

错误处理¶

错误处理策略因语言而异。

在 C 语言中，大多数方法接收一个 AdbcError。在 Go 中，大多数方法返回一个可以转换为 AdbcError 的错误。在 Java 中，大多数方法抛出 AdbcException。

在所有情况下，错误都包含：

状态码，
错误消息，
可选的供应商代码（特定于供应商的状态码），
可选的 5 字符“SQLSTATE”代码（类似于 SQL 的供应商特定代码）。

丰富的错误元数据¶

注意

自 API 版本 1.1.0 起

驱动程序可以公开额外的丰富错误元数据。这可用于返回结构化的错误信息。例如，驱动程序可以使用类似 Googleapis ErrorDetails 的东西。

在 C、Go 和 Java 中，AdbcError、AdbcError 和 AdbcException 分别公开了一个附加元数据列表。对于 C，请参阅 AdbcError 的文档，了解如何在保持 ABI 的同时扩展该结构。

变更日志¶

版本 1.1.0¶

信息键 ADBC_INFO_DRIVER_ADBC_VERSION 可用于检索驱动程序支持的 ADBC 版本。

增加了规范选项“uri”、“username”和“password”，以使不同驱动程序之间的配置保持一致。

增加了取消功能，以及获取和设置不同类型选项的能力。（以前，可以设置字符串选项，但不能获取选项值或获取/设置其他类型的值。）这可用于通过一对新的规范选项来获取和设置当前活动的目录和/或模式。

批量注入支持两种附加模式：

“adbc.ingest.mode.replace” 将删除现有数据，然后表现得像“create”。
“adbc.ingest.mode.create_append” 将表现得像“create”，除非表已存在，此时它不会报错。

增加了丰富的错误元数据，允许客户端获取额外的错误元数据。

增加了检索表/列统计信息的功能。其目标是使 ADBC 在联邦场景中工作得更好，即当一个查询引擎想要从另一个数据库读取 Arrow 数据时。

增量执行允许在结果集分区可用时进行流式传输，而不是在读取结果之前阻塞并等待查询执行完成。