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 暴露了关于数据库的各种元数据，例如存在哪些目录、模式和表，表的 Arrow 模式等等。

统计数据¶

注意

自 API 1.1.0 版起

ADBC 暴露了表/列统计数据，例如（唯一）行数、最小/最大值等。此处的目的是使 ADBC 在联合场景中更好地工作，其中一个查询引擎希望从另一个数据库读取 Arrow 数据。拥有可用的统计数据可以让“外部”查询计划器更好地选择连接顺序等，甚至决定完全跳过读取数据。

语句¶

语句保存与查询执行相关的状态。它们表示一次性查询和预编译语句。它们可以重用，尽管这样做会使该语句的先前结果集失效。（请参阅并发和线程安全。）

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 数据。

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