Quickstart

Recipe source: quickstart.cc

Here we’ll briefly tour basic features of ADBC with the SQLite driver in C++17.

Installation

This quickstart is actually a literate C++ file. You can clone the repository, build the sample, and follow along.

We’ll assume you’re using conda-forge for dependencies. CMake, a C++17 compiler, and the ADBC libraries are required. They can be installed as follows:

mamba install cmake compilers libadbc-driver-manager

Installing Drivers

See Installing Drivers for instructions on installing ADBC drivers for the database you want to connect to. For the example below, you could install dbc and then use dbc to install the SQLite driver and its manifest in the user configuration directory where the driver manager library will search for it:

dbc install --level user sqlite

You can also build drivers from source or use other installation methods. See the driver documentation for more details.

Building

We’ll use CMake here. From a source checkout of the ADBC repository:

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

Basic Example

Let’s start with some includes:

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

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

Then we’ll add some (very basic) error checking helpers.

// 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() {

Loading the Driver

We’ll load the SQLite driver using the driver manager. We don’t have to explicitly link to the driver this way.

  AdbcError error = {};

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

The way the driver manager knows what driver we want is via the driver option.

  CHECK_ADBC(AdbcDatabaseSetOption(&database, "driver", "sqlite", &error));

We also need to enable searching for driver manifests.

  CHECK_ADBC(
      AdbcDriverManagerDatabaseSetLoadFlags(&database, ADBC_LOAD_FLAG_DEFAULT, &error));
  CHECK_ADBC(AdbcDatabaseInit(&database, &error));

Creating a Connection

ADBC distinguishes between “databases”, “connections”, and “statements”. A “database” holds shared state across multiple connections. For example, in the SQLite driver, it holds the actual instance of SQLite. A “connection” is one connection to the database.

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

Creating a Statement

A statement lets us execute queries. They are used for both prepared and non-prepared (“ad-hoc”) queries.

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

Executing a Query

We execute a query by setting the query on the statement, then calling AdbcStatementExecuteQuery(). The results come back through the Arrow C Data Interface.

  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));

While the API gives us the number of rows, the SQLite driver can’t actually know how many rows there are in the result set ahead of time, so this value will actually just be -1 to indicate that the value is not known.

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

We need an Arrow implementation to read the actual results. We can use Arrow C++ or Nanoarrow for that. For simplicity, we’ll use Nanoarrow here. (The CMake configuration for this example downloads and builds Nanoarrow from source as part of the build.)

First we’ll get the schema of the data:

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

Then we can use Nanoarrow to print it:

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

Now we can read the data. The data comes as a stream of Arrow record batches.

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

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

We can use Nanoarrow to print out the data, too.

    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);
  }
  // Output:
  // Got a batch with 1 rows
  // THEANSWER[0] = 42

  stream.release(&stream);

Cleanup

At the end, we must release all our resources.

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

stdout

Got -1 rows
Result schema: struct<THEANSWER: int64>
Got a batch with 1 rows
THEANSWER[0] = 42