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 版本

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

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

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

批量摄取 支持两种额外的模式

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

  • “adbc.ingest.mode.create_append” 的行为将类似于 “create”，但如果表已存在，则不会出错。

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

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

增量执行 允许流式传输结果集的分区（因为它们可用），而不是阻塞并等待查询执行完成才能读取结果。