ADBC
Arrow Database Connectivity
Loading...
Searching...
No Matches
adbc.h File Reference
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Classes

struct  AdbcError
 A detailed error message for an operation. More...
 
struct  AdbcErrorDetail
 Extra key-value metadata for an error. More...
 
struct  AdbcDatabase
 An instance of a database. More...
 
struct  AdbcConnection
 An active database connection. More...
 
struct  AdbcStatement
 A container for all state needed to execute a database query, such as the query itself, parameters for prepared statements, driver parameters, etc. More...
 
struct  AdbcPartitions
 The partitions of a distributed/partitioned result set. More...
 
struct  AdbcDriver
 An instance of an initialized database driver. More...
 

Macros

#define ADBC_STATUS_OK   0
 No error.
 
#define ADBC_STATUS_UNKNOWN   1
 An unknown error occurred.
 
#define ADBC_STATUS_NOT_IMPLEMENTED   2
 The operation is not implemented or supported.
 
#define ADBC_STATUS_NOT_FOUND   3
 A requested resource was not found.
 
#define ADBC_STATUS_ALREADY_EXISTS   4
 A requested resource already exists.
 
#define ADBC_STATUS_INVALID_ARGUMENT   5
 The arguments are invalid, likely a programming error.
 
#define ADBC_STATUS_INVALID_STATE   6
 The preconditions for the operation are not met, likely a programming error.
 
#define ADBC_STATUS_INVALID_DATA   7
 Invalid data was processed (not a programming error).
 
#define ADBC_STATUS_INTEGRITY   8
 The database's integrity was affected.
 
#define ADBC_STATUS_INTERNAL   9
 An error internal to the driver or database occurred.
 
#define ADBC_STATUS_IO   10
 An I/O error occurred.
 
#define ADBC_STATUS_CANCELLED   11
 The operation was cancelled, not due to a timeout.
 
#define ADBC_STATUS_TIMEOUT   12
 The operation was cancelled due to a timeout.
 
#define ADBC_STATUS_UNAUTHENTICATED   13
 Authentication failed.
 
#define ADBC_STATUS_UNAUTHORIZED   14
 The client is not authorized to perform the given operation.
 
#define ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA   INT32_MIN
 Inform the driver/driver manager that we are using the extended AdbcError struct from ADBC 1.1.0.
 
#define ADBC_ERROR_INIT
 A helper to initialize the full AdbcError structure.
 
#define ADBC_ERROR_1_0_0_SIZE   (offsetof(struct AdbcError, private_data))
 The size of the AdbcError structure in ADBC 1.0.0.
 
#define ADBC_ERROR_1_1_0_SIZE   (sizeof(struct AdbcError))
 The size of the AdbcError structure in ADBC 1.1.0.
 
#define ADBC_VERSION_1_0_0   1000000
 ADBC revision 1.0.0.
 
#define ADBC_VERSION_1_1_0   1001000
 ADBC revision 1.1.0.
 
#define ADBC_OPTION_VALUE_ENABLED   "true"
 Canonical option value for enabling an option.
 
#define ADBC_OPTION_VALUE_DISABLED   "false"
 Canonical option value for disabling an option.
 
#define ADBC_OPTION_URI   "uri"
 Canonical option name for URIs.
 
#define ADBC_OPTION_USERNAME   "username"
 Canonical option name for usernames.
 
#define ADBC_OPTION_PASSWORD   "password"
 Canonical option name for passwords.
 
#define ADBC_INFO_VENDOR_NAME   0
 The database vendor/product name (e.g. the server name). (type: utf8).
 
#define ADBC_INFO_VENDOR_VERSION   1
 The database vendor/product version (type: utf8).
 
#define ADBC_INFO_VENDOR_ARROW_VERSION   2
 The database vendor/product Arrow library version (type: utf8).
 
#define ADBC_INFO_VENDOR_SQL   3
 Indicates whether SQL queries are supported (type: bool).
 
#define ADBC_INFO_VENDOR_SUBSTRAIT   4
 Indicates whether Substrait queries are supported (type: bool).
 
#define ADBC_INFO_VENDOR_SUBSTRAIT_MIN_VERSION   5
 The minimum supported Substrait version, or null if Substrait is not supported (type: utf8).
 
#define ADBC_INFO_VENDOR_SUBSTRAIT_MAX_VERSION   6
 The maximum supported Substrait version, or null if Substrait is not supported (type: utf8).
 
#define ADBC_INFO_DRIVER_NAME   100
 The driver name (type: utf8).
 
#define ADBC_INFO_DRIVER_VERSION   101
 The driver version (type: utf8).
 
#define ADBC_INFO_DRIVER_ARROW_VERSION   102
 The driver Arrow library version (type: utf8).
 
#define ADBC_INFO_DRIVER_ADBC_VERSION   103
 The driver ADBC API version (type: int64).
 
#define ADBC_OBJECT_DEPTH_ALL   0
 Return metadata on catalogs, schemas, tables, and columns.
 
#define ADBC_OBJECT_DEPTH_CATALOGS   1
 Return metadata on catalogs only.
 
#define ADBC_OBJECT_DEPTH_DB_SCHEMAS   2
 Return metadata on catalogs and schemas.
 
#define ADBC_OBJECT_DEPTH_TABLES   3
 Return metadata on catalogs, schemas, and tables.
 
#define ADBC_OBJECT_DEPTH_COLUMNS   ADBC_OBJECT_DEPTH_ALL
 Return metadata on catalogs, schemas, tables, and columns.
 
#define ADBC_STATISTIC_AVERAGE_BYTE_WIDTH_KEY   0
 The dictionary-encoded name of the average byte width statistic.
 
#define ADBC_STATISTIC_AVERAGE_BYTE_WIDTH_NAME   "adbc.statistic.byte_width"
 The average byte width statistic. The average size in bytes of a row in the column. Value type is float64.
 
#define ADBC_STATISTIC_DISTINCT_COUNT_KEY   1
 The dictionary-encoded name of the distinct value count statistic.
 
#define ADBC_STATISTIC_DISTINCT_COUNT_NAME   "adbc.statistic.distinct_count"
 The distinct value count (NDV) statistic. The number of distinct values in the column. Value type is int64 (when not approximate) or float64 (when approximate).
 
#define ADBC_STATISTIC_MAX_BYTE_WIDTH_KEY   2
 The dictionary-encoded name of the max byte width statistic.
 
#define ADBC_STATISTIC_MAX_BYTE_WIDTH_NAME   "adbc.statistic.max_byte_width"
 The max byte width statistic. The maximum size in bytes of a row in the column. Value type is int64 (when not approximate) or float64 (when approximate).
 
#define ADBC_STATISTIC_MAX_VALUE_KEY   3
 The dictionary-encoded name of the max value statistic.
 
#define ADBC_STATISTIC_MAX_VALUE_NAME   "adbc.statistic.max_value"
 The max value statistic. Value type is column-dependent.
 
#define ADBC_STATISTIC_MIN_VALUE_KEY   4
 The dictionary-encoded name of the min value statistic.
 
#define ADBC_STATISTIC_MIN_VALUE_NAME   "adbc.statistic.min_value"
 The min value statistic. Value type is column-dependent.
 
#define ADBC_STATISTIC_NULL_COUNT_KEY   5
 The dictionary-encoded name of the null count statistic.
 
#define ADBC_STATISTIC_NULL_COUNT_NAME   "adbc.statistic.null_count"
 The null count statistic. The number of values that are null in the column. Value type is int64 (when not approximate) or float64 (when approximate).
 
#define ADBC_STATISTIC_ROW_COUNT_KEY   6
 The dictionary-encoded name of the row count statistic.
 
#define ADBC_STATISTIC_ROW_COUNT_NAME   "adbc.statistic.row_count"
 The row count statistic. The number of rows in the column or table. Value type is int64 (when not approximate) or float64 (when approximate).
 
#define ADBC_CONNECTION_OPTION_AUTOCOMMIT   "adbc.connection.autocommit"
 The name of the canonical option for whether autocommit is enabled.
 
#define ADBC_CONNECTION_OPTION_READ_ONLY   "adbc.connection.readonly"
 The name of the canonical option for whether the current connection should be restricted to being read-only.
 
#define ADBC_CONNECTION_OPTION_CURRENT_CATALOG   "adbc.connection.catalog"
 The name of the canonical option for the current catalog.
 
#define ADBC_CONNECTION_OPTION_CURRENT_DB_SCHEMA   "adbc.connection.db_schema"
 The name of the canonical option for the current schema.
 
#define ADBC_STATEMENT_OPTION_INCREMENTAL   "adbc.statement.exec.incremental"
 The name of the canonical option for making query execution nonblocking.
 
#define ADBC_STATEMENT_OPTION_PROGRESS   "adbc.statement.exec.progress"
 The name of the option for getting the progress of a query.
 
#define ADBC_STATEMENT_OPTION_MAX_PROGRESS   "adbc.statement.exec.max_progress"
 The name of the option for getting the maximum progress of a query.
 
#define ADBC_CONNECTION_OPTION_ISOLATION_LEVEL    "adbc.connection.transaction.isolation_level"
 The name of the canonical option for setting the isolation level of a transaction.
 
#define ADBC_OPTION_ISOLATION_LEVEL_DEFAULT    "adbc.connection.transaction.isolation.default"
 Use database or driver default isolation level.
 
#define ADBC_OPTION_ISOLATION_LEVEL_READ_UNCOMMITTED    "adbc.connection.transaction.isolation.read_uncommitted"
 The lowest isolation level. Dirty reads are allowed, so one transaction may see not-yet-committed changes made by others.
 
#define ADBC_OPTION_ISOLATION_LEVEL_READ_COMMITTED    "adbc.connection.transaction.isolation.read_committed"
 Lock-based concurrency control keeps write locks until the end of the transaction, but read locks are released as soon as a SELECT is performed. Non-repeatable reads can occur in this isolation level.
 
#define ADBC_OPTION_ISOLATION_LEVEL_REPEATABLE_READ    "adbc.connection.transaction.isolation.repeatable_read"
 Lock-based concurrency control keeps read AND write locks (acquired on selection data) until the end of the transaction.
 
#define ADBC_OPTION_ISOLATION_LEVEL_SNAPSHOT    "adbc.connection.transaction.isolation.snapshot"
 This isolation guarantees that all reads in the transaction will see a consistent snapshot of the database and the transaction should only successfully commit if no updates conflict with any concurrent updates made since that snapshot.
 
#define ADBC_OPTION_ISOLATION_LEVEL_SERIALIZABLE    "adbc.connection.transaction.isolation.serializable"
 Serializability requires read and write locks to be released only at the end of the transaction. This includes acquiring range- locks when a select query uses a ranged WHERE clause to avoid phantom reads.
 
#define ADBC_OPTION_ISOLATION_LEVEL_LINEARIZABLE    "adbc.connection.transaction.isolation.linearizable"
 The central distinction between serializability and linearizability is that serializability is a global property; a property of an entire history of operations and transactions. Linearizability is a local property; a property of a single operation/transaction.
 
#define ADBC_INGEST_OPTION_TARGET_TABLE   "adbc.ingest.target_table"
 The name of the target table for a bulk insert.
 
#define ADBC_INGEST_OPTION_MODE   "adbc.ingest.mode"
 Whether to create (the default) or append.
 
#define ADBC_INGEST_OPTION_MODE_CREATE   "adbc.ingest.mode.create"
 Create the table and insert data; error if the table exists.
 
#define ADBC_INGEST_OPTION_MODE_APPEND   "adbc.ingest.mode.append"
 Do not create the table, and insert data; error if the table does not exist (ADBC_STATUS_NOT_FOUND) or does not match the schema of the data to append (ADBC_STATUS_ALREADY_EXISTS).
 
#define ADBC_INGEST_OPTION_MODE_REPLACE   "adbc.ingest.mode.replace"
 Create the table and insert data; drop the original table if it already exists.
 
#define ADBC_INGEST_OPTION_MODE_CREATE_APPEND   "adbc.ingest.mode.create_append"
 Insert data; create the table if it does not exist, or error if the table exists, but the schema does not match the schema of the data to append (ADBC_STATUS_ALREADY_EXISTS).
 
#define ADBC_INGEST_OPTION_TARGET_CATALOG   "adbc.ingest.target_catalog"
 The catalog of the table for bulk insert.
 
#define ADBC_INGEST_OPTION_TARGET_DB_SCHEMA   "adbc.ingest.target_db_schema"
 The schema of the table for bulk insert.
 
#define ADBC_INGEST_OPTION_TEMPORARY   "adbc.ingest.temporary"
 Use a temporary table for ingestion.
 
#define ADBC_DRIVER_1_0_0_SIZE   (offsetof(struct AdbcDriver, ErrorGetDetailCount))
 The size of the AdbcDriver structure in ADBC 1.0.0. Drivers written for ADBC 1.1.0 and later should never touch more than this portion of an AdbcDriver struct when given ADBC_VERSION_1_0_0.
 
#define ADBC_DRIVER_1_1_0_SIZE   (sizeof(struct AdbcDriver))
 The size of the AdbcDriver structure in ADBC 1.1.0. Drivers written for ADBC 1.1.0 and later should never touch more than this portion of an AdbcDriver struct when given ADBC_VERSION_1_1_0.
 

Typedefs

typedef uint8_t AdbcStatusCode
 Error codes for operations that may fail.
 
typedef AdbcStatusCode(* AdbcDriverInitFunc) (int version, void *driver, struct AdbcError *error)
 Common entry point for drivers via the driver manager (which uses dlopen(3)/LoadLibrary). The driver manager is told to load a library and call a function of this type to load the driver.
 

Functions

int AdbcErrorGetDetailCount (const struct AdbcError *error)
 Get the number of metadata values available in an error.
 
struct AdbcErrorDetail AdbcErrorGetDetail (const struct AdbcError *error, int index)
 Get a metadata value in an error by index.
 
const struct AdbcErrorAdbcErrorFromArrayStream (struct ArrowArrayStream *stream, AdbcStatusCode *status)
 Get an ADBC error from an ArrowArrayStream created by a driver.
 
AdbcStatusCode AdbcDatabaseNew (struct AdbcDatabase *database, struct AdbcError *error)
 Allocate a new (but uninitialized) database.
 
AdbcStatusCode AdbcDatabaseGetOption (struct AdbcDatabase *database, const char *key, char *value, size_t *length, struct AdbcError *error)
 Get a string option of the database.
 
AdbcStatusCode AdbcDatabaseGetOptionBytes (struct AdbcDatabase *database, const char *key, uint8_t *value, size_t *length, struct AdbcError *error)
 Get a bytestring option of the database.
 
AdbcStatusCode AdbcDatabaseGetOptionDouble (struct AdbcDatabase *database, const char *key, double *value, struct AdbcError *error)
 Get a double option of the database.
 
AdbcStatusCode AdbcDatabaseGetOptionInt (struct AdbcDatabase *database, const char *key, int64_t *value, struct AdbcError *error)
 Get an integer option of the database.
 
AdbcStatusCode AdbcDatabaseSetOption (struct AdbcDatabase *database, const char *key, const char *value, struct AdbcError *error)
 Set a char* option.
 
AdbcStatusCode AdbcDatabaseSetOptionBytes (struct AdbcDatabase *database, const char *key, const uint8_t *value, size_t length, struct AdbcError *error)
 Set a bytestring option on a database.
 
AdbcStatusCode AdbcDatabaseSetOptionDouble (struct AdbcDatabase *database, const char *key, double value, struct AdbcError *error)
 Set a double option on a database.
 
AdbcStatusCode AdbcDatabaseSetOptionInt (struct AdbcDatabase *database, const char *key, int64_t value, struct AdbcError *error)
 Set an integer option on a database.
 
AdbcStatusCode AdbcDatabaseInit (struct AdbcDatabase *database, struct AdbcError *error)
 Finish setting options and initialize the database.
 
AdbcStatusCode AdbcDatabaseRelease (struct AdbcDatabase *database, struct AdbcError *error)
 Destroy this database. No connections may exist.
 
AdbcStatusCode AdbcConnectionNew (struct AdbcConnection *connection, struct AdbcError *error)
 Allocate a new (but uninitialized) connection.
 
AdbcStatusCode AdbcConnectionSetOption (struct AdbcConnection *connection, const char *key, const char *value, struct AdbcError *error)
 Set a char* option.
 
AdbcStatusCode AdbcConnectionSetOptionBytes (struct AdbcConnection *connection, const char *key, const uint8_t *value, size_t length, struct AdbcError *error)
 Set a bytestring option on a connection.
 
AdbcStatusCode AdbcConnectionSetOptionInt (struct AdbcConnection *connection, const char *key, int64_t value, struct AdbcError *error)
 Set an integer option.
 
AdbcStatusCode AdbcConnectionSetOptionDouble (struct AdbcConnection *connection, const char *key, double value, struct AdbcError *error)
 Set a double option.
 
AdbcStatusCode AdbcConnectionInit (struct AdbcConnection *connection, struct AdbcDatabase *database, struct AdbcError *error)
 Finish setting options and initialize the connection.
 
AdbcStatusCode AdbcConnectionRelease (struct AdbcConnection *connection, struct AdbcError *error)
 Destroy this connection.
 
AdbcStatusCode AdbcConnectionCancel (struct AdbcConnection *connection, struct AdbcError *error)
 Cancel the in-progress operation on a connection.
 
AdbcStatusCode AdbcConnectionGetInfo (struct AdbcConnection *connection, const uint32_t *info_codes, size_t info_codes_length, struct ArrowArrayStream *out, struct AdbcError *error)
 Get metadata about the database/driver.
 
AdbcStatusCode AdbcConnectionGetObjects (struct AdbcConnection *connection, int depth, const char *catalog, const char *db_schema, const char *table_name, const char **table_type, const char *column_name, struct ArrowArrayStream *out, struct AdbcError *error)
 Get a hierarchical view of all catalogs, database schemas, tables, and columns.
 
AdbcStatusCode AdbcConnectionGetOption (struct AdbcConnection *connection, const char *key, char *value, size_t *length, struct AdbcError *error)
 Get a string option of the connection.
 
AdbcStatusCode AdbcConnectionGetOptionBytes (struct AdbcConnection *connection, const char *key, uint8_t *value, size_t *length, struct AdbcError *error)
 Get a bytestring option of the connection.
 
AdbcStatusCode AdbcConnectionGetOptionInt (struct AdbcConnection *connection, const char *key, int64_t *value, struct AdbcError *error)
 Get an integer option of the connection.
 
AdbcStatusCode AdbcConnectionGetOptionDouble (struct AdbcConnection *connection, const char *key, double *value, struct AdbcError *error)
 Get a double option of the connection.
 
AdbcStatusCode AdbcConnectionGetStatistics (struct AdbcConnection *connection, const char *catalog, const char *db_schema, const char *table_name, char approximate, struct ArrowArrayStream *out, struct AdbcError *error)
 Get statistics about the data distribution of table(s).
 
AdbcStatusCode AdbcConnectionGetStatisticNames (struct AdbcConnection *connection, struct ArrowArrayStream *out, struct AdbcError *error)
 Get the names of statistics specific to this driver.
 
AdbcStatusCode AdbcConnectionGetTableSchema (struct AdbcConnection *connection, const char *catalog, const char *db_schema, const char *table_name, struct ArrowSchema *schema, struct AdbcError *error)
 Get the Arrow schema of a table.
 
AdbcStatusCode AdbcConnectionGetTableTypes (struct AdbcConnection *connection, struct ArrowArrayStream *out, struct AdbcError *error)
 Get a list of table types in the database.
 
AdbcStatusCode AdbcConnectionReadPartition (struct AdbcConnection *connection, const uint8_t *serialized_partition, size_t serialized_length, struct ArrowArrayStream *out, struct AdbcError *error)
 Construct a statement for a partition of a query. The results can then be read independently.
 
AdbcStatusCode AdbcConnectionCommit (struct AdbcConnection *connection, struct AdbcError *error)
 Commit any pending transactions. Only used if autocommit is disabled.
 
AdbcStatusCode AdbcConnectionRollback (struct AdbcConnection *connection, struct AdbcError *error)
 Roll back any pending transactions. Only used if autocommit is disabled.
 
AdbcStatusCode AdbcStatementNew (struct AdbcConnection *connection, struct AdbcStatement *statement, struct AdbcError *error)
 Create a new statement for a given connection.
 
AdbcStatusCode AdbcStatementRelease (struct AdbcStatement *statement, struct AdbcError *error)
 Destroy a statement.
 
AdbcStatusCode AdbcStatementExecuteQuery (struct AdbcStatement *statement, struct ArrowArrayStream *out, int64_t *rows_affected, struct AdbcError *error)
 Execute a statement and get the results.
 
AdbcStatusCode AdbcStatementExecuteSchema (struct AdbcStatement *statement, struct ArrowSchema *schema, struct AdbcError *error)
 Get the schema of the result set of a query without executing it.
 
AdbcStatusCode AdbcStatementPrepare (struct AdbcStatement *statement, struct AdbcError *error)
 Turn this statement into a prepared statement to be executed multiple times.
 
AdbcStatusCode AdbcStatementSetSqlQuery (struct AdbcStatement *statement, const char *query, struct AdbcError *error)
 Set the SQL query to execute.
 
AdbcStatusCode AdbcStatementSetSubstraitPlan (struct AdbcStatement *statement, const uint8_t *plan, size_t length, struct AdbcError *error)
 Set the Substrait plan to execute.
 
AdbcStatusCode AdbcStatementBind (struct AdbcStatement *statement, struct ArrowArray *values, struct ArrowSchema *schema, struct AdbcError *error)
 Bind Arrow data. This can be used for bulk inserts or prepared statements.
 
AdbcStatusCode AdbcStatementBindStream (struct AdbcStatement *statement, struct ArrowArrayStream *stream, struct AdbcError *error)
 Bind Arrow data. This can be used for bulk inserts or prepared statements.
 
AdbcStatusCode AdbcStatementCancel (struct AdbcStatement *statement, struct AdbcError *error)
 Cancel execution of an in-progress query.
 
AdbcStatusCode AdbcStatementGetOption (struct AdbcStatement *statement, const char *key, char *value, size_t *length, struct AdbcError *error)
 Get a string option of the statement.
 
AdbcStatusCode AdbcStatementGetOptionBytes (struct AdbcStatement *statement, const char *key, uint8_t *value, size_t *length, struct AdbcError *error)
 Get a bytestring option of the statement.
 
AdbcStatusCode AdbcStatementGetOptionInt (struct AdbcStatement *statement, const char *key, int64_t *value, struct AdbcError *error)
 Get an integer option of the statement.
 
AdbcStatusCode AdbcStatementGetOptionDouble (struct AdbcStatement *statement, const char *key, double *value, struct AdbcError *error)
 Get a double option of the statement.
 
AdbcStatusCode AdbcStatementGetParameterSchema (struct AdbcStatement *statement, struct ArrowSchema *schema, struct AdbcError *error)
 Get the schema for bound parameters.
 
AdbcStatusCode AdbcStatementSetOption (struct AdbcStatement *statement, const char *key, const char *value, struct AdbcError *error)
 Set a string option on a statement.
 
AdbcStatusCode AdbcStatementSetOptionBytes (struct AdbcStatement *statement, const char *key, const uint8_t *value, size_t length, struct AdbcError *error)
 Set a bytestring option on a statement.
 
AdbcStatusCode AdbcStatementSetOptionInt (struct AdbcStatement *statement, const char *key, int64_t value, struct AdbcError *error)
 Set an integer option on a statement.
 
AdbcStatusCode AdbcStatementSetOptionDouble (struct AdbcStatement *statement, const char *key, double value, struct AdbcError *error)
 Set a double option on a statement.
 
AdbcStatusCode AdbcStatementExecutePartitions (struct AdbcStatement *statement, struct ArrowSchema *schema, struct AdbcPartitions *partitions, int64_t *rows_affected, struct AdbcError *error)
 Execute a statement and get the results as a partitioned result set.
 

Detailed Description

ADBC: Arrow Database connectivity

An Arrow-based interface between applications and database drivers. ADBC aims to provide a vendor-independent API for SQL and Substrait-based database access that is targeted at analytics/OLAP use cases.

This API is intended to be implemented directly by drivers and used directly by client applications. To assist portability between different vendors, a "driver manager" library is also provided, which implements this same API, but dynamically loads drivers internally and forwards calls appropriately.

ADBC uses structs with free functions that operate on those structs to model objects.

In general, objects allow serialized access from multiple threads, but not concurrent access. Specific implementations may permit multiple threads.

Version
1.1.0