ADBC C API Specification

In C, ADBC consists of a self-contained header. The header is reproduced in full here, and is intended to be self-documenting.

From apache/arrow-adbc commit f044edf5256abfb4c091b0ad2acc73afea2c93c0:

 166/// \defgroup adbc-error-handling Error Handling
 167/// ADBC uses integer error codes to signal errors. To provide more
 168/// detail about errors, functions may also return an AdbcError via an
 169/// optional out parameter, which can be inspected. If provided, it is
 170/// the responsibility of the caller to zero-initialize the AdbcError
 171/// value.
 172///
 173/// @{
 174
 175/// \brief Error codes for operations that may fail.
 176typedef uint8_t AdbcStatusCode;
 177
 178/// \brief No error.
 179#define ADBC_STATUS_OK 0
 180/// \brief An unknown error occurred.
 181///
 182/// May indicate a driver-side or database-side error.
 183#define ADBC_STATUS_UNKNOWN 1
 184/// \brief The operation is not implemented or supported.
 185///
 186/// May indicate a driver-side or database-side error.
 187#define ADBC_STATUS_NOT_IMPLEMENTED 2
 188/// \brief A requested resource was not found.
 189///
 190/// May indicate a driver-side or database-side error.
 191#define ADBC_STATUS_NOT_FOUND 3
 192/// \brief A requested resource already exists.
 193///
 194/// May indicate a driver-side or database-side error.
 195#define ADBC_STATUS_ALREADY_EXISTS 4
 196/// \brief The arguments are invalid, likely a programming error.
 197///
 198/// For instance, they may be of the wrong format, or out of range.
 199///
 200/// May indicate a driver-side or database-side error.
 201#define ADBC_STATUS_INVALID_ARGUMENT 5
 202/// \brief The preconditions for the operation are not met, likely a
 203///   programming error.
 204///
 205/// For instance, the object may be uninitialized, or may have not
 206/// been fully configured.
 207///
 208/// May indicate a driver-side or database-side error.
 209#define ADBC_STATUS_INVALID_STATE 6
 210/// \brief Invalid data was processed (not a programming error).
 211///
 212/// For instance, a division by zero may have occurred during query
 213/// execution.
 214///
 215/// May indicate a database-side error only.
 216#define ADBC_STATUS_INVALID_DATA 7
 217/// \brief The database's integrity was affected.
 218///
 219/// For instance, a foreign key check may have failed, or a uniqueness
 220/// constraint may have been violated.
 221///
 222/// May indicate a database-side error only.
 223#define ADBC_STATUS_INTEGRITY 8
 224/// \brief An error internal to the driver or database occurred.
 225///
 226/// May indicate a driver-side or database-side error.
 227#define ADBC_STATUS_INTERNAL 9
 228/// \brief An I/O error occurred.
 229///
 230/// For instance, a remote service may be unavailable.
 231///
 232/// May indicate a driver-side or database-side error.
 233#define ADBC_STATUS_IO 10
 234/// \brief The operation was cancelled, not due to a timeout.
 235///
 236/// May indicate a driver-side or database-side error.
 237#define ADBC_STATUS_CANCELLED 11
 238/// \brief The operation was cancelled due to a timeout.
 239///
 240/// May indicate a driver-side or database-side error.
 241#define ADBC_STATUS_TIMEOUT 12
 242/// \brief Authentication failed.
 243///
 244/// May indicate a database-side error only.
 245#define ADBC_STATUS_UNAUTHENTICATED 13
 246/// \brief The client is not authorized to perform the given operation.
 247///
 248/// May indicate a database-side error only.
 249#define ADBC_STATUS_UNAUTHORIZED 14
 250
 251/// \brief A detailed error message for an operation.
 252struct ADBC_EXPORT AdbcError {
 253  /// \brief The error message.
 254  char* message;
 255
 256  /// \brief A vendor-specific error code, if applicable.
 257  int32_t vendor_code;
 258
 259  /// \brief A SQLSTATE error code, if provided, as defined by the
 260  ///   SQL:2003 standard.  If not set, it should be set to
 261  ///   "\0\0\0\0\0".
 262  char sqlstate[5];
 263
 264  /// \brief Release the contained error.
 265  ///
 266  /// Unlike other structures, this is an embedded callback to make it
 267  /// easier for the driver manager and driver to cooperate.
 268  void (*release)(struct AdbcError* error);
 269};
 270
 271/// @}
 272
 273/// \defgroup adbc-constants Constants
 274/// @{
 275
 276/// \brief ADBC revision 1.0.0.
 277///
 278/// When passed to an AdbcDriverInitFunc(), the driver parameter must
 279/// point to an AdbcDriver.
 280#define ADBC_VERSION_1_0_0 1000000
 281
 282/// \brief Canonical option value for enabling an option.
 283///
 284/// For use as the value in SetOption calls.
 285#define ADBC_OPTION_VALUE_ENABLED "true"
 286/// \brief Canonical option value for disabling an option.
 287///
 288/// For use as the value in SetOption calls.
 289#define ADBC_OPTION_VALUE_DISABLED "false"
 290
 291/// \brief The database vendor/product name (e.g. the server name).
 292///   (type: utf8).
 293///
 294/// \see AdbcConnectionGetInfo
 295#define ADBC_INFO_VENDOR_NAME 0
 296/// \brief The database vendor/product version (type: utf8).
 297///
 298/// \see AdbcConnectionGetInfo
 299#define ADBC_INFO_VENDOR_VERSION 1
 300/// \brief The database vendor/product Arrow library version (type:
 301///   utf8).
 302///
 303/// \see AdbcConnectionGetInfo
 304#define ADBC_INFO_VENDOR_ARROW_VERSION 2
 305
 306/// \brief The driver name (type: utf8).
 307///
 308/// \see AdbcConnectionGetInfo
 309#define ADBC_INFO_DRIVER_NAME 100
 310/// \brief The driver version (type: utf8).
 311///
 312/// \see AdbcConnectionGetInfo
 313#define ADBC_INFO_DRIVER_VERSION 101
 314/// \brief The driver Arrow library version (type: utf8).
 315///
 316/// \see AdbcConnectionGetInfo
 317#define ADBC_INFO_DRIVER_ARROW_VERSION 102
 318
 319/// \brief Return metadata on catalogs, schemas, tables, and columns.
 320///
 321/// \see AdbcConnectionGetObjects
 322#define ADBC_OBJECT_DEPTH_ALL 0
 323/// \brief Return metadata on catalogs only.
 324///
 325/// \see AdbcConnectionGetObjects
 326#define ADBC_OBJECT_DEPTH_CATALOGS 1
 327/// \brief Return metadata on catalogs and schemas.
 328///
 329/// \see AdbcConnectionGetObjects
 330#define ADBC_OBJECT_DEPTH_DB_SCHEMAS 2
 331/// \brief Return metadata on catalogs, schemas, and tables.
 332///
 333/// \see AdbcConnectionGetObjects
 334#define ADBC_OBJECT_DEPTH_TABLES 3
 335/// \brief Return metadata on catalogs, schemas, tables, and columns.
 336///
 337/// \see AdbcConnectionGetObjects
 338#define ADBC_OBJECT_DEPTH_COLUMNS ADBC_OBJECT_DEPTH_ALL
 339
 340/// \brief The name of the canonical option for whether autocommit is
 341///   enabled.
 342///
 343/// \see AdbcConnectionSetOption
 344#define ADBC_CONNECTION_OPTION_AUTOCOMMIT "adbc.connection.autocommit"
 345
 346/// \brief The name of the canonical option for whether the current
 347///   connection should be restricted to being read-only.
 348///
 349/// \see AdbcConnectionSetOption
 350#define ADBC_CONNECTION_OPTION_READ_ONLY "adbc.connection.readonly"
 351
 352/// \brief The name of the canonical option for setting the isolation
 353///   level of a transaction.
 354///
 355/// Should only be used in conjunction with autocommit disabled and
 356/// AdbcConnectionCommit / AdbcConnectionRollback. If the desired
 357/// isolation level is not supported by a driver, it should return an
 358/// appropriate error.
 359///
 360/// \see AdbcConnectionSetOption
 361#define ADBC_CONNECTION_OPTION_ISOLATION_LEVEL \
 362  "adbc.connection.transaction.isolation_level"
 363
 364/// \brief Use database or driver default isolation level
 365///
 366/// \see AdbcConnectionSetOption
 367#define ADBC_OPTION_ISOLATION_LEVEL_DEFAULT \
 368  "adbc.connection.transaction.isolation.default"
 369
 370/// \brief The lowest isolation level. Dirty reads are allowed, so one
 371///   transaction may see not-yet-committed changes made by others.
 372///
 373/// \see AdbcConnectionSetOption
 374#define ADBC_OPTION_ISOLATION_LEVEL_READ_UNCOMMITTED \
 375  "adbc.connection.transaction.isolation.read_uncommitted"
 376
 377/// \brief Lock-based concurrency control keeps write locks until the
 378///   end of the transaction, but read locks are released as soon as a
 379///   SELECT is performed. Non-repeatable reads can occur in this
 380///   isolation level.
 381///
 382/// More simply put, Read Committed is an isolation level that guarantees
 383/// that any data read is committed at the moment it is read. It simply
 384/// restricts the reader from seeing any intermediate, uncommitted,
 385/// 'dirty' reads. It makes no promise whatsoever that if the transaction
 386/// re-issues the read, it will find the same data; data is free to change
 387/// after it is read.
 388///
 389/// \see AdbcConnectionSetOption
 390#define ADBC_OPTION_ISOLATION_LEVEL_READ_COMMITTED \
 391  "adbc.connection.transaction.isolation.read_committed"
 392
 393/// \brief Lock-based concurrency control keeps read AND write locks
 394///   (acquired on selection data) until the end of the transaction.
 395///
 396/// However, range-locks are not managed, so phantom reads can occur.
 397/// Write skew is possible at this isolation level in some systems.
 398///
 399/// \see AdbcConnectionSetOption
 400#define ADBC_OPTION_ISOLATION_LEVEL_REPEATABLE_READ \
 401  "adbc.connection.transaction.isolation.repeatable_read"
 402
 403/// \brief This isolation guarantees that all reads in the transaction
 404///   will see a consistent snapshot of the database and the transaction
 405///   should only successfully commit if no updates conflict with any
 406///   concurrent updates made since that snapshot.
 407///
 408/// \see AdbcConnectionSetOption
 409#define ADBC_OPTION_ISOLATION_LEVEL_SNAPSHOT \
 410  "adbc.connection.transaction.isolation.snapshot"
 411
 412/// \brief Serializability requires read and write locks to be released
 413///   only at the end of the transaction. This includes acquiring range-
 414///   locks when a select query uses a ranged WHERE clause to avoid
 415///   phantom reads.
 416///
 417/// \see AdbcConnectionSetOption
 418#define ADBC_OPTION_ISOLATION_LEVEL_SERIALIZABLE \
 419  "adbc.connection.transaction.isolation.serializable"
 420
 421/// \brief The central distinction between serializability and linearizability
 422///   is that serializability is a global property; a property of an entire
 423///   history of operations and transactions. Linearizability is a local
 424///   property; a property of a single operation/transaction.
 425///
 426/// Linearizability can be viewed as a special case of strict serializability
 427/// where transactions are restricted to consist of a single operation applied
 428/// to a single object.
 429///
 430/// \see AdbcConnectionSetOption
 431#define ADBC_OPTION_ISOLATION_LEVEL_LINEARIZABLE \
 432  "adbc.connection.transaction.isolation.linearizable"
 433
 434/// \defgroup adbc-statement-ingestion Bulk Data Ingestion
 435/// While it is possible to insert data via prepared statements, it can
 436/// be more efficient to explicitly perform a bulk insert.  For
 437/// compatible drivers, this can be accomplished by setting up and
 438/// executing a statement.  Instead of setting a SQL query or Substrait
 439/// plan, bind the source data via AdbcStatementBind, and set the name
 440/// of the table to be created via AdbcStatementSetOption and the
 441/// options below.  Then, call AdbcStatementExecute with
 442/// ADBC_OUTPUT_TYPE_UPDATE.
 443///
 444/// @{
 445
 446/// \brief The name of the target table for a bulk insert.
 447///
 448/// The driver should attempt to create the table if it does not
 449/// exist.  If the table exists but has a different schema,
 450/// ADBC_STATUS_ALREADY_EXISTS should be raised.  Else, data should be
 451/// appended to the target table.
 452#define ADBC_INGEST_OPTION_TARGET_TABLE "adbc.ingest.target_table"
 453/// \brief Whether to create (the default) or append.
 454#define ADBC_INGEST_OPTION_MODE "adbc.ingest.mode"
 455/// \brief Create the table and insert data; error if the table exists.
 456#define ADBC_INGEST_OPTION_MODE_CREATE "adbc.ingest.mode.create"
 457/// \brief Do not create the table, and insert data; error if the
 458///   table does not exist (ADBC_STATUS_NOT_FOUND) or does not match
 459///   the schema of the data to append (ADBC_STATUS_ALREADY_EXISTS).
 460#define ADBC_INGEST_OPTION_MODE_APPEND "adbc.ingest.mode.append"
 461
 462/// @}
 463
 464/// @}
 465
 466/// \defgroup adbc-database Database Initialization
 467/// Clients first initialize a database, then create a connection
 468/// (below).  This gives the implementation a place to initialize and
 469/// own any common connection state.  For example, in-memory databases
 470/// can place ownership of the actual database in this object.
 471/// @{
 472
 473/// \brief An instance of a database.
 474///
 475/// Must be kept alive as long as any connections exist.
 476struct ADBC_EXPORT AdbcDatabase {
 477  /// \brief Opaque implementation-defined state.
 478  /// This field is NULLPTR iff the connection is unintialized/freed.
 479  void* private_data;
 480  /// \brief The associated driver (used by the driver manager to help
 481  ///   track state).
 482  struct AdbcDriver* private_driver;
 483};
 484
 485/// @}
 486
 487/// \defgroup adbc-connection Connection Establishment
 488/// Functions for creating, using, and releasing database connections.
 489/// @{
 490
 491/// \brief An active database connection.
 492///
 493/// Provides methods for query execution, managing prepared
 494/// statements, using transactions, and so on.
 495///
 496/// Connections are not required to be thread-safe, but they can be
 497/// used from multiple threads so long as clients take care to
 498/// serialize accesses to a connection.
 499struct ADBC_EXPORT AdbcConnection {
 500  /// \brief Opaque implementation-defined state.
 501  /// This field is NULLPTR iff the connection is unintialized/freed.
 502  void* private_data;
 503  /// \brief The associated driver (used by the driver manager to help
 504  ///   track state).
 505  struct AdbcDriver* private_driver;
 506};
 507
 508/// @}
 509
 510/// \defgroup adbc-statement Managing Statements
 511/// Applications should first initialize a statement with
 512/// AdbcStatementNew. Then, the statement should be configured with
 513/// functions like AdbcStatementSetSqlQuery and
 514/// AdbcStatementSetOption. Finally, the statement can be executed
 515/// with AdbcStatementExecuteQuery (or call AdbcStatementPrepare first
 516/// to turn it into a prepared statement instead).
 517/// @{
 518
 519/// \brief A container for all state needed to execute a database
 520/// query, such as the query itself, parameters for prepared
 521/// statements, driver parameters, etc.
 522///
 523/// Statements may represent queries or prepared statements.
 524///
 525/// Statements may be used multiple times and can be reconfigured
 526/// (e.g. they can be reused to execute multiple different queries).
 527/// However, executing a statement (and changing certain other state)
 528/// will invalidate result sets obtained prior to that execution.
 529///
 530/// Multiple statements may be created from a single connection.
 531/// However, the driver may block or error if they are used
 532/// concurrently (whether from a single thread or multiple threads).
 533///
 534/// Statements are not required to be thread-safe, but they can be
 535/// used from multiple threads so long as clients take care to
 536/// serialize accesses to a statement.
 537struct ADBC_EXPORT AdbcStatement {
 538  /// \brief Opaque implementation-defined state.
 539  /// This field is NULLPTR iff the connection is unintialized/freed.
 540  void* private_data;
 541
 542  /// \brief The associated driver (used by the driver manager to help
 543  ///   track state).
 544  struct AdbcDriver* private_driver;
 545};
 546
 547/// \defgroup adbc-statement-partition Partitioned Results
 548/// Some backends may internally partition the results. These
 549/// partitions are exposed to clients who may wish to integrate them
 550/// with a threaded or distributed execution model, where partitions
 551/// can be divided among threads or machines and fetched in parallel.
 552///
 553/// To use partitioning, execute the statement with
 554/// AdbcStatementExecutePartitions to get the partition descriptors.
 555/// Call AdbcConnectionReadPartition to turn the individual
 556/// descriptors into ArrowArrayStream instances.  This may be done on
 557/// a different connection than the one the partition was created
 558/// with, or even in a different process on another machine.
 559///
 560/// Drivers are not required to support partitioning.
 561///
 562/// @{
 563
 564/// \brief The partitions of a distributed/partitioned result set.
 565struct AdbcPartitions {
 566  /// \brief The number of partitions.
 567  size_t num_partitions;
 568
 569  /// \brief The partitions of the result set, where each entry (up to
 570  ///   num_partitions entries) is an opaque identifier that can be
 571  ///   passed to AdbcConnectionReadPartition.
 572  const uint8_t** partitions;
 573
 574  /// \brief The length of each corresponding entry in partitions.
 575  const size_t* partition_lengths;
 576
 577  /// \brief Opaque implementation-defined state.
 578  /// This field is NULLPTR iff the connection is unintialized/freed.
 579  void* private_data;
 580
 581  /// \brief Release the contained partitions.
 582  ///
 583  /// Unlike other structures, this is an embedded callback to make it
 584  /// easier for the driver manager and driver to cooperate.
 585  void (*release)(struct AdbcPartitions* partitions);
 586};
 587
 588/// @}
 589
 590/// @}
 591
 592/// \defgroup adbc-driver Driver Initialization
 593///
 594/// These functions are intended to help support integration between a
 595/// driver and the driver manager.
 596/// @{
 597
 598/// \brief An instance of an initialized database driver.
 599///
 600/// This provides a common interface for vendor-specific driver
 601/// initialization routines. Drivers should populate this struct, and
 602/// applications can call ADBC functions through this struct, without
 603/// worrying about multiple definitions of the same symbol.
 604struct ADBC_EXPORT AdbcDriver {
 605  /// \brief Opaque driver-defined state.
 606  /// This field is NULL if the driver is unintialized/freed (but
 607  /// it need not have a value even if the driver is initialized).
 608  void* private_data;
 609  /// \brief Opaque driver manager-defined state.
 610  /// This field is NULL if the driver is unintialized/freed (but
 611  /// it need not have a value even if the driver is initialized).
 612  void* private_manager;
 613
 614  /// \brief Release the driver and perform any cleanup.
 615  ///
 616  /// This is an embedded callback to make it easier for the driver
 617  /// manager and driver to cooperate.
 618  AdbcStatusCode (*release)(struct AdbcDriver* driver, struct AdbcError* error);
 619
 620  AdbcStatusCode (*DatabaseInit)(struct AdbcDatabase*, struct AdbcError*);
 621  AdbcStatusCode (*DatabaseNew)(struct AdbcDatabase*, struct AdbcError*);
 622  AdbcStatusCode (*DatabaseSetOption)(struct AdbcDatabase*, const char*, const char*,
 623                                      struct AdbcError*);
 624  AdbcStatusCode (*DatabaseRelease)(struct AdbcDatabase*, struct AdbcError*);
 625
 626  AdbcStatusCode (*ConnectionCommit)(struct AdbcConnection*, struct AdbcError*);
 627  AdbcStatusCode (*ConnectionGetInfo)(struct AdbcConnection*, uint32_t*, size_t,
 628                                      struct ArrowArrayStream*, struct AdbcError*);
 629  AdbcStatusCode (*ConnectionGetObjects)(struct AdbcConnection*, int, const char*,
 630                                         const char*, const char*, const char**,
 631                                         const char*, struct ArrowArrayStream*,
 632                                         struct AdbcError*);
 633  AdbcStatusCode (*ConnectionGetTableSchema)(struct AdbcConnection*, const char*,
 634                                             const char*, const char*,
 635                                             struct ArrowSchema*, struct AdbcError*);
 636  AdbcStatusCode (*ConnectionGetTableTypes)(struct AdbcConnection*,
 637                                            struct ArrowArrayStream*, struct AdbcError*);
 638  AdbcStatusCode (*ConnectionInit)(struct AdbcConnection*, struct AdbcDatabase*,
 639                                   struct AdbcError*);
 640  AdbcStatusCode (*ConnectionNew)(struct AdbcConnection*, struct AdbcError*);
 641  AdbcStatusCode (*ConnectionSetOption)(struct AdbcConnection*, const char*, const char*,
 642                                        struct AdbcError*);
 643  AdbcStatusCode (*ConnectionReadPartition)(struct AdbcConnection*, const uint8_t*,
 644                                            size_t, struct ArrowArrayStream*,
 645                                            struct AdbcError*);
 646  AdbcStatusCode (*ConnectionRelease)(struct AdbcConnection*, struct AdbcError*);
 647  AdbcStatusCode (*ConnectionRollback)(struct AdbcConnection*, struct AdbcError*);
 648
 649  AdbcStatusCode (*StatementBind)(struct AdbcStatement*, struct ArrowArray*,
 650                                  struct ArrowSchema*, struct AdbcError*);
 651  AdbcStatusCode (*StatementBindStream)(struct AdbcStatement*, struct ArrowArrayStream*,
 652                                        struct AdbcError*);
 653  AdbcStatusCode (*StatementExecuteQuery)(struct AdbcStatement*, struct ArrowArrayStream*,
 654                                          int64_t*, struct AdbcError*);
 655  AdbcStatusCode (*StatementExecutePartitions)(struct AdbcStatement*, struct ArrowSchema*,
 656                                               struct AdbcPartitions*, int64_t*,
 657                                               struct AdbcError*);
 658  AdbcStatusCode (*StatementGetParameterSchema)(struct AdbcStatement*,
 659                                                struct ArrowSchema*, struct AdbcError*);
 660  AdbcStatusCode (*StatementNew)(struct AdbcConnection*, struct AdbcStatement*,
 661                                 struct AdbcError*);
 662  AdbcStatusCode (*StatementPrepare)(struct AdbcStatement*, struct AdbcError*);
 663  AdbcStatusCode (*StatementRelease)(struct AdbcStatement*, struct AdbcError*);
 664  AdbcStatusCode (*StatementSetOption)(struct AdbcStatement*, const char*, const char*,
 665                                       struct AdbcError*);
 666  AdbcStatusCode (*StatementSetSqlQuery)(struct AdbcStatement*, const char*,
 667                                         struct AdbcError*);
 668  AdbcStatusCode (*StatementSetSubstraitPlan)(struct AdbcStatement*, const uint8_t*,
 669                                              size_t, struct AdbcError*);
 670};
 671
 672/// @}
 673
 674/// \addtogroup adbc-database
 675/// @{
 676
 677/// \brief Allocate a new (but uninitialized) database.
 678ADBC_EXPORT
 679AdbcStatusCode AdbcDatabaseNew(struct AdbcDatabase* database, struct AdbcError* error);
 680
 681/// \brief Set a char* option.
 682///
 683/// Options may be set before AdbcDatabaseInit.  Some drivers may
 684/// support setting options after initialization as well.
 685///
 686/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized
 687ADBC_EXPORT
 688AdbcStatusCode AdbcDatabaseSetOption(struct AdbcDatabase* database, const char* key,
 689                                     const char* value, struct AdbcError* error);
 690
 691/// \brief Finish setting options and initialize the database.
 692///
 693/// Some drivers may support setting options after initialization
 694/// as well.
 695ADBC_EXPORT
 696AdbcStatusCode AdbcDatabaseInit(struct AdbcDatabase* database, struct AdbcError* error);
 697
 698/// \brief Destroy this database. No connections may exist.
 699/// \param[in] database The database to release.
 700/// \param[out] error An optional location to return an error
 701///   message if necessary.
 702ADBC_EXPORT
 703AdbcStatusCode AdbcDatabaseRelease(struct AdbcDatabase* database,
 704                                   struct AdbcError* error);
 705
 706/// @}
 707
 708/// \addtogroup adbc-connection
 709/// @{
 710
 711/// \brief Allocate a new (but uninitialized) connection.
 712ADBC_EXPORT
 713AdbcStatusCode AdbcConnectionNew(struct AdbcConnection* connection,
 714                                 struct AdbcError* error);
 715
 716/// \brief Set a char* option.
 717///
 718/// Options may be set before AdbcConnectionInit.  Some drivers may
 719/// support setting options after initialization as well.
 720///
 721/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized
 722ADBC_EXPORT
 723AdbcStatusCode AdbcConnectionSetOption(struct AdbcConnection* connection, const char* key,
 724                                       const char* value, struct AdbcError* error);
 725
 726/// \brief Finish setting options and initialize the connection.
 727///
 728/// Some drivers may support setting options after initialization
 729/// as well.
 730ADBC_EXPORT
 731AdbcStatusCode AdbcConnectionInit(struct AdbcConnection* connection,
 732                                  struct AdbcDatabase* database, struct AdbcError* error);
 733
 734/// \brief Destroy this connection.
 735///
 736/// \param[in] connection The connection to release.
 737/// \param[out] error An optional location to return an error
 738///   message if necessary.
 739ADBC_EXPORT
 740AdbcStatusCode AdbcConnectionRelease(struct AdbcConnection* connection,
 741                                     struct AdbcError* error);
 742
 743/// \defgroup adbc-connection-metadata Metadata
 744/// Functions for retrieving metadata about the database.
 745///
 746/// Generally, these functions return an ArrowArrayStream that can be
 747/// consumed to get the metadata as Arrow data.  The returned metadata
 748/// has an expected schema given in the function docstring. Schema
 749/// fields are nullable unless otherwise marked.  While no
 750/// AdbcStatement is used in these functions, the result set may count
 751/// as an active statement to the driver for the purposes of
 752/// concurrency management (e.g. if the driver has a limit on
 753/// concurrent active statements and it must execute a SQL query
 754/// internally in order to implement the metadata function).
 755///
 756/// Some functions accept "search pattern" arguments, which are
 757/// strings that can contain the special character "%" to match zero
 758/// or more characters, or "_" to match exactly one character.  (See
 759/// the documentation of DatabaseMetaData in JDBC or "Pattern Value
 760/// Arguments" in the ODBC documentation.)  Escaping is not currently
 761/// supported.
 762///
 763/// @{
 764
 765/// \brief Get metadata about the database/driver.
 766///
 767/// The result is an Arrow dataset with the following schema:
 768///
 769/// Field Name                  | Field Type
 770/// ----------------------------|------------------------
 771/// info_name                   | uint32 not null
 772/// info_value                  | INFO_SCHEMA
 773///
 774/// INFO_SCHEMA is a dense union with members:
 775///
 776/// Field Name (Type Code)      | Field Type
 777/// ----------------------------|------------------------
 778/// string_value (0)            | utf8
 779/// bool_value (1)              | bool
 780/// int64_value (2)             | int64
 781/// int32_bitmask (3)           | int32
 782/// string_list (4)             | list<utf8>
 783/// int32_to_int32_list_map (5) | map<int32, list<int32>>
 784///
 785/// Each metadatum is identified by an integer code.  The recognized
 786/// codes are defined as constants.  Codes [0, 10_000) are reserved
 787/// for ADBC usage.  Drivers/vendors will ignore requests for
 788/// unrecognized codes (the row will be omitted from the result).
 789///
 790/// \param[in] connection The connection to query.
 791/// \param[in] info_codes A list of metadata codes to fetch, or NULL
 792///   to fetch all.
 793/// \param[in] info_codes_length The length of the info_codes
 794///   parameter.  Ignored if info_codes is NULL.
 795/// \param[out] out The result set.
 796/// \param[out] error Error details, if an error occurs.
 797ADBC_EXPORT
 798AdbcStatusCode AdbcConnectionGetInfo(struct AdbcConnection* connection,
 799                                     uint32_t* info_codes, size_t info_codes_length,
 800                                     struct ArrowArrayStream* out,
 801                                     struct AdbcError* error);
 802
 803/// \brief Get a hierarchical view of all catalogs, database schemas,
 804///   tables, and columns.
 805///
 806/// The result is an Arrow dataset with the following schema:
 807///
 808/// | Field Name               | Field Type              |
 809/// |--------------------------|-------------------------|
 810/// | catalog_name             | utf8                    |
 811/// | catalog_db_schemas       | list<DB_SCHEMA_SCHEMA>  |
 812///
 813/// DB_SCHEMA_SCHEMA is a Struct with fields:
 814///
 815/// | Field Name               | Field Type              |
 816/// |--------------------------|-------------------------|
 817/// | db_schema_name           | utf8                    |
 818/// | db_schema_tables         | list<TABLE_SCHEMA>      |
 819///
 820/// TABLE_SCHEMA is a Struct with fields:
 821///
 822/// | Field Name               | Field Type              |
 823/// |--------------------------|-------------------------|
 824/// | table_name               | utf8 not null           |
 825/// | table_type               | utf8 not null           |
 826/// | table_columns            | list<COLUMN_SCHEMA>     |
 827/// | table_constraints        | list<CONSTRAINT_SCHEMA> |
 828///
 829/// COLUMN_SCHEMA is a Struct with fields:
 830///
 831/// | Field Name               | Field Type              | Comments |
 832/// |--------------------------|-------------------------|----------|
 833/// | column_name              | utf8 not null           |          |
 834/// | ordinal_position         | int32                   | (1)      |
 835/// | remarks                  | utf8                    | (2)      |
 836/// | xdbc_data_type           | int16                   | (3)      |
 837/// | xdbc_type_name           | utf8                    | (3)      |
 838/// | xdbc_column_size         | int32                   | (3)      |
 839/// | xdbc_decimal_digits      | int16                   | (3)      |
 840/// | xdbc_num_prec_radix      | int16                   | (3)      |
 841/// | xdbc_nullable            | int16                   | (3)      |
 842/// | xdbc_column_def          | utf8                    | (3)      |
 843/// | xdbc_sql_data_type       | int16                   | (3)      |
 844/// | xdbc_datetime_sub        | int16                   | (3)      |
 845/// | xdbc_char_octet_length   | int32                   | (3)      |
 846/// | xdbc_is_nullable         | utf8                    | (3)      |
 847/// | xdbc_scope_catalog       | utf8                    | (3)      |
 848/// | xdbc_scope_schema        | utf8                    | (3)      |
 849/// | xdbc_scope_table         | utf8                    | (3)      |
 850/// | xdbc_is_autoincrement    | bool                    | (3)      |
 851/// | xdbc_is_generatedcolumn  | bool                    | (3)      |
 852///
 853/// 1. The column's ordinal position in the table (starting from 1).
 854/// 2. Database-specific description of the column.
 855/// 3. Optional value.  Should be null if not supported by the driver.
 856///    xdbc_ values are meant to provide JDBC/ODBC-compatible metadata
 857///    in an agnostic manner.
 858///
 859/// CONSTRAINT_SCHEMA is a Struct with fields:
 860///
 861/// | Field Name               | Field Type              | Comments |
 862/// |--------------------------|-------------------------|----------|
 863/// | constraint_name          | utf8                    |          |
 864/// | constraint_type          | utf8 not null           | (1)      |
 865/// | constraint_column_names  | list<utf8> not null     | (2)      |
 866/// | constraint_column_usage  | list<USAGE_SCHEMA>      | (3)      |
 867///
 868/// 1. One of 'CHECK', 'FOREIGN KEY', 'PRIMARY KEY', or 'UNIQUE'.
 869/// 2. The columns on the current table that are constrained, in
 870///    order.
 871/// 3. For FOREIGN KEY only, the referenced table and columns.
 872///
 873/// USAGE_SCHEMA is a Struct with fields:
 874///
 875/// | Field Name               | Field Type              |
 876/// |--------------------------|-------------------------|
 877/// | fk_catalog               | utf8                    |
 878/// | fk_db_schema             | utf8                    |
 879/// | fk_table                 | utf8 not null           |
 880/// | fk_column_name           | utf8 not null           |
 881///
 882/// \param[in] connection The database connection.
 883/// \param[in] depth The level of nesting to display. If 0, display
 884///   all levels. If 1, display only catalogs (i.e.  catalog_schemas
 885///   will be null). If 2, display only catalogs and schemas
 886///   (i.e. db_schema_tables will be null), and so on.
 887/// \param[in] catalog Only show tables in the given catalog. If NULL,
 888///   do not filter by catalog. If an empty string, only show tables
 889///   without a catalog.  May be a search pattern (see section
 890///   documentation).
 891/// \param[in] db_schema Only show tables in the given database schema. If
 892///   NULL, do not filter by database schema. If an empty string, only show
 893///   tables without a database schema. May be a search pattern (see section
 894///   documentation).
 895/// \param[in] table_name Only show tables with the given name. If NULL, do not
 896///   filter by name. May be a search pattern (see section documentation).
 897/// \param[in] table_type Only show tables matching one of the given table
 898///   types. If NULL, show tables of any type. Valid table types can be fetched
 899///   from GetTableTypes.  Terminate the list with a NULL entry.
 900/// \param[in] column_name Only show columns with the given name. If
 901///   NULL, do not filter by name.  May be a search pattern (see
 902///   section documentation).
 903/// \param[out] out The result set.
 904/// \param[out] error Error details, if an error occurs.
 905ADBC_EXPORT
 906AdbcStatusCode AdbcConnectionGetObjects(struct AdbcConnection* connection, int depth,
 907                                        const char* catalog, const char* db_schema,
 908                                        const char* table_name, const char** table_type,
 909                                        const char* column_name,
 910                                        struct ArrowArrayStream* out,
 911                                        struct AdbcError* error);
 912
 913/// \brief Get the Arrow schema of a table.
 914///
 915/// \param[in] connection The database connection.
 916/// \param[in] catalog The catalog (or nullptr if not applicable).
 917/// \param[in] db_schema The database schema (or nullptr if not applicable).
 918/// \param[in] table_name The table name.
 919/// \param[out] schema The table schema.
 920/// \param[out] error Error details, if an error occurs.
 921ADBC_EXPORT
 922AdbcStatusCode AdbcConnectionGetTableSchema(struct AdbcConnection* connection,
 923                                            const char* catalog, const char* db_schema,
 924                                            const char* table_name,
 925                                            struct ArrowSchema* schema,
 926                                            struct AdbcError* error);
 927
 928/// \brief Get a list of table types in the database.
 929///
 930/// The result is an Arrow dataset with the following schema:
 931///
 932/// Field Name     | Field Type
 933/// ---------------|--------------
 934/// table_type     | utf8 not null
 935///
 936/// \param[in] connection The database connection.
 937/// \param[out] out The result set.
 938/// \param[out] error Error details, if an error occurs.
 939ADBC_EXPORT
 940AdbcStatusCode AdbcConnectionGetTableTypes(struct AdbcConnection* connection,
 941                                           struct ArrowArrayStream* out,
 942                                           struct AdbcError* error);
 943
 944/// @}
 945
 946/// \defgroup adbc-connection-partition Partitioned Results
 947/// Some databases may internally partition the results. These
 948/// partitions are exposed to clients who may wish to integrate them
 949/// with a threaded or distributed execution model, where partitions
 950/// can be divided among threads or machines for processing.
 951///
 952/// Drivers are not required to support partitioning.
 953///
 954/// Partitions are not ordered. If the result set is sorted,
 955/// implementations should return a single partition.
 956///
 957/// @{
 958
 959/// \brief Construct a statement for a partition of a query. The
 960///   results can then be read independently.
 961///
 962/// A partition can be retrieved from AdbcPartitions.
 963///
 964/// \param[in] connection The connection to use.  This does not have
 965///   to be the same connection that the partition was created on.
 966/// \param[in] serialized_partition The partition descriptor.
 967/// \param[in] serialized_length The partition descriptor length.
 968/// \param[out] out The result set.
 969/// \param[out] error Error details, if an error occurs.
 970ADBC_EXPORT
 971AdbcStatusCode AdbcConnectionReadPartition(struct AdbcConnection* connection,
 972                                           const uint8_t* serialized_partition,
 973                                           size_t serialized_length,
 974                                           struct ArrowArrayStream* out,
 975                                           struct AdbcError* error);
 976
 977/// @}
 978
 979/// \defgroup adbc-connection-transaction Transaction Semantics
 980///
 981/// Connections start out in auto-commit mode by default (if
 982/// applicable for the given vendor). Use AdbcConnectionSetOption and
 983/// ADBC_CONNECTION_OPTION_AUTO_COMMIT to change this.
 984///
 985/// @{
 986
 987/// \brief Commit any pending transactions. Only used if autocommit is
 988///   disabled.
 989///
 990/// Behavior is undefined if this is mixed with SQL transaction
 991/// statements.
 992ADBC_EXPORT
 993AdbcStatusCode AdbcConnectionCommit(struct AdbcConnection* connection,
 994                                    struct AdbcError* error);
 995
 996/// \brief Roll back any pending transactions. Only used if autocommit
 997///   is disabled.
 998///
 999/// Behavior is undefined if this is mixed with SQL transaction
1000/// statements.
1001ADBC_EXPORT
1002AdbcStatusCode AdbcConnectionRollback(struct AdbcConnection* connection,
1003                                      struct AdbcError* error);
1004
1005/// @}
1006
1007/// @}
1008
1009/// \addtogroup adbc-statement
1010/// @{
1011
1012/// \brief Create a new statement for a given connection.
1013///
1014/// Set options on the statement, then call AdbcStatementExecuteQuery
1015/// or AdbcStatementPrepare.
1016ADBC_EXPORT
1017AdbcStatusCode AdbcStatementNew(struct AdbcConnection* connection,
1018                                struct AdbcStatement* statement, struct AdbcError* error);
1019
1020/// \brief Destroy a statement.
1021/// \param[in] statement The statement to release.
1022/// \param[out] error An optional location to return an error
1023///   message if necessary.
1024ADBC_EXPORT
1025AdbcStatusCode AdbcStatementRelease(struct AdbcStatement* statement,
1026                                    struct AdbcError* error);
1027
1028/// \brief Execute a statement and get the results.
1029///
1030/// This invalidates any prior result sets.
1031///
1032/// \param[in] statement The statement to execute.
1033/// \param[out] out The results. Pass NULL if the client does not
1034///   expect a result set.
1035/// \param[out] rows_affected The number of rows affected if known,
1036///   else -1. Pass NULL if the client does not want this information.
1037/// \param[out] error An optional location to return an error
1038///   message if necessary.
1039ADBC_EXPORT
1040AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
1041                                         struct ArrowArrayStream* out,
1042                                         int64_t* rows_affected, struct AdbcError* error);
1043
1044/// \brief Turn this statement into a prepared statement to be
1045///   executed multiple times.
1046///
1047/// This invalidates any prior result sets.
1048ADBC_EXPORT
1049AdbcStatusCode AdbcStatementPrepare(struct AdbcStatement* statement,
1050                                    struct AdbcError* error);
1051
1052/// \defgroup adbc-statement-sql SQL Semantics
1053/// Functions for executing SQL queries, or querying SQL-related
1054/// metadata. Drivers are not required to support both SQL and
1055/// Substrait semantics. If they do, it may be via converting
1056/// between representations internally.
1057/// @{
1058
1059/// \brief Set the SQL query to execute.
1060///
1061/// The query can then be executed with AdbcStatementExecute.  For
1062/// queries expected to be executed repeatedly, AdbcStatementPrepare
1063/// the statement first.
1064///
1065/// \param[in] statement The statement.
1066/// \param[in] query The query to execute.
1067/// \param[out] error Error details, if an error occurs.
1068ADBC_EXPORT
1069AdbcStatusCode AdbcStatementSetSqlQuery(struct AdbcStatement* statement,
1070                                        const char* query, struct AdbcError* error);
1071
1072/// @}
1073
1074/// \defgroup adbc-statement-substrait Substrait Semantics
1075/// Functions for executing Substrait plans, or querying
1076/// Substrait-related metadata.  Drivers are not required to support
1077/// both SQL and Substrait semantics.  If they do, it may be via
1078/// converting between representations internally.
1079/// @{
1080
1081/// \brief Set the Substrait plan to execute.
1082///
1083/// The query can then be executed with AdbcStatementExecute.  For
1084/// queries expected to be executed repeatedly, AdbcStatementPrepare
1085/// the statement first.
1086///
1087/// \param[in] statement The statement.
1088/// \param[in] plan The serialized substrait.Plan to execute.
1089/// \param[in] length The length of the serialized plan.
1090/// \param[out] error Error details, if an error occurs.
1091ADBC_EXPORT
1092AdbcStatusCode AdbcStatementSetSubstraitPlan(struct AdbcStatement* statement,
1093                                             const uint8_t* plan, size_t length,
1094                                             struct AdbcError* error);
1095
1096/// @}
1097
1098/// \brief Bind Arrow data. This can be used for bulk inserts or
1099///   prepared statements.
1100///
1101/// \param[in] statement The statement to bind to.
1102/// \param[in] values The values to bind. The driver will call the
1103///   release callback itself, although it may not do this until the
1104///   statement is released.
1105/// \param[in] schema The schema of the values to bind.
1106/// \param[out] error An optional location to return an error message
1107///   if necessary.
1108ADBC_EXPORT
1109AdbcStatusCode AdbcStatementBind(struct AdbcStatement* statement,
1110                                 struct ArrowArray* values, struct ArrowSchema* schema,
1111                                 struct AdbcError* error);
1112
1113/// \brief Bind Arrow data. This can be used for bulk inserts or
1114///   prepared statements.
1115/// \param[in] statement The statement to bind to.
1116/// \param[in] stream The values to bind. The driver will call the
1117///   release callback itself, although it may not do this until the
1118///   statement is released.
1119/// \param[out] error An optional location to return an error message
1120///   if necessary.
1121ADBC_EXPORT
1122AdbcStatusCode AdbcStatementBindStream(struct AdbcStatement* statement,
1123                                       struct ArrowArrayStream* stream,