ADBC API 标准

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

有关 ADBC API 的权威定义，请参阅以下来源

adbc.h 被视为权威。

数据库

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

连接

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

自动提交

默认情况下，连接应以自动提交模式运行；即，查询在执行后立即生效。这可以通过手动调用 commit/rollback 来禁用，但并非所有实现都支持此功能。

元数据

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

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

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

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

批量摄取 支持另外两种模式

  • “adbc.ingest.mode.replace” 将删除现有数据，然后表现得像“create”。

  • “adbc.ingest.mode.create_append” 将表现得像“create”，除非表已存在，否则它不会报错。

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

添加了检索表/列 统计信息 的功能。这里的目标是让 ADBC 在联邦场景中更好地工作，其中一个查询引擎想从另一个数据库读取 Arrow 数据。

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