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 中,AdbcErrorAdbcErrorAdbcException 分别暴露一个额外的元数据列表。 对于 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 数据。

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