ADBC API 标准

本文档概述了通用功能集。

数据库

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

连接

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

自动提交

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

元数据

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 中的功能。）客户端可以利用这一点将结果集上的计算分布到多个线程、进程或机器上。

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

注意

从 API 修订版 1.1.0 开始

生命周期和使用

The lifecycle of a statement.

基本使用

../_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 数据。

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