快速入門¶

在此我們將簡要導覽 ADBC 的基本功能，使用 C++17 中的 SQLite 驅動程式。

安裝¶

這個快速入門實際上是一個可讀的 C++ 檔案。您可以複製儲存庫、建置範例並跟著操作。

我們假設您使用 conda-forge 來管理依賴項。需要 CMake、C++17 編譯器和 ADBC 庫。它們可以如下安裝

mamba install cmake compilers libadbc-driver-manager libadbc-driver-sqlite

建置¶

我們在這裡使用 CMake。從 ADBC 儲存庫的原始碼檢出

mkdir build
cd build
cmake ../docs/source/cpp/recipe
cmake --build . --target quickstart
./quickstart

使用 ADBC¶

讓我們先從一些包含檔開始

// For EXIT_SUCCESS
#include <cstdlib>
// For strerror
#include <cstring>
#include <iostream>

#include <arrow-adbc/adbc.h>
#include <nanoarrow.h>

然後我們將加入一些（非常基本的）錯誤檢查輔助函式。

// Error-checking helper for ADBC calls.
// Assumes that there is an AdbcError named `error` in scope.
#define CHECK_ADBC(EXPR)                                          \
  if (AdbcStatusCode status = (EXPR); status != ADBC_STATUS_OK) { \
    if (error.message != nullptr) {                               \
      std::cerr << error.message << std::endl;                    \
    }                                                             \
    return EXIT_FAILURE;                                          \
  }

// Error-checking helper for ArrowArrayStream.
#define CHECK_STREAM(STREAM, EXPR)                            \
  if (int status = (EXPR); status != 0) {                     \
    std::cerr << "(" << std::strerror(status) << "): ";       \
    const char* message = (STREAM).get_last_error(&(STREAM)); \
    if (message != nullptr) {                                 \
      std::cerr << message << std::endl;                      \
    } else {                                                  \
      std::cerr << "(no error message)" << std::endl;         \
    }                                                         \
    return EXIT_FAILURE;                                      \
  }

// Error-checking helper for Nanoarrow.
#define CHECK_NANOARROW(EXPR)                                              \
  if (int status = (EXPR); status != 0) {                                  \
    std::cerr << "(" << std::strerror(status) << "): failed" << std::endl; \
    return EXIT_FAILURE;                                                   \
  }

int main() {

載入驅動程式¶

我們將使用驅動程式管理器載入 SQLite 驅動程式。我們不必以這種方式顯式連結到驅動程式。

  AdbcError error = {};

  AdbcDatabase database = {};
  CHECK_ADBC(AdbcDatabaseNew(&database, &error));

驅動程式管理器知道我們想要哪個驅動程式的方式是透過 driver 選項。

  CHECK_ADBC(AdbcDatabaseSetOption(&database, "driver", "adbc_driver_sqlite", &error));
  CHECK_ADBC(AdbcDatabaseInit(&database, &error));

建立連線¶

ADBC 區分「資料庫」、「連線」和「語句」。「資料庫」在多個連線之間保存共享狀態。例如，在 SQLite 驅動程式中，它保存 SQLite 的實際實例。「連線」是與資料庫的一個連線。

  AdbcConnection connection = {};
  CHECK_ADBC(AdbcConnectionNew(&connection, &error));
  CHECK_ADBC(AdbcConnectionInit(&connection, &database, &error));

建立語句¶

語句讓我們可以執行查詢。它們用於預備查詢和非預備（「臨時」）查詢。

  AdbcStatement statement = {};
  CHECK_ADBC(AdbcStatementNew(&connection, &statement, &error));

執行查詢¶

我們透過在語句上設定查詢，然後呼叫 AdbcStatementExecuteQuery() 來執行查詢。結果透過 Arrow C 資料介面回傳。

  struct ArrowArrayStream stream = {};
  int64_t rows_affected = -1;

  CHECK_ADBC(AdbcStatementSetSqlQuery(&statement, "SELECT 42 AS THEANSWER", &error));
  CHECK_ADBC(AdbcStatementExecuteQuery(&statement, &stream, &rows_affected, &error));

雖然 API 給了我們行數，但 SQLite 驅動程式實際上無法提前知道結果集中有多少行，因此這個值實際上只會是 -1，表示該值未知。

  std::cout << "Got " << rows_affected << " rows" << std::endl;

我們需要 Arrow 實作來讀取實際結果。我們可以使用 Arrow C++ 或 Nanoarrow。為了簡化，我們在這裡使用 Nanoarrow。（此範例的 CMake 配置會下載並從原始碼建置 Nanoarrow 作為建置的一部分。）

首先，我們將取得資料的綱要

  ArrowSchema schema = {};
  CHECK_STREAM(stream, stream.get_schema(&stream, &schema));

然後我們可以使用 Nanoarrow 來列印它

  char buf[1024] = {};
  ArrowSchemaToString(&schema, buf, sizeof(buf), /*recursive=*/1);
  std::cout << buf << std::endl;

現在我們可以讀取資料。資料以 Arrow 記錄批次的串流形式傳輸。

  while (true) {
    ArrowArray batch = {};
    CHECK_STREAM(stream, stream.get_next(&stream, &batch));

    if (batch.release == nullptr) {
      // Stream has ended
      break;
    }

我們也可以使用 Nanoarrow 來列印資料。

    ArrowArrayView view = {};
    CHECK_NANOARROW(ArrowArrayViewInitFromSchema(&view, &schema, nullptr));
    CHECK_NANOARROW(ArrowArrayViewSetArray(&view, &batch, nullptr));
    std::cout << "Got a batch with " << batch.length << " rows" << std::endl;
    for (int64_t i = 0; i < batch.length; i++) {
      std::cout << "THEANSWER[" << i
                << "] = " << view.children[0]->buffer_views[1].data.as_int64[i]
                << std::endl;
    }
    ArrowArrayViewReset(&view);
  }

  std::cout << "Finished reading result set" << std::endl;
  stream.release(&stream);

清理¶

最後，我們必須釋放所有資源。

  CHECK_ADBC(AdbcStatementRelease(&statement, &error));
  CHECK_ADBC(AdbcConnectionRelease(&connection, &error));
  CHECK_ADBC(AdbcDatabaseRelease(&database, &error));
  return EXIT_SUCCESS;
}