ADBC API 标准¶
本文档概述了通用功能集。
有关 C/C++ 详细信息,请参阅 adbc.h。
有关 Go 详细信息,请参阅 源代码。
有关 Java 详细信息,请参阅 源代码,特别是包
org.apache.arrow.adbc.core
。
数据库¶
数据库保存多个连接共享的状态。通常,这意味着通用配置和缓存。对于内存数据库,它提供了一个保存内存数据库所有权的位置。
C/C++:
AdbcDatabase
Go:
Driver
连接¶
连接是到数据库的单个逻辑连接。
C/C++:
AdbcConnection
Go:
Connection
自动提交¶
默认情况下,连接应以自动提交模式运行;也就是说,查询在执行后立即生效。可以禁用此设置以支持手动提交/回滚调用,但并非所有实现都支持此设置。
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 中的功能。)客户端可以利用此功能在多个线程、进程或计算机上分配结果集上的计算。
Go:
Statement.ExecutePartitions
Java:
org.apache.arrow.adbc.core.AdbcStatement#executePartitioned()
原则上,供应商可以返回分区执行的结果,因为它们是可用的,而不是一次全部返回。 增量执行允许驱动程序公开此功能。 启用后,每次调用 ExecutePartitions
将返回可用的读取端点,而不是阻塞以检索所有端点。
注意
自 API 修订版 1.1.0 起
生命周期 & 用法¶
基本用法¶
准备语句和绑定参数是可选的。¶
使用结果集¶
这相当于从许多 Arrow 库调用的 RecordBatchReader 中读取。¶
批量数据注入¶
无需准备语句。¶
仅更新查询(无结果集)¶
准备语句和绑定参数是可选的。¶
分区执行¶
错误处理¶
错误处理策略因语言而异。
在 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 数据。
增量执行 允许流式传输结果集的分区(因为它们可用),而不是阻塞并等待查询执行完成才能读取结果。