From f91c0db5eef179a1efc17644e8199a2f44a687e0 Mon Sep 17 00:00:00 2001 From: David Li Date: Mon, 12 Jun 2023 13:32:21 -0400 Subject: [PATCH] format: add additional features to 1.1.0 spec Intends to tackle: - #621 - #685 - #736 - #755 --- adbc.h | 513 +++++++++++ c/driver_manager/adbc_driver_manager.cc | 22 + go/adbc/drivermgr/adbc.h | 1108 ++++++++++++++++++++++- 3 files changed, 1641 insertions(+), 2 deletions(-) diff --git a/adbc.h b/adbc.h index 5118f8307d..9017c538a9 100644 --- a/adbc.h +++ b/adbc.h @@ -326,6 +326,33 @@ struct ADBC_EXPORT AdbcError { /// \since ADBC API revision 1.1.0 /// \addtogroup adbc-1.1.0 #define ADBC_OPTION_PASSWORD "password" +/// \brief Canonical option name for error details. +/// +/// Should be used as the expected option name to retrieve error +/// details from the driver. This allows drivers to return custom, +/// structured error information (for example, JSON or Protocol +/// Buffers) that can be optionally parsed by clients, beyond the +/// standard AdbcError fields, without having to encode it in the +/// error message. The encoding of the data is driver-defined. +/// +/// This can be called immediately after any API call that returns an +/// error. Additionally, if an ArrowArrayStream returned from an +/// AdbcConnection or an AdbcStatement returns an error, this can be +/// immediately called from the associated AdbcConnection or +/// AdbcStatement to get further error details (if available). Making +/// other API calls with that connection or statement may clear this +/// error value. +/// +/// Drivers may provide multiple error details. Each call to +/// GetOptionBinary will return the next error detail. The driver +/// should return ADBC_STATUS_NOT_FOUND if there are no (more) error +/// details. +/// +/// The type is uint8_t*. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_OPTION_ERROR_DETAILS "error_details" /// \brief The database vendor/product name (e.g. the server name). /// (type: utf8). @@ -386,6 +413,35 @@ struct ADBC_EXPORT AdbcError { /// \see AdbcConnectionGetObjects #define ADBC_OBJECT_DEPTH_COLUMNS ADBC_OBJECT_DEPTH_ALL +/// \defgroup adbc-table-statistics ADBC Statistic Types +/// Standard statistic names for AdbcConnectionGetTableStatistics. +/// @{ + +/// \brief The dictionary-encoded name of the byte width statistic. +#define ADBC_STATISTIC_BYTE_WIDTH_KEY 0 +/// \brief The byte width statistic. The average size in bytes of a +/// row in the column. +/// +/// For example, for a string column, this would roughly be the +/// average length of a string. +#define ADBC_STATISTIC_BYTE_WIDTH_NAME "adbc.statistic.byte_width" +/// \brief The dictionary-encoded name of the NDV statistic. +#define ADBC_STATISTIC_DISTINCT_VALUE_COUNT_KEY 1 +/// \brief The distinct value count (NDV) statistic. The number of +/// distinct values in the column. +#define ADBC_STATISTIC_DISTINCT_VALUE_COUNT_NAME "adbc.statistic.distinct_count" +/// \brief The dictionary-encoded name of the null percentage statistic. +#define ADBC_STATISTIC_NULL_PERCENTAGE_KEY 2 +/// \brief The null percentage statistic. The percentage of values +/// that are null in the column (range [0, 1]). +#define ADBC_STATISTIC_NULL_PERCENTAGE_NAME "adbc.statistic.null_percentage" +/// \brief The dictionary-encoded name of the row count statistic. +#define ADBC_STATISTIC_ROW_COUNT_KEY 3 +/// \brief The row count statistic. The number of rows in the column +/// or table. +#define ADBC_STATISTIC_ROW_COUNT_NAME "adbc.statistic.row_count" +/// @} + /// \brief The name of the canonical option for whether autocommit is /// enabled. /// @@ -811,8 +867,12 @@ struct ADBC_EXPORT AdbcDriver { AdbcStatusCode (*DatabaseGetOption)(struct AdbcDatabase*, const char*, const char**, struct AdbcError*); + AdbcStatusCode (*DatabaseGetOptionBytes)(struct AdbcDatabase*, const char*, + const uint8_t**, size_t*, struct AdbcError*); AdbcStatusCode (*DatabaseGetOptionInt)(struct AdbcDatabase*, const char*, int64_t*, struct AdbcError*); + AdbcStatusCode (*DatabaseSetOptionBytes)(struct AdbcDatabase*, const char*, + const uint8_t*, size_t, struct AdbcError*); AdbcStatusCode (*DatabaseGetOptionDouble)(struct AdbcDatabase*, const char*, double*, struct AdbcError*); AdbcStatusCode (*DatabaseSetOptionInt)(struct AdbcDatabase*, const char*, int64_t, @@ -820,12 +880,30 @@ struct ADBC_EXPORT AdbcDriver { AdbcStatusCode (*DatabaseSetOptionDouble)(struct AdbcDatabase*, const char*, double, struct AdbcError*); + AdbcStatusCode (*ConnectionCancel)(struct AdbcConnection*, struct AdbcError*); + AdbcStatusCode (*ConnectionGetFunctions)(struct AdbcConnection*, const char*, + const char*, const char*, + struct ArrowArrayStream*, struct AdbcError*); AdbcStatusCode (*ConnectionGetOption)(struct AdbcConnection*, const char*, const char**, struct AdbcError*); + AdbcStatusCode (*ConnectionGetOptionBytes)(struct AdbcDatabase*, const char*, + const uint8_t**, size_t*, struct AdbcError*); AdbcStatusCode (*ConnectionGetOptionInt)(struct AdbcConnection*, const char*, int64_t*, struct AdbcError*); AdbcStatusCode (*ConnectionGetOptionDouble)(struct AdbcConnection*, const char*, double*, struct AdbcError*); + AdbcStatusCode (*ConnectionGetProcedures)(struct AdbcConnection*, const char*, + const char*, const char*, + struct ArrowArrayStream*, struct AdbcError*); + AdbcStatusCode (*ConnectionGetTableStatistics)(struct AdbcConnection*, const char*, + const char*, const char*, char, + struct ArrowArrayStream*, + struct AdbcError*); + AdbcStatusCode (*ConnectionGetTypes)(struct AdbcConnection*, const char*, const char*, + const char*, struct ArrowSchema*, + struct AdbcError*); + AdbcStatusCode (*ConnectionSetOptionBytes)(struct AdbcDatabase*, const char*, + const uint8_t*, size_t, struct AdbcError*); AdbcStatusCode (*ConnectionSetOptionInt)(struct AdbcConnection*, const char*, int64_t, struct AdbcError*); AdbcStatusCode (*ConnectionSetOptionDouble)(struct AdbcConnection*, const char*, double, @@ -836,10 +914,14 @@ struct ADBC_EXPORT AdbcDriver { struct AdbcError*); AdbcStatusCode (*StatementGetOption)(struct AdbcStatement*, const char*, const char**, struct AdbcError*); + AdbcStatusCode (*StatementGetOptionBytes)(struct AdbcDatabase*, const char*, + const uint8_t**, size_t*, struct AdbcError*); AdbcStatusCode (*StatementGetOptionInt)(struct AdbcStatement*, const char*, int64_t*, struct AdbcError*); AdbcStatusCode (*StatementGetOptionDouble)(struct AdbcStatement*, const char*, double*, struct AdbcError*); + AdbcStatusCode (*StatementSetOptionBytes)(struct AdbcDatabase*, const char*, + const uint8_t*, size_t, struct AdbcError*); AdbcStatusCode (*StatementSetOptionInt)(struct AdbcStatement*, const char*, int64_t, struct AdbcError*); AdbcStatusCode (*StatementSetOptionDouble)(struct AdbcStatement*, const char*, double, @@ -907,6 +989,34 @@ AdbcStatusCode AdbcDatabaseNew(struct AdbcDatabase* database, struct AdbcError* AdbcStatusCode AdbcDatabaseGetOption(struct AdbcDatabase* database, const char* key, const char** value, struct AdbcError* error); +/// \brief Get a bytestring option of the database. +/// +/// This must always be thread-safe (other operations are not). +/// +/// The returned option value is only valid until the next call to +/// GetOption or Release. +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] database The database. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] length The option value length. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcDatabaseGetOptionBytes(struct AdbcDatabase* database, const char* key, + const uint8_t** value, size_t* length, + struct AdbcError* error); + /// \brief Get an integer option of the database. /// /// This must always be thread-safe (other operations are not). @@ -968,6 +1078,22 @@ ADBC_EXPORT AdbcStatusCode AdbcDatabaseSetOption(struct AdbcDatabase* database, const char* key, const char* value, struct AdbcError* error); +/// \brief Set a bytestring option on a database. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] database The database. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[in] length The option value length. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized +ADBC_EXPORT +AdbcStatusCode AdbcDatabaseSetOptionBytes(struct AdbcDatabase* database, const char* key, + const uint8_t* value, size_t length, + struct AdbcError* error); + /// \brief Set an integer option on a database. /// /// \since ADBC API revision 1.1.0 @@ -1042,6 +1168,22 @@ ADBC_EXPORT AdbcStatusCode AdbcConnectionSetOption(struct AdbcConnection* connection, const char* key, const char* value, struct AdbcError* error); +/// \brief Set a bytestring option on a connection. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] connection The connection. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[in] length The option value length. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized +ADBC_EXPORT +AdbcStatusCode AdbcConnectionSetOptionBytes(struct AdbcConnection* connection, + const char* key, const uint8_t* value, + size_t length, struct AdbcError* error); + /// \brief Set an integer option. /// /// Options may be set before AdbcConnectionInit. Some drivers may @@ -1095,6 +1237,112 @@ ADBC_EXPORT AdbcStatusCode AdbcConnectionRelease(struct AdbcConnection* connection, struct AdbcError* error); +/// \brief Cancel the in-progress operation on a connection. +/// +/// This can be called during AdbcConnectionGetObjects (or similar), +/// or while consuming an ArrowArrayStream returned from such. +/// Calling this function should make the other functions return +/// ADBC_STATUS_CANCELLED (from ADBC functions) or ECANCELED (from +/// methods of ArrowArrayStream). +/// +/// This must always be thread-safe (other operations are not). +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// +/// \param[in] connection The connection to cancel. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// +/// \return ADBC_STATUS_INVALID_STATE if there is no operation to cancel. +/// \return ADBC_STATUS_UNKNOWN if the operation could not be cancelled. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionCancel(struct AdbcConnection* connection, + struct AdbcError* error); + +/// \brief Get a hierarchical view of system and user-defined functions. +/// +/// The result is an Arrow dataset with the following schema: +/// +/// | Field Name | Field Type | +/// |--------------------------|-------------------------| +/// | catalog_name | utf8 | +/// | catalog_db_schemas | list | +/// +/// DB_SCHEMA_SCHEMA is a Struct with fields: +/// +/// | Field Name | Field Type | +/// |--------------------------|-------------------------| +/// | db_schema_name | utf8 | +/// | db_schema_functions | list | +/// +/// FUNCTION_SCHEMA is a Struct with fields: +/// +/// | Field Name | Field Type | Comments | +/// |--------------------------|-------------------------|----------| +/// | function_name | utf8 not null | | +/// | remarks | utf8 | (1) | +/// | function_type | int16 | (2) | +/// | specific_name | utf8 | (3) | +/// | function_columns | list | | +/// +/// 1. Database-specific description of the function. +/// 2. The kind of function. Should be null if not known, 1 if the function +/// does not return a table, or 2 if the function does return a table. +/// 3. An additional name that uniquely identifies the function within its +/// schema. +/// +/// COLUMN_SCHEMA is a Struct with fields: +/// +/// | Field Name | Field Type | Comments | +/// |--------------------------|-------------------------|----------| +/// | column_name | utf8 | | +/// | column_type | int16 | (1) | +/// | ordinal_position | int32 | (2) | +/// | remarks | utf8 | (3) | +/// | xdbc_data_type | int16 | (4) | +/// | xdbc_type_name | utf8 | (4) | +/// | xdbc_precision | int32 | (4) | +/// | xdbc_length | int32 | (4) | +/// | xdbc_scale | int16 | (4) | +/// | xdbc_radix | int16 | (4) | +/// | xdbc_nullable | int16 | (4) | +/// | xdbc_char_octet_length | int32 | (4) | +/// | xdbc_is_nullable | utf8 | (4) | +/// +/// 1. Whether this row describes an IN parameter (1), INOUT parameter (2), +/// OUT parameter (3), return value (4), result set column (5), or unknown +/// (null). +/// 2. The column's ordinal position in the input parameters, output +/// parameters, or result set (respectively starting from 1). Or, 0 if the +/// row describes the function's return value. +/// 3. Database-specific description of the column. +/// 4. Optional value. Should be null if not supported by the driver. +/// xdbc_ values are meant to provide JDBC/ODBC-compatible metadata +/// in an agnostic manner. +/// +/// This AdbcConnection must outlive the returned ArrowArrayStream. +/// +/// \param[in] connection The database connection. +/// \param[in] catalog Only show functions in the given catalog. If NULL, do +/// not filter by catalog. If an empty string, only show functions without a +/// catalog. May be a search pattern (see section documentation). +/// \param[in] db_schema Only show functions in the given database schema. If +/// NULL, do not filter by database schema. If an empty string, only show +/// functions without a database schema. May be a search pattern (see +/// section documentation). +/// \param[in] function_name Only show functions with the given name. If NULL, +/// do not filter by name. May be a search pattern (see section +/// documentation). +/// \param[out] out The result set. +/// \param[out] error Error details, if an error occurs. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetFunctions(struct AdbcConnection* connection, + const char* catalog, const char* db_schema, + const char* function_name, + struct ArrowArrayStream* out, + struct AdbcError* error); + /// \defgroup adbc-connection-metadata Metadata /// Functions for retrieving metadata about the database. /// @@ -1299,6 +1547,34 @@ AdbcStatusCode AdbcConnectionGetObjects(struct AdbcConnection* connection, int d AdbcStatusCode AdbcConnectionGetOption(struct AdbcConnection* connection, const char* key, const char** value, struct AdbcError* error); +/// \brief Get a bytestring option of the connection. +/// +/// This must always be thread-safe (other operations are not). +/// +/// The returned option value is only valid until the next call to +/// GetOption or Release. +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] connection The connection. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] length The option value length. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcConnectionGetOptionBytes(struct AdbcConnection* connection, + const char* key, const uint8_t** value, + size_t* length, struct AdbcError* error); + /// \brief Get an integer option of the connection. /// /// This must always be thread-safe (other operations are not). @@ -1347,6 +1623,92 @@ AdbcStatusCode AdbcConnectionGetOptionDouble(struct AdbcConnection* connection, const char* key, double* value, struct AdbcError* error); +/// \brief Get a hierarchical view of stored procedures. +/// +/// The result is an Arrow dataset with the following schema: +/// +/// | Field Name | Field Type | +/// |--------------------------|-------------------------| +/// | catalog_name | utf8 | +/// | catalog_db_schemas | list | +/// +/// DB_SCHEMA_SCHEMA is a Struct with fields: +/// +/// | Field Name | Field Type | +/// |--------------------------|-------------------------| +/// | db_schema_name | utf8 | +/// | db_schema_procedures | list | +/// +/// PROCEDURE_SCHEMA is a Struct with fields: +/// +/// | Field Name | Field Type | Comments | +/// |--------------------------|-------------------------|----------| +/// | procedure_name | utf8 not null | | +/// | remarks | utf8 | (1) | +/// | procedure_type | int16 | (2) | +/// | specific_name | utf8 | (3) | +/// | procedure_columns | list | | +/// +/// 1. Database-specific description of the procedure. +/// 2. The kind of procedure. Should be null if not known, 1 if the procedure +/// does not return a value, or 2 if the procedure does return a value. +/// 3. An additional name that uniquely identifies the procedure within its +/// schema. +/// +/// COLUMN_SCHEMA is a Struct with fields: +/// +/// | Field Name | Field Type | Comments | +/// |--------------------------|-------------------------|----------| +/// | column_name | utf8 | | +/// | column_type | int16 | (1) | +/// | ordinal_position | int32 | (2) | +/// | remarks | utf8 | (3) | +/// | xdbc_data_type | int16 | (4) | +/// | xdbc_type_name | utf8 | (4) | +/// | xdbc_precision | int32 | (4) | +/// | xdbc_length | int32 | (4) | +/// | xdbc_scale | int16 | (4) | +/// | xdbc_radix | int16 | (4) | +/// | xdbc_nullable | int16 | (4) | +/// | xdbc_column_def | utf8 | (4) | +/// | xdbc_sql_data_type | int32 | (4) | +/// | xdbc_sql_datetime_sub | int32 | (4) | +/// | xdbc_char_octet_length | int32 | (4) | +/// | xdbc_is_nullable | utf8 | (4) | +/// +/// 1. Whether this row describes an IN parameter (1), INOUT parameter (2), +/// OUT parameter (3), return value (4), result set column (5), or unknown +/// (null). +/// 2. The column's ordinal position in the input parameters, output +/// parameters, or result set (respectively starting from 1). Or, 0 if the +/// row describes the procedure's return value. +/// 3. Database-specific description of the column. +/// 4. Optional value. Should be null if not supported by the driver. +/// xdbc_ values are meant to provide JDBC/ODBC-compatible metadata +/// in an agnostic manner. +/// +/// This AdbcConnection must outlive the returned ArrowArrayStream. +/// +/// \param[in] connection The database connection. +/// \param[in] catalog Only show procedures in the given catalog. If NULL, do +/// not filter by catalog. If an empty string, only show procedures without +/// a catalog. May be a search pattern (see section documentation). +/// \param[in] db_schema Only show procedures in the given database schema. If +/// NULL, do not filter by database schema. If an empty string, only show +/// procedures without a database schema. May be a search pattern (see +/// section documentation). +/// \param[in] procedure_name Only show procedures with the given name. If +/// NULL, do not filter by name. May be a search pattern (see section +/// documentation). +/// \param[out] out The result set. +/// \param[out] error Error details, if an error occurs. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetProcedures(struct AdbcConnection* connection, + const char* catalog, const char* db_schema, + const char* procedure_name, + struct ArrowArrayStream* out, + struct AdbcError* error); + /// \brief Get the Arrow schema of a table. /// /// \param[in] connection The database connection. @@ -1362,6 +1724,50 @@ AdbcStatusCode AdbcConnectionGetTableSchema(struct AdbcConnection* connection, struct ArrowSchema* schema, struct AdbcError* error); +/// \brief Get statistics about the data distribution of table(s). +/// +/// The result is an Arrow dataset with the following schema: +/// +/// | Field Name | Field Type | Comments | +/// |--------------------------|----------------------------------| -------- | +/// | catalog_name | utf8 | | +/// | db_schema_name | utf8 | | +/// | table_name | utf8 not null | | +/// | column_name | utf8 | (1) | +/// | statistic_name | dictionary not null | (2) | +/// | statistic_value | float64 not null | | +/// | statistic_is_approximate | bool not null | (3) | +/// +/// 1. If null, then the statistic applies to the entire table. +/// 2. A dictionary-encoded statistic name. Values in [0, 1024) are +/// reserved for ADBC use. Other values are free for +/// implementation-specific statistics. For the names and +/// definitions of predefined statistic types, see \ref +/// adbc-table-statistics. +/// 3. If true, then the value is approximate or best-effort. +/// +/// This AdbcConnection must outlive the returned ArrowArrayStream. +/// +/// \param[in] connection The database connection. +/// \param[in] catalog The catalog (or nullptr). May be a search +/// pattern (see section documentation). +/// \param[in] db_schema The database schema (or nullptr). May be a +/// search pattern (see section documentation). +/// \param[in] table_name The table name (or nullptr). May be a +/// search pattern (see section documentation). +/// \param[in] approximate If zero, request exact values of +/// statistics, else allow for best-effort values. The database may +/// return approximate values regardless, as indicated in the result. +/// \param[out] out The result set. +/// \param[out] error Error details, if an error occurs. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetTableStatistics(struct AdbcConnection* connection, + const char* catalog, + const char* db_schema, + const char* table_name, char approximate, + struct ArrowArrayStream* out, + struct AdbcError* error); + /// \brief Get a list of table types in the database. /// /// The result is an Arrow dataset with the following schema: @@ -1380,6 +1786,66 @@ AdbcStatusCode AdbcConnectionGetTableTypes(struct AdbcConnection* connection, struct ArrowArrayStream* out, struct AdbcError* error); +/// \brief Get a view of types supported by the database. +/// +/// The result is an Arrow schema with one field per type. This represents +/// the driver's mapping of the database type to an Arrow type. +/// +/// Each top-level field may have the following metadata fields: +/// +/// - adbc:catalog_name +/// - adbc:db_schema_name +/// - adbc:supertype_catalog_name +/// - adbc:supertype_db_schema_name +/// - adbc:supertype_name +/// +/// Both top-level fields and child fields may have the following metadata +/// fields: +/// +/// - adbc:remarks (1) +/// - adbc:specific_name (2) +/// - adbc:xdbc_data_type (3) +/// - adbc:xdbc_type_name (3) +/// - adbc:xdbc_size (3) +/// - adbc:xdbc_decimal_digits (3) +/// - adbc:xdbc_num_prec_radix (3) +/// - adbc:xdbc_nullable (3) +/// - adbc:xdbc_remarks (3) +/// - adbc:xdbc_attr_def (3) +/// - adbc:xdbc_sql_data_type (3) +/// - adbc:xdbc_sql_datetime_sub (3) +/// - adbc:xdbc_char_octet_length (3) +/// - adbc:xdbc_is_nullable (3) +/// - adbc:xdbc_scope_catalog (3) +/// - adbc:xdbc_scope_schema (3) +/// - adbc:xdbc_scope_table (3) +/// - adbc:xdbc_scope_data_type (3) +/// +/// 1. Database-specific description of the type. +/// 2. An additional name that uniquely identifies the type within its +/// schema. +/// 3. xdbc_ values are meant to provide JDBC/ODBC-compatible metadata +/// in an agnostic manner. +/// +/// \param[in] connection The database connection. +/// \param[in] catalog Only show types in the given catalog. If NULL, do +/// not filter by catalog. If an empty string, only show types without +/// a catalog. May be a search pattern (see section documentation). +/// \param[in] db_schema Only show types in the given database schema. If +/// NULL, do not filter by database schema. If an empty string, only show +/// types without a database schema. May be a search pattern (see +/// section documentation). +/// \param[in] type_name Only show types with the given name. If +/// NULL, do not filter by name. May be a search pattern (see section +/// documentation). +/// \param[out] out The result schema. +/// \param[out] error Error details, if an error occurs. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetTypes(struct AdbcConnection* connection, + const char* catalog, const char* db_schema, + const char* type_name, struct ArrowSchema* out, + struct AdbcError* error); + /// @} /// \defgroup adbc-connection-partition Partitioned Results @@ -1494,6 +1960,9 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement, /// /// This invalidates any prior result sets. /// +/// Depending on the driver, this may require first executing +/// AdbcStatementPrepare. +/// /// \since ADBC API revision 1.1.0 /// \addtogroup adbc-1.1.0 /// @@ -1639,6 +2108,34 @@ AdbcStatusCode AdbcStatementCancel(struct AdbcStatement* statement, AdbcStatusCode AdbcStatementGetOption(struct AdbcStatement* statement, const char* key, const char** value, struct AdbcError* error); +/// \brief Get a bytestring option of the statement. +/// +/// This must always be thread-safe (other operations are not). +/// +/// The returned option value is only valid until the next call to +/// GetOption or Release. +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] statement The statement. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] length The option value length. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcStatementGetOptionBytes(struct AdbcStatement* statement, + const char* key, const uint8_t** value, + size_t* length, struct AdbcError* error); + /// \brief Get an integer option of the statement. /// /// This must always be thread-safe (other operations are not). @@ -1717,6 +2214,22 @@ ADBC_EXPORT AdbcStatusCode AdbcStatementSetOption(struct AdbcStatement* statement, const char* key, const char* value, struct AdbcError* error); +/// \brief Set a bytestring option on a statement. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] statement The statement. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[in] length The option value length. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized +ADBC_EXPORT +AdbcStatusCode AdbcStatementSetOptionBytes(struct AdbcStatement* statement, + const char* key, const uint8_t* value, + size_t length, struct AdbcError* error); + /// \brief Set an integer option on a statement. /// /// \since ADBC API revision 1.1.0 diff --git a/c/driver_manager/adbc_driver_manager.cc b/c/driver_manager/adbc_driver_manager.cc index e0315d8662..aa2fe4957e 100644 --- a/c/driver_manager/adbc_driver_manager.cc +++ b/c/driver_manager/adbc_driver_manager.cc @@ -160,6 +160,11 @@ AdbcStatusCode DatabaseSetOptionDouble(struct AdbcDatabase* database, const char return ADBC_STATUS_NOT_IMPLEMENTED; } +AdbcStatusCode ConnectionCancel(struct AdbcConnection* connection, + struct AdbcError* error) { + return ADBC_STATUS_NOT_IMPLEMENTED; +} + AdbcStatusCode ConnectionCommit(struct AdbcConnection*, struct AdbcError* error) { return ADBC_STATUS_NOT_IMPLEMENTED; } @@ -533,6 +538,14 @@ AdbcStatusCode AdbcDatabaseRelease(struct AdbcDatabase* database, return status; } +AdbcStatusCode AdbcConnectionCancel(struct AdbcConnection* connection, + struct AdbcError* error) { + if (!connection->private_driver) { + return ADBC_STATUS_INVALID_STATE; + } + return connection->private_driver->ConnectionCancel(connection, error); +} + AdbcStatusCode AdbcConnectionCommit(struct AdbcConnection* connection, struct AdbcError* error) { if (!connection->private_driver) { @@ -801,6 +814,14 @@ AdbcStatusCode AdbcStatementBindStream(struct AdbcStatement* statement, return statement->private_driver->StatementBindStream(statement, stream, error); } +AdbcStatusCode AdbcStatementCancel(struct AdbcStatement* statement, + struct AdbcError* error) { + if (!statement->private_driver) { + return ADBC_STATUS_INVALID_STATE; + } + return statement->private_driver->StatementCancel(statement, error); +} + // XXX: cpplint gets confused here if declared as 'struct ArrowSchema* schema' AdbcStatusCode AdbcStatementExecutePartitions(struct AdbcStatement* statement, ArrowSchema* schema, @@ -1197,6 +1218,7 @@ AdbcStatusCode AdbcLoadDriverFromInitFunc(AdbcDriverInitFunc init_func, int vers FILL_DEFAULT(driver, DatabaseSetOptionInt); FILL_DEFAULT(driver, DatabaseSetOptionDouble); + FILL_DEFAULT(driver, ConnectionCancel); FILL_DEFAULT(driver, ConnectionGetOption); FILL_DEFAULT(driver, ConnectionGetOptionInt); FILL_DEFAULT(driver, ConnectionGetOptionDouble); diff --git a/go/adbc/drivermgr/adbc.h b/go/adbc/drivermgr/adbc.h index 154e881255..9017c538a9 100644 --- a/go/adbc/drivermgr/adbc.h +++ b/go/adbc/drivermgr/adbc.h @@ -279,6 +279,14 @@ struct ADBC_EXPORT AdbcError { /// point to an AdbcDriver. #define ADBC_VERSION_1_0_0 1000000 +/// \brief ADBC revision 1.1.0. +/// +/// When passed to an AdbcDriverInitFunc(), the driver parameter must +/// point to an AdbcDriver. +/// +/// \addtogroup adbc-1.1.0 +#define ADBC_VERSION_1_1_0 1001000 + /// \brief Canonical option value for enabling an option. /// /// For use as the value in SetOption calls. @@ -288,6 +296,64 @@ struct ADBC_EXPORT AdbcError { /// For use as the value in SetOption calls. #define ADBC_OPTION_VALUE_DISABLED "false" +/// \brief Canonical option name for URIs. +/// +/// Should be used as the expected option name to specify a URI for +/// any ADBC driver. +/// +/// The type is char*. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_OPTION_URI "uri" +/// \brief Canonical option name for usernames. +/// +/// Should be used as the expected option name to specify a username +/// to a driver for authentication. +/// +/// The type is char*. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_OPTION_USERNAME "username" +/// \brief Canonical option name for passwords. +/// +/// Should be used as the expected option name to specify a password +/// for authentication to a driver. +/// +/// The type is char*. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_OPTION_PASSWORD "password" +/// \brief Canonical option name for error details. +/// +/// Should be used as the expected option name to retrieve error +/// details from the driver. This allows drivers to return custom, +/// structured error information (for example, JSON or Protocol +/// Buffers) that can be optionally parsed by clients, beyond the +/// standard AdbcError fields, without having to encode it in the +/// error message. The encoding of the data is driver-defined. +/// +/// This can be called immediately after any API call that returns an +/// error. Additionally, if an ArrowArrayStream returned from an +/// AdbcConnection or an AdbcStatement returns an error, this can be +/// immediately called from the associated AdbcConnection or +/// AdbcStatement to get further error details (if available). Making +/// other API calls with that connection or statement may clear this +/// error value. +/// +/// Drivers may provide multiple error details. Each call to +/// GetOptionBinary will return the next error detail. The driver +/// should return ADBC_STATUS_NOT_FOUND if there are no (more) error +/// details. +/// +/// The type is uint8_t*. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_OPTION_ERROR_DETAILS "error_details" + /// \brief The database vendor/product name (e.g. the server name). /// (type: utf8). /// @@ -315,6 +381,16 @@ struct ADBC_EXPORT AdbcError { /// /// \see AdbcConnectionGetInfo #define ADBC_INFO_DRIVER_ARROW_VERSION 102 +/// \brief The driver ADBC API version (type: int64). +/// +/// The value should be one of the ADBC_VERSION constants. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \see AdbcConnectionGetInfo +/// \see ADBC_VERSION_1_0_0 +/// \see ADBC_VERSION_1_1_0 +#define ADBC_INFO_DRIVER_ADBC_VERSION 103 /// \brief Return metadata on catalogs, schemas, tables, and columns. /// @@ -337,18 +413,100 @@ struct ADBC_EXPORT AdbcError { /// \see AdbcConnectionGetObjects #define ADBC_OBJECT_DEPTH_COLUMNS ADBC_OBJECT_DEPTH_ALL +/// \defgroup adbc-table-statistics ADBC Statistic Types +/// Standard statistic names for AdbcConnectionGetTableStatistics. +/// @{ + +/// \brief The dictionary-encoded name of the byte width statistic. +#define ADBC_STATISTIC_BYTE_WIDTH_KEY 0 +/// \brief The byte width statistic. The average size in bytes of a +/// row in the column. +/// +/// For example, for a string column, this would roughly be the +/// average length of a string. +#define ADBC_STATISTIC_BYTE_WIDTH_NAME "adbc.statistic.byte_width" +/// \brief The dictionary-encoded name of the NDV statistic. +#define ADBC_STATISTIC_DISTINCT_VALUE_COUNT_KEY 1 +/// \brief The distinct value count (NDV) statistic. The number of +/// distinct values in the column. +#define ADBC_STATISTIC_DISTINCT_VALUE_COUNT_NAME "adbc.statistic.distinct_count" +/// \brief The dictionary-encoded name of the null percentage statistic. +#define ADBC_STATISTIC_NULL_PERCENTAGE_KEY 2 +/// \brief The null percentage statistic. The percentage of values +/// that are null in the column (range [0, 1]). +#define ADBC_STATISTIC_NULL_PERCENTAGE_NAME "adbc.statistic.null_percentage" +/// \brief The dictionary-encoded name of the row count statistic. +#define ADBC_STATISTIC_ROW_COUNT_KEY 3 +/// \brief The row count statistic. The number of rows in the column +/// or table. +#define ADBC_STATISTIC_ROW_COUNT_NAME "adbc.statistic.row_count" +/// @} + /// \brief The name of the canonical option for whether autocommit is /// enabled. /// +/// The type is char*. +/// /// \see AdbcConnectionSetOption #define ADBC_CONNECTION_OPTION_AUTOCOMMIT "adbc.connection.autocommit" /// \brief The name of the canonical option for whether the current /// connection should be restricted to being read-only. /// +/// The type is char*. +/// /// \see AdbcConnectionSetOption #define ADBC_CONNECTION_OPTION_READ_ONLY "adbc.connection.readonly" +/// \brief The name of the canonical option for the current catalog. +/// +/// The type is char*. +/// +/// \see AdbcConnectionGetOption +/// \see AdbcConnectionSetOption +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_CONNECTION_OPTION_CURRENT_CATALOG "adbc.connection.catalog" + +/// \brief The name of the canonical option for the current schema. +/// +/// The type is char*. +/// +/// \see AdbcConnectionGetOption +/// \see AdbcConnectionSetOption +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_CONNECTION_OPTION_CURRENT_DB_SCHEMA "adbc.connection.db_schema" + +/// \brief The name of the canonical option for making query execution +/// nonblocking. +/// +/// When enabled, AdbcStatementExecutePartitions will return +/// partitions as soon as they are available, instead of returning +/// them all at the end. When there are no more to return, it will +/// return an empty set of partitions. AdbcStatementExecuteQuery and +/// AdbcStatementExecuteSchema are not affected. +/// +/// The default is ADBC_OPTION_VALUE_DISABLED. +/// +/// The type is char*. +/// +/// \see AdbcStatementSetOption +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_STATEMENT_OPTION_INCREMENTAL "adbc.statement.exec.incremental" + +/// \brief The name of the option for getting the progress of a query. +/// +/// Progress is a value in [0.0, 1.0]. +/// +/// The type is double. +/// +/// \see AdbcStatementGetOptionDouble +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_STATEMENT_OPTION_PROGRESS "adbc.statement.exec.progress" + /// \brief The name of the canonical option for setting the isolation /// level of a transaction. /// @@ -357,6 +515,8 @@ struct ADBC_EXPORT AdbcError { /// isolation level is not supported by a driver, it should return an /// appropriate error. /// +/// The type is char*. +/// /// \see AdbcConnectionSetOption #define ADBC_CONNECTION_OPTION_ISOLATION_LEVEL \ "adbc.connection.transaction.isolation_level" @@ -449,8 +609,12 @@ struct ADBC_EXPORT AdbcError { /// exist. If the table exists but has a different schema, /// ADBC_STATUS_ALREADY_EXISTS should be raised. Else, data should be /// appended to the target table. +/// +/// The type is char*. #define ADBC_INGEST_OPTION_TARGET_TABLE "adbc.ingest.target_table" /// \brief Whether to create (the default) or append. +/// +/// The type is char*. #define ADBC_INGEST_OPTION_MODE "adbc.ingest.mode" /// \brief Create the table and insert data; error if the table exists. #define ADBC_INGEST_OPTION_MODE_CREATE "adbc.ingest.mode.create" @@ -458,6 +622,17 @@ struct ADBC_EXPORT AdbcError { /// 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_APPEND "adbc.ingest.mode.append" +/// \brief Create the table and insert data; drop the original table +/// if it already exists. +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_INGEST_OPTION_MODE_REPLACE "adbc.ingest.mode.replace" +/// \brief 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). +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_INGEST_OPTION_MODE_CREATE_APPEND "adbc.ingest.mode.create_append" /// @} @@ -667,8 +842,112 @@ struct ADBC_EXPORT AdbcDriver { struct AdbcError*); AdbcStatusCode (*StatementSetSubstraitPlan)(struct AdbcStatement*, const uint8_t*, size_t, struct AdbcError*); + + /// \defgroup adbc-1.1.0 ADBC API Revision 1.1.0 + /// + /// Functions added in ADBC 1.1.0. For backwards compatibility, + /// these members must not be accessed unless the version passed to + /// the AdbcDriverInitFunc is greater than or equal to + /// ADBC_VERSION_1_1_0. + /// + /// For a 1.0.0 driver being loaded by a 1.1.0 driver manager: the + /// 1.1.0 manager will allocate the new, expanded AdbcDriver struct + /// and attempt to have the driver initialize it with + /// ADBC_VERSION_1_1_0. This must return an error, after which the + /// driver will try again with ADBC_VERSION_1_0_0. The driver must + /// not access the new fields, which will carry undefined values. + /// + /// For a 1.1.0 driver being loaded by a 1.0.0 driver manager: the + /// 1.0.0 manager will allocate the old AdbcDriver struct and + /// attempt to have the driver initialize it with + /// ADBC_VERSION_1_0_0. The driver must not access the new fields, + /// and should initialize the old fields. + /// + /// @{ + + AdbcStatusCode (*DatabaseGetOption)(struct AdbcDatabase*, const char*, const char**, + struct AdbcError*); + AdbcStatusCode (*DatabaseGetOptionBytes)(struct AdbcDatabase*, const char*, + const uint8_t**, size_t*, struct AdbcError*); + AdbcStatusCode (*DatabaseGetOptionInt)(struct AdbcDatabase*, const char*, int64_t*, + struct AdbcError*); + AdbcStatusCode (*DatabaseSetOptionBytes)(struct AdbcDatabase*, const char*, + const uint8_t*, size_t, struct AdbcError*); + AdbcStatusCode (*DatabaseGetOptionDouble)(struct AdbcDatabase*, const char*, double*, + struct AdbcError*); + AdbcStatusCode (*DatabaseSetOptionInt)(struct AdbcDatabase*, const char*, int64_t, + struct AdbcError*); + AdbcStatusCode (*DatabaseSetOptionDouble)(struct AdbcDatabase*, const char*, double, + struct AdbcError*); + + AdbcStatusCode (*ConnectionCancel)(struct AdbcConnection*, struct AdbcError*); + AdbcStatusCode (*ConnectionGetFunctions)(struct AdbcConnection*, const char*, + const char*, const char*, + struct ArrowArrayStream*, struct AdbcError*); + AdbcStatusCode (*ConnectionGetOption)(struct AdbcConnection*, const char*, const char**, + struct AdbcError*); + AdbcStatusCode (*ConnectionGetOptionBytes)(struct AdbcDatabase*, const char*, + const uint8_t**, size_t*, struct AdbcError*); + AdbcStatusCode (*ConnectionGetOptionInt)(struct AdbcConnection*, const char*, int64_t*, + struct AdbcError*); + AdbcStatusCode (*ConnectionGetOptionDouble)(struct AdbcConnection*, const char*, + double*, struct AdbcError*); + AdbcStatusCode (*ConnectionGetProcedures)(struct AdbcConnection*, const char*, + const char*, const char*, + struct ArrowArrayStream*, struct AdbcError*); + AdbcStatusCode (*ConnectionGetTableStatistics)(struct AdbcConnection*, const char*, + const char*, const char*, char, + struct ArrowArrayStream*, + struct AdbcError*); + AdbcStatusCode (*ConnectionGetTypes)(struct AdbcConnection*, const char*, const char*, + const char*, struct ArrowSchema*, + struct AdbcError*); + AdbcStatusCode (*ConnectionSetOptionBytes)(struct AdbcDatabase*, const char*, + const uint8_t*, size_t, struct AdbcError*); + AdbcStatusCode (*ConnectionSetOptionInt)(struct AdbcConnection*, const char*, int64_t, + struct AdbcError*); + AdbcStatusCode (*ConnectionSetOptionDouble)(struct AdbcConnection*, const char*, double, + struct AdbcError*); + + AdbcStatusCode (*StatementCancel)(struct AdbcStatement*, struct AdbcError*); + AdbcStatusCode (*StatementExecuteSchema)(struct AdbcStatement*, struct ArrowSchema*, + struct AdbcError*); + AdbcStatusCode (*StatementGetOption)(struct AdbcStatement*, const char*, const char**, + struct AdbcError*); + AdbcStatusCode (*StatementGetOptionBytes)(struct AdbcDatabase*, const char*, + const uint8_t**, size_t*, struct AdbcError*); + AdbcStatusCode (*StatementGetOptionInt)(struct AdbcStatement*, const char*, int64_t*, + struct AdbcError*); + AdbcStatusCode (*StatementGetOptionDouble)(struct AdbcStatement*, const char*, double*, + struct AdbcError*); + AdbcStatusCode (*StatementSetOptionBytes)(struct AdbcDatabase*, const char*, + const uint8_t*, size_t, struct AdbcError*); + AdbcStatusCode (*StatementSetOptionInt)(struct AdbcStatement*, const char*, int64_t, + struct AdbcError*); + AdbcStatusCode (*StatementSetOptionDouble)(struct AdbcStatement*, const char*, double, + struct AdbcError*); + + /// @} }; +/// \brief 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. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_DRIVER_1_0_0_SIZE (offsetof(struct AdbcDriver, DatabaseGetOption)) + +/// \brief 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. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +#define ADBC_DRIVER_1_1_0_SIZE (sizeof(struct AdbcDriver)) + /// @} /// \addtogroup adbc-database @@ -684,16 +963,165 @@ struct ADBC_EXPORT AdbcDriver { ADBC_EXPORT AdbcStatusCode AdbcDatabaseNew(struct AdbcDatabase* database, struct AdbcError* error); +/// \brief Get a string option of the database. +/// +/// This must always be thread-safe (other operations are not). +/// +/// The returned option value is only valid until the next call to +/// GetOption or Release. +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] database The database. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcDatabaseGetOption(struct AdbcDatabase* database, const char* key, + const char** value, struct AdbcError* error); + +/// \brief Get a bytestring option of the database. +/// +/// This must always be thread-safe (other operations are not). +/// +/// The returned option value is only valid until the next call to +/// GetOption or Release. +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] database The database. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] length The option value length. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcDatabaseGetOptionBytes(struct AdbcDatabase* database, const char* key, + const uint8_t** value, size_t* length, + struct AdbcError* error); + +/// \brief Get an integer option of the database. +/// +/// This must always be thread-safe (other operations are not). +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the integer +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] database The database. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcDatabaseGetOptionInt(struct AdbcDatabase* database, const char* key, + int64_t* value, struct AdbcError* error); + +/// \brief Get a double option of the database. +/// +/// This must always be thread-safe (other operations are not). +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the double +/// representation of an integer option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] database The database. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcDatabaseGetOptionDouble(struct AdbcDatabase* database, const char* key, + double* value, struct AdbcError* error); + /// \brief Set a char* option. /// /// Options may be set before AdbcDatabaseInit. Some drivers may /// support setting options after initialization as well. /// +/// \param[in] database The database. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. /// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized ADBC_EXPORT AdbcStatusCode AdbcDatabaseSetOption(struct AdbcDatabase* database, const char* key, const char* value, struct AdbcError* error); +/// \brief Set a bytestring option on a database. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] database The database. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[in] length The option value length. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized +ADBC_EXPORT +AdbcStatusCode AdbcDatabaseSetOptionBytes(struct AdbcDatabase* database, const char* key, + const uint8_t* value, size_t length, + struct AdbcError* error); + +/// \brief Set an integer option on a database. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] database The database. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized +ADBC_EXPORT +AdbcStatusCode AdbcDatabaseSetOptionInt(struct AdbcDatabase* database, const char* key, + int64_t value, struct AdbcError* error); + +/// \brief Set a double option on a database. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] database The database. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized +ADBC_EXPORT +AdbcStatusCode AdbcDatabaseSetOptionDouble(struct AdbcDatabase* database, const char* key, + double value, struct AdbcError* error); + /// \brief Finish setting options and initialize the database. /// /// Some drivers may support setting options after initialization @@ -730,11 +1158,68 @@ AdbcStatusCode AdbcConnectionNew(struct AdbcConnection* connection, /// Options may be set before AdbcConnectionInit. Some drivers may /// support setting options after initialization as well. /// +/// \param[in] connection The database connection. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. /// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized ADBC_EXPORT AdbcStatusCode AdbcConnectionSetOption(struct AdbcConnection* connection, const char* key, const char* value, struct AdbcError* error); +/// \brief Set a bytestring option on a connection. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] connection The connection. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[in] length The option value length. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized +ADBC_EXPORT +AdbcStatusCode AdbcConnectionSetOptionBytes(struct AdbcConnection* connection, + const char* key, const uint8_t* value, + size_t length, struct AdbcError* error); + +/// \brief Set an integer option. +/// +/// Options may be set before AdbcConnectionInit. Some drivers may +/// support setting options after initialization as well. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] connection The database connection. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized +ADBC_EXPORT +AdbcStatusCode AdbcConnectionSetOptionInt(struct AdbcConnection* connection, + const char* key, int64_t value, + struct AdbcError* error); + +/// \brief Set a double option. +/// +/// Options may be set before AdbcConnectionInit. Some drivers may +/// support setting options after initialization as well. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] connection The database connection. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized +ADBC_EXPORT +AdbcStatusCode AdbcConnectionSetOptionDouble(struct AdbcConnection* connection, + const char* key, double value, + struct AdbcError* error); + /// \brief Finish setting options and initialize the connection. /// /// Some drivers may support setting options after initialization @@ -752,6 +1237,112 @@ ADBC_EXPORT AdbcStatusCode AdbcConnectionRelease(struct AdbcConnection* connection, struct AdbcError* error); +/// \brief Cancel the in-progress operation on a connection. +/// +/// This can be called during AdbcConnectionGetObjects (or similar), +/// or while consuming an ArrowArrayStream returned from such. +/// Calling this function should make the other functions return +/// ADBC_STATUS_CANCELLED (from ADBC functions) or ECANCELED (from +/// methods of ArrowArrayStream). +/// +/// This must always be thread-safe (other operations are not). +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// +/// \param[in] connection The connection to cancel. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// +/// \return ADBC_STATUS_INVALID_STATE if there is no operation to cancel. +/// \return ADBC_STATUS_UNKNOWN if the operation could not be cancelled. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionCancel(struct AdbcConnection* connection, + struct AdbcError* error); + +/// \brief Get a hierarchical view of system and user-defined functions. +/// +/// The result is an Arrow dataset with the following schema: +/// +/// | Field Name | Field Type | +/// |--------------------------|-------------------------| +/// | catalog_name | utf8 | +/// | catalog_db_schemas | list | +/// +/// DB_SCHEMA_SCHEMA is a Struct with fields: +/// +/// | Field Name | Field Type | +/// |--------------------------|-------------------------| +/// | db_schema_name | utf8 | +/// | db_schema_functions | list | +/// +/// FUNCTION_SCHEMA is a Struct with fields: +/// +/// | Field Name | Field Type | Comments | +/// |--------------------------|-------------------------|----------| +/// | function_name | utf8 not null | | +/// | remarks | utf8 | (1) | +/// | function_type | int16 | (2) | +/// | specific_name | utf8 | (3) | +/// | function_columns | list | | +/// +/// 1. Database-specific description of the function. +/// 2. The kind of function. Should be null if not known, 1 if the function +/// does not return a table, or 2 if the function does return a table. +/// 3. An additional name that uniquely identifies the function within its +/// schema. +/// +/// COLUMN_SCHEMA is a Struct with fields: +/// +/// | Field Name | Field Type | Comments | +/// |--------------------------|-------------------------|----------| +/// | column_name | utf8 | | +/// | column_type | int16 | (1) | +/// | ordinal_position | int32 | (2) | +/// | remarks | utf8 | (3) | +/// | xdbc_data_type | int16 | (4) | +/// | xdbc_type_name | utf8 | (4) | +/// | xdbc_precision | int32 | (4) | +/// | xdbc_length | int32 | (4) | +/// | xdbc_scale | int16 | (4) | +/// | xdbc_radix | int16 | (4) | +/// | xdbc_nullable | int16 | (4) | +/// | xdbc_char_octet_length | int32 | (4) | +/// | xdbc_is_nullable | utf8 | (4) | +/// +/// 1. Whether this row describes an IN parameter (1), INOUT parameter (2), +/// OUT parameter (3), return value (4), result set column (5), or unknown +/// (null). +/// 2. The column's ordinal position in the input parameters, output +/// parameters, or result set (respectively starting from 1). Or, 0 if the +/// row describes the function's return value. +/// 3. Database-specific description of the column. +/// 4. Optional value. Should be null if not supported by the driver. +/// xdbc_ values are meant to provide JDBC/ODBC-compatible metadata +/// in an agnostic manner. +/// +/// This AdbcConnection must outlive the returned ArrowArrayStream. +/// +/// \param[in] connection The database connection. +/// \param[in] catalog Only show functions in the given catalog. If NULL, do +/// not filter by catalog. If an empty string, only show functions without a +/// catalog. May be a search pattern (see section documentation). +/// \param[in] db_schema Only show functions in the given database schema. If +/// NULL, do not filter by database schema. If an empty string, only show +/// functions without a database schema. May be a search pattern (see +/// section documentation). +/// \param[in] function_name Only show functions with the given name. If NULL, +/// do not filter by name. May be a search pattern (see section +/// documentation). +/// \param[out] out The result set. +/// \param[out] error Error details, if an error occurs. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetFunctions(struct AdbcConnection* connection, + const char* catalog, const char* db_schema, + const char* function_name, + struct ArrowArrayStream* out, + struct AdbcError* error); + /// \defgroup adbc-connection-metadata Metadata /// Functions for retrieving metadata about the database. /// @@ -765,6 +1356,8 @@ AdbcStatusCode AdbcConnectionRelease(struct AdbcConnection* connection, /// concurrent active statements and it must execute a SQL query /// internally in order to implement the metadata function). /// +/// This AdbcConnection must outlive the returned ArrowArrayStream. +/// /// Some functions accept "search pattern" arguments, which are /// strings that can contain the special character "%" to match zero /// or more characters, or "_" to match exactly one character. (See @@ -799,6 +1392,10 @@ AdbcStatusCode AdbcConnectionRelease(struct AdbcConnection* connection, /// for ADBC usage. Drivers/vendors will ignore requests for /// unrecognized codes (the row will be omitted from the result). /// +/// Since ADBC 1.1.0: the range [500, 1_000) is reserved for "XDBC" +/// information, which is the same metadata provided by the same info +/// code range in the Arrow Flight SQL GetSqlInfo RPC. +/// /// \param[in] connection The connection to query. /// \param[in] info_codes A list of metadata codes to fetch, or NULL /// to fetch all. @@ -891,6 +1488,8 @@ AdbcStatusCode AdbcConnectionGetInfo(struct AdbcConnection* connection, /// | fk_table | utf8 not null | /// | fk_column_name | utf8 not null | /// +/// This AdbcConnection must outlive the returned ArrowArrayStream. +/// /// \param[in] connection The database connection. /// \param[in] depth The level of nesting to display. If 0, display /// all levels. If 1, display only catalogs (i.e. catalog_schemas @@ -922,6 +1521,194 @@ AdbcStatusCode AdbcConnectionGetObjects(struct AdbcConnection* connection, int d struct ArrowArrayStream* out, struct AdbcError* error); +/// \brief Get a string option of the connection. +/// +/// This must always be thread-safe (other operations are not). +/// +/// The returned option value is only valid until the next call to +/// GetOption or Release. +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] connection The database connection. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcConnectionGetOption(struct AdbcConnection* connection, const char* key, + const char** value, struct AdbcError* error); + +/// \brief Get a bytestring option of the connection. +/// +/// This must always be thread-safe (other operations are not). +/// +/// The returned option value is only valid until the next call to +/// GetOption or Release. +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] connection The connection. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] length The option value length. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcConnectionGetOptionBytes(struct AdbcConnection* connection, + const char* key, const uint8_t** value, + size_t* length, struct AdbcError* error); + +/// \brief Get an integer option of the connection. +/// +/// This must always be thread-safe (other operations are not). +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] connection The database connection. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcConnectionGetOptionInt(struct AdbcConnection* connection, + const char* key, int64_t* value, + struct AdbcError* error); + +/// \brief Get a double option of the connection. +/// +/// This must always be thread-safe (other operations are not). +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] connection The database connection. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcConnectionGetOptionDouble(struct AdbcConnection* connection, + const char* key, double* value, + struct AdbcError* error); + +/// \brief Get a hierarchical view of stored procedures. +/// +/// The result is an Arrow dataset with the following schema: +/// +/// | Field Name | Field Type | +/// |--------------------------|-------------------------| +/// | catalog_name | utf8 | +/// | catalog_db_schemas | list | +/// +/// DB_SCHEMA_SCHEMA is a Struct with fields: +/// +/// | Field Name | Field Type | +/// |--------------------------|-------------------------| +/// | db_schema_name | utf8 | +/// | db_schema_procedures | list | +/// +/// PROCEDURE_SCHEMA is a Struct with fields: +/// +/// | Field Name | Field Type | Comments | +/// |--------------------------|-------------------------|----------| +/// | procedure_name | utf8 not null | | +/// | remarks | utf8 | (1) | +/// | procedure_type | int16 | (2) | +/// | specific_name | utf8 | (3) | +/// | procedure_columns | list | | +/// +/// 1. Database-specific description of the procedure. +/// 2. The kind of procedure. Should be null if not known, 1 if the procedure +/// does not return a value, or 2 if the procedure does return a value. +/// 3. An additional name that uniquely identifies the procedure within its +/// schema. +/// +/// COLUMN_SCHEMA is a Struct with fields: +/// +/// | Field Name | Field Type | Comments | +/// |--------------------------|-------------------------|----------| +/// | column_name | utf8 | | +/// | column_type | int16 | (1) | +/// | ordinal_position | int32 | (2) | +/// | remarks | utf8 | (3) | +/// | xdbc_data_type | int16 | (4) | +/// | xdbc_type_name | utf8 | (4) | +/// | xdbc_precision | int32 | (4) | +/// | xdbc_length | int32 | (4) | +/// | xdbc_scale | int16 | (4) | +/// | xdbc_radix | int16 | (4) | +/// | xdbc_nullable | int16 | (4) | +/// | xdbc_column_def | utf8 | (4) | +/// | xdbc_sql_data_type | int32 | (4) | +/// | xdbc_sql_datetime_sub | int32 | (4) | +/// | xdbc_char_octet_length | int32 | (4) | +/// | xdbc_is_nullable | utf8 | (4) | +/// +/// 1. Whether this row describes an IN parameter (1), INOUT parameter (2), +/// OUT parameter (3), return value (4), result set column (5), or unknown +/// (null). +/// 2. The column's ordinal position in the input parameters, output +/// parameters, or result set (respectively starting from 1). Or, 0 if the +/// row describes the procedure's return value. +/// 3. Database-specific description of the column. +/// 4. Optional value. Should be null if not supported by the driver. +/// xdbc_ values are meant to provide JDBC/ODBC-compatible metadata +/// in an agnostic manner. +/// +/// This AdbcConnection must outlive the returned ArrowArrayStream. +/// +/// \param[in] connection The database connection. +/// \param[in] catalog Only show procedures in the given catalog. If NULL, do +/// not filter by catalog. If an empty string, only show procedures without +/// a catalog. May be a search pattern (see section documentation). +/// \param[in] db_schema Only show procedures in the given database schema. If +/// NULL, do not filter by database schema. If an empty string, only show +/// procedures without a database schema. May be a search pattern (see +/// section documentation). +/// \param[in] procedure_name Only show procedures with the given name. If +/// NULL, do not filter by name. May be a search pattern (see section +/// documentation). +/// \param[out] out The result set. +/// \param[out] error Error details, if an error occurs. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetProcedures(struct AdbcConnection* connection, + const char* catalog, const char* db_schema, + const char* procedure_name, + struct ArrowArrayStream* out, + struct AdbcError* error); + /// \brief Get the Arrow schema of a table. /// /// \param[in] connection The database connection. @@ -937,6 +1724,50 @@ AdbcStatusCode AdbcConnectionGetTableSchema(struct AdbcConnection* connection, struct ArrowSchema* schema, struct AdbcError* error); +/// \brief Get statistics about the data distribution of table(s). +/// +/// The result is an Arrow dataset with the following schema: +/// +/// | Field Name | Field Type | Comments | +/// |--------------------------|----------------------------------| -------- | +/// | catalog_name | utf8 | | +/// | db_schema_name | utf8 | | +/// | table_name | utf8 not null | | +/// | column_name | utf8 | (1) | +/// | statistic_name | dictionary not null | (2) | +/// | statistic_value | float64 not null | | +/// | statistic_is_approximate | bool not null | (3) | +/// +/// 1. If null, then the statistic applies to the entire table. +/// 2. A dictionary-encoded statistic name. Values in [0, 1024) are +/// reserved for ADBC use. Other values are free for +/// implementation-specific statistics. For the names and +/// definitions of predefined statistic types, see \ref +/// adbc-table-statistics. +/// 3. If true, then the value is approximate or best-effort. +/// +/// This AdbcConnection must outlive the returned ArrowArrayStream. +/// +/// \param[in] connection The database connection. +/// \param[in] catalog The catalog (or nullptr). May be a search +/// pattern (see section documentation). +/// \param[in] db_schema The database schema (or nullptr). May be a +/// search pattern (see section documentation). +/// \param[in] table_name The table name (or nullptr). May be a +/// search pattern (see section documentation). +/// \param[in] approximate If zero, request exact values of +/// statistics, else allow for best-effort values. The database may +/// return approximate values regardless, as indicated in the result. +/// \param[out] out The result set. +/// \param[out] error Error details, if an error occurs. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetTableStatistics(struct AdbcConnection* connection, + const char* catalog, + const char* db_schema, + const char* table_name, char approximate, + struct ArrowArrayStream* out, + struct AdbcError* error); + /// \brief Get a list of table types in the database. /// /// The result is an Arrow dataset with the following schema: @@ -945,6 +1776,8 @@ AdbcStatusCode AdbcConnectionGetTableSchema(struct AdbcConnection* connection, /// ---------------|-------------- /// table_type | utf8 not null /// +/// This AdbcConnection must outlive the returned ArrowArrayStream. +/// /// \param[in] connection The database connection. /// \param[out] out The result set. /// \param[out] error Error details, if an error occurs. @@ -953,6 +1786,66 @@ AdbcStatusCode AdbcConnectionGetTableTypes(struct AdbcConnection* connection, struct ArrowArrayStream* out, struct AdbcError* error); +/// \brief Get a view of types supported by the database. +/// +/// The result is an Arrow schema with one field per type. This represents +/// the driver's mapping of the database type to an Arrow type. +/// +/// Each top-level field may have the following metadata fields: +/// +/// - adbc:catalog_name +/// - adbc:db_schema_name +/// - adbc:supertype_catalog_name +/// - adbc:supertype_db_schema_name +/// - adbc:supertype_name +/// +/// Both top-level fields and child fields may have the following metadata +/// fields: +/// +/// - adbc:remarks (1) +/// - adbc:specific_name (2) +/// - adbc:xdbc_data_type (3) +/// - adbc:xdbc_type_name (3) +/// - adbc:xdbc_size (3) +/// - adbc:xdbc_decimal_digits (3) +/// - adbc:xdbc_num_prec_radix (3) +/// - adbc:xdbc_nullable (3) +/// - adbc:xdbc_remarks (3) +/// - adbc:xdbc_attr_def (3) +/// - adbc:xdbc_sql_data_type (3) +/// - adbc:xdbc_sql_datetime_sub (3) +/// - adbc:xdbc_char_octet_length (3) +/// - adbc:xdbc_is_nullable (3) +/// - adbc:xdbc_scope_catalog (3) +/// - adbc:xdbc_scope_schema (3) +/// - adbc:xdbc_scope_table (3) +/// - adbc:xdbc_scope_data_type (3) +/// +/// 1. Database-specific description of the type. +/// 2. An additional name that uniquely identifies the type within its +/// schema. +/// 3. xdbc_ values are meant to provide JDBC/ODBC-compatible metadata +/// in an agnostic manner. +/// +/// \param[in] connection The database connection. +/// \param[in] catalog Only show types in the given catalog. If NULL, do +/// not filter by catalog. If an empty string, only show types without +/// a catalog. May be a search pattern (see section documentation). +/// \param[in] db_schema Only show types in the given database schema. If +/// NULL, do not filter by database schema. If an empty string, only show +/// types without a database schema. May be a search pattern (see +/// section documentation). +/// \param[in] type_name Only show types with the given name. If +/// NULL, do not filter by name. May be a search pattern (see section +/// documentation). +/// \param[out] out The result schema. +/// \param[out] error Error details, if an error occurs. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetTypes(struct AdbcConnection* connection, + const char* catalog, const char* db_schema, + const char* type_name, struct ArrowSchema* out, + struct AdbcError* error); + /// @} /// \defgroup adbc-connection-partition Partitioned Results @@ -973,6 +1866,8 @@ AdbcStatusCode AdbcConnectionGetTableTypes(struct AdbcConnection* connection, /// /// A partition can be retrieved from AdbcPartitions. /// +/// This AdbcConnection must outlive the returned ArrowArrayStream. +/// /// \param[in] connection The connection to use. This does not have /// to be the same connection that the partition was created on. /// \param[in] serialized_partition The partition descriptor. @@ -1042,7 +1937,11 @@ AdbcStatusCode AdbcStatementRelease(struct AdbcStatement* statement, /// \brief Execute a statement and get the results. /// -/// This invalidates any prior result sets. +/// This invalidates any prior result sets. This AdbcStatement must +/// outlive the returned ArrowArrayStream. +/// +/// Since ADBC 1.1.0: releasing the returned ArrowArrayStream without +/// consuming it fully is equivalent to calling AdbcStatementCancel. /// /// \param[in] statement The statement to execute. /// \param[out] out The results. Pass NULL if the client does not @@ -1056,6 +1955,28 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement, struct ArrowArrayStream* out, int64_t* rows_affected, struct AdbcError* error); +/// \brief Get the schema of the result set of a query without +/// executing it. +/// +/// This invalidates any prior result sets. +/// +/// Depending on the driver, this may require first executing +/// AdbcStatementPrepare. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// +/// \param[in] statement The statement to execute. +/// \param[out] out The result schema. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver does not support this. +ADBC_EXPORT +AdbcStatusCode AdbcStatementExecuteSchema(struct AdbcStatement* statement, + struct ArrowSchema* schema, + struct AdbcError* error); + /// \brief Turn this statement into a prepared statement to be /// executed multiple times. /// @@ -1138,6 +2059,130 @@ AdbcStatusCode AdbcStatementBindStream(struct AdbcStatement* statement, struct ArrowArrayStream* stream, struct AdbcError* error); +/// \brief Cancel execution of an in-progress query. +/// +/// This can be called during AdbcStatementExecuteQuery (or similar), +/// or while consuming an ArrowArrayStream returned from such. +/// Calling this function should make the other functions return +/// ADBC_STATUS_CANCELLED (from ADBC functions) or ECANCELED (from +/// methods of ArrowArrayStream). +/// +/// This must always be thread-safe (other operations are not). +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// +/// \param[in] statement The statement to cancel. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// +/// \return ADBC_STATUS_INVALID_STATE if there is no query to cancel. +/// \return ADBC_STATUS_UNKNOWN if the query could not be cancelled. +ADBC_EXPORT +AdbcStatusCode AdbcStatementCancel(struct AdbcStatement* statement, + struct AdbcError* error); + +/// \brief Get a string option of the statement. +/// +/// This must always be thread-safe (other operations are not). +/// +/// The returned option value is only valid until the next call to +/// GetOption or Release. +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] statement The statement. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcStatementGetOption(struct AdbcStatement* statement, const char* key, + const char** value, struct AdbcError* error); + +/// \brief Get a bytestring option of the statement. +/// +/// This must always be thread-safe (other operations are not). +/// +/// The returned option value is only valid until the next call to +/// GetOption or Release. +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] statement The statement. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] length The option value length. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcStatementGetOptionBytes(struct AdbcStatement* statement, + const char* key, const uint8_t** value, + size_t* length, struct AdbcError* error); + +/// \brief Get an integer option of the statement. +/// +/// This must always be thread-safe (other operations are not). +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] statement The statement. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcStatementGetOptionInt(struct AdbcStatement* statement, const char* key, + int64_t* value, struct AdbcError* error); + +/// \brief Get a double option of the statement. +/// +/// This must always be thread-safe (other operations are not). +/// +/// For standard options, drivers must always support getting the +/// option value (if they support getting option values at all) via +/// the type specified in the option. (For example, an option set via +/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers +/// may also support getting a converted option value via other +/// getters if needed. (For example, getting the string +/// representation of a double option.) +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] statement The statement. +/// \param[in] key The option to get. +/// \param[out] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized. +AdbcStatusCode AdbcStatementGetOptionDouble(struct AdbcStatement* statement, + const char* key, double* value, + struct AdbcError* error); + /// \brief Get the schema for bound parameters. /// /// This retrieves an Arrow schema describing the number, names, and @@ -1159,10 +2204,61 @@ AdbcStatusCode AdbcStatementGetParameterSchema(struct AdbcStatement* statement, struct AdbcError* error); /// \brief Set a string option on a statement. +/// \param[in] statement The statement. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized. ADBC_EXPORT AdbcStatusCode AdbcStatementSetOption(struct AdbcStatement* statement, const char* key, const char* value, struct AdbcError* error); +/// \brief Set a bytestring option on a statement. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] statement The statement. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[in] length The option value length. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized +ADBC_EXPORT +AdbcStatusCode AdbcStatementSetOptionBytes(struct AdbcStatement* statement, + const char* key, const uint8_t* value, + size_t length, struct AdbcError* error); + +/// \brief Set an integer option on a statement. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] statement The statement. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized +ADBC_EXPORT +AdbcStatusCode AdbcStatementSetOptionInt(struct AdbcStatement* statement, const char* key, + int64_t value, struct AdbcError* error); + +/// \brief Set a double option on a statement. +/// +/// \since ADBC API revision 1.1.0 +/// \addtogroup adbc-1.1.0 +/// \param[in] statement The statement. +/// \param[in] key The option to set. +/// \param[in] value The option value. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized +ADBC_EXPORT +AdbcStatusCode AdbcStatementSetOptionDouble(struct AdbcStatement* statement, + const char* key, double value, + struct AdbcError* error); + /// \addtogroup adbc-statement-partition /// @{ @@ -1198,7 +2294,15 @@ AdbcStatusCode AdbcStatementExecutePartitions(struct AdbcStatement* statement, /// driver. /// /// Although drivers may choose any name for this function, the -/// recommended name is "AdbcDriverInit". +/// recommended name is "AdbcDriverInit", or a name derived from the +/// name of the driver's shared library as follows: remove the 'lib' +/// prefix (on Unix systems) and all file extensions, then PascalCase +/// the driver name, append Init, and prepend Adbc (if not already +/// there). For example: +/// +/// - libadbc_driver_sqlite.so.2.0.0 -> AdbcDriverSqliteInit +/// - adbc_driver_sqlite.dll -> AdbcDriverSqliteInit +/// - proprietary_driver.dll -> AdbcProprietaryDriverInit /// /// \param[in] version The ADBC revision to attempt to initialize (see /// ADBC_VERSION_1_0_0).