ADBC
Arrow Database Connectivity
|
#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 AdbcError * | AdbcErrorFromArrayStream (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. | |
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.