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 資料。

增量執行 允許在結果集的分區可用時串流它們，而不是阻塞和等待查詢執行完成後再讀取結果。