From d58d2a9682c5623aabba7de91dbb6808f9794fe9 Mon Sep 17 00:00:00 2001 From: Matt Topol Date: Wed, 22 Oct 2025 15:33:50 -0400 Subject: [PATCH 1/5] feat: async and multi-result set APIs --- c/include/arrow-adbc/adbc.h | 228 ++++++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h index a55f645ed7..144a2355d9 100644 --- a/c/include/arrow-adbc/adbc.h +++ b/c/include/arrow-adbc/adbc.h @@ -142,6 +142,102 @@ struct ArrowArrayStream { #endif // ARROW_C_STREAM_INTERFACE #endif // ARROW_FLAG_DICTIONARY_ORDERED +#ifndef ARROW_C_DEVICE_DATA_INTERFACE +#define ARROW_C_DEVICE_DATA_INTERFACE + +// Device type for the allocated memory +typedef int32_t ArrowDeviceType; + +// CPU device, same as using ArrowArray directly +#define ARROW_DEVICE_CPU 1 +// CUDA GPU Device +#define ARROW_DEVICE_CUDA 2 +// Pinned CUDA CPU memory by cudaMallocHost +#define ARROW_DEVICE_CUDA_HOST 3 +// OpenCL Device +#define ARROW_DEVICE_OPENCL 4 +// Vulkan buffer for next-gen graphics +#define ARROW_DEVICE_VULKAN 7 +// Metal for Apple GPU +#define ARROW_DEVICE_METAL 8 +// Verilog simulator buffer +#define ARROW_DEVICE_VPI 9 +// ROCm GPUs for AMD GPUs +#define ARROW_DEVICE_ROCM 10 +// Pinned ROCm CPU memory allocated by hipMallocHost +#define ARROW_DEVICE_ROCM_HOST 11 +// Reserved for extension +// +// used to quickly test extension devices, semantics +// can differ based on implementation +#define ARROW_DEVICE_EXT_DEV 12 +// CUDA managed/unified memory allocated by cudaMallocManaged +#define ARROW_DEVICE_CUDA_MANAGED 13 +// Unified shared memory allocated on a oneAPI +// non-partitioned device. +// +// A call to the oneAPI runtime is required to determine the +// device type, the USM allocation type and the sycl context +// that it is bound to. +#define ARROW_DEVICE_ONEAPI 14 +// GPU support for next-gen WebGPU standard +#define ARROW_DEVICE_WEBGPU 15 +// Qualcomm Hexagon DSP +#define ARROW_DEVICE_HEXAGON 16 + +struct ArrowDeviceArray { + struct ArrowArray array; + int64_t device_id; + ArrowDeviceType device_type; + void* sync_event; + + // reserved bytes for future expansion + int64_t reserved[3]; +}; + +#endif // ARROW_C_DEVICE_DATA_INTERFACE + +#ifndef ARROW_C_ASYNC_STREAM_INTERFACE +#define ARROW_C_ASYNC_STREAM_INTERFACE + +struct ArrowAsyncTask { + int (*extract_data)(struct ArrowArrayTask* self, struct ArrowDeviceArray* out); + + void* private_data; +}; + +struct ArrowAsyncProducer { + ArrowDeviceType device_type; + + void (*request)(struct ArrowAsyncProducer* self, int64_t n); + void (*cancel)(struct ArrowAsyncProducer* self); + + void (*release)(struct ArrowAsyncProducer* self); + const char* additional_metadata; + void* private_data; +}; + +struct ArrowAsyncDeviceStreamHandler { + // consumer-specific handlers + int (*on_schema)(struct ArrowAsyncDeviceStreamHandler* self, + struct ArrowSchema* stream_schema); + int (*on_next_task)(struct ArrowAsyncDeviceStreamHandler* self, + struct ArrowAsyncTask* task, const char* metadata); + void (*on_error)(struct ArrowAsyncDeviceStreamHandler* self, int code, + const char* message, const char* metadata); + + // release callback + void (*release)(struct ArrowAsyncDeviceStreamHandler* self); + + // must be populated before calling any callbacks + struct ArrowAsyncProducer* producer; + + // opaque handler-specific data + void* private_data; +}; + +#endif // ARROW_C_ASYNC_STREAM_INTERFACE + //! @endcond /// @} @@ -1135,6 +1231,44 @@ struct ADBC_EXPORT AdbcDriver { struct AdbcError*); /// @} + + /// \defgroup adbc-1.2.0 ADBC API Revision 1.2.0 + /// + /// Functions added in ADBC 1.2.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_2_0. + /// + /// For an earlier driver being loaded by a 1.2.0 driver manager: the + /// 1.2.0 manager will allocate the new, expanded AdbcDriver struct + /// and attempt to have the driver initialize it with + /// ADBC_VERSION_1_2_0. This must return an error, after which the + /// driver will try again with ADBC_VERSION_1_1_0, and so on. The + /// driver must not access the new fields, which will carry undefined + /// values. + /// + /// For a 1.2.0 driver being loaded by an earlier driver manager: the + /// earlier manager will allocate the old AdbcDriver struct and attempt + /// to have the driver initialize it with the earlier version. The driver + /// must not access the new fields, and should initialize the old fields. + /// + /// @{ + + AdbcStatusCode (*StatementNextResultSet)(struct AdbcStatement*, + struct ArrowArrayStream*, int64_t*, + struct AdbcError*); + AdbcStatusCode (*StatementExecuteQueryAsync)(struct AdbcStatement*, + struct ArrowAsyncDeviceStreamHandler*, + int64_t*, struct AdbcError*); + AdbcStatusCode (*StatementNextResultSetAsync)(struct AdbcStatement*, + struct ArrowAsyncDeviceStreamHandler*, + int64_t*, struct AdbcError*); + AdbcStatusCode (*ConnectionReadPartitionAsync)(struct AdbcConnection*, const uint8_t*, + size_t, + struct ArrowAsyncDeviceStreamHandler*, + struct AdbcError*); + + /// @} }; /// \brief The size of the AdbcDriver structure in ADBC 1.0.0. @@ -1939,6 +2073,32 @@ AdbcStatusCode AdbcConnectionReadPartition(struct AdbcConnection* connection, struct ArrowArrayStream* out, struct AdbcError* error); +/// \brief Asynchronously read a partition of a query. The results can +/// then be read independently. +/// +/// A partition can be retrieved from AdbcPartitions. +/// +/// This AdbcConnection must outlive the ArrowAsyncDeviceStreamHandler. +/// +/// \since ADBC API revision 1.2.0 +/// +/// \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 serialized partition descriptor. +/// \param[in] serialized_length The length of the serialized partition. +/// \param[in] handler The async device stream handler whose callbacks will +/// be used to deliver results. +/// \param[out] error Error details, if an error occurs. +/// +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver does not support async +/// execution/partition reading, ADBC_STATUS_OK if the execution has started +/// successfully. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionReadPartitionAsync( + struct AdbcConnection* connection, const uint8_t* serialized_partition, + size_t serialized_length, struct ArrowAsyncDeviceStreamHandler* handler, + struct AdbcError* error); + /// @} /// \defgroup adbc-connection-transaction Transaction Semantics @@ -2013,6 +2173,74 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement, struct ArrowArrayStream* out, int64_t* rows_affected, struct AdbcError* error); +/// \brief Retrieve the next result set from a multi-statement execution +/// +/// This invalidates any prior result sets. This AdbcStatement must +/// outlive the returned ArrowArrayStream. +/// +/// \since ADBC API revision 1.2.0 +/// +/// \param[in] statement The statement to retrieve the next result set from. +/// \param[out] out The results. Pass NULL if the client does not +/// expect a result set. +/// \param[out] rows_affected The number of rows affected if known, +/// else -1. Pass NULL if the client does not want this information. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver does not support +/// multi-result set execution, ADBC_STATUS_OK if next result set is +/// being returned successfully. ADBC_STATUS_NOT_FOUND is returned +/// when there are no more result sets. +ADBC_EXPORT +AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement, + struct ArrowArrayStream* out, + int64_t* rows_affected, + struct AdbcError* error); + +/// \brief Execute a statement asynchronously and get the results. +/// +/// This will invalidate any prior result sets. This AdbcStatement must +/// outlive the returned ArrowAsyncDeviceStreamHandler. +/// +/// \since ADBC API revision 1.2.0 +/// +/// \param[in] statement The statement to execute. +/// \param[in] handler The async stream handler whose callbacks to use +/// to deliver results. +/// \param[out] rows_affected The number of rows affected if known, else -1. Pass +/// NULL if the client does not want this information. +/// \param[out] error An optional location to return an error message if necessary. +/// +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver does not support async execution, +/// ADBC_STATUS_OK if the execution has started successfully. +ADBC_EXPORT +AdbcStatusCode AdbcStatementExecuteQueryAsync( + struct AdbcStatement* statement, struct ArrowAsyncDeviceStreamHandler* handler, + int64_t* rows_affected, struct AdbcError* error); + +/// \brief Retrieve the next result set from a multi-statement execution +/// asynchronously. +/// +/// This will invalidate any prior result sets. This AdbcStatement must +/// outlive the returned ArrowAsyncDeviceStreamHandler. +/// +/// \since ADBC API revision 1.2.0 +/// +/// \param[in] statement The statement to retrieve the next result set from. +/// \param[in] handler The async stream handler whose callbacks to use to deliver results. +/// \param[out] rows_affected The number of rows affected if known, else -1. Pass +/// NULL if the client does not want this information. +/// \param[out] error An optional location to return an error message if necessary. +/// +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver does not support async execution, +/// ADBC_STATUS_OK if next result set is being returned successfully. +/// ADBC_STATUS_NOT_FOUND is returned when there are no more result sets. +ADBC_EXPORT +AdbcStatusCode AdbcStatementNextResultSetAsync( + struct AdbcStatement* statement, struct ArrowAsyncDeviceStreamHandler* handler, + int64_t* rows_affected, struct AdbcError* error); + /// \brief Get the schema of the result set of a query without /// executing it. /// From a017e4ac9ba6d66d2167970f8485e3def9d8c1f8 Mon Sep 17 00:00:00 2001 From: Matt Topol Date: Wed, 22 Oct 2025 15:36:29 -0400 Subject: [PATCH 2/5] add ADBC_VERSION_1_2_0 constant --- c/include/arrow-adbc/adbc.h | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h index 144a2355d9..a0cf050aca 100644 --- a/c/include/arrow-adbc/adbc.h +++ b/c/include/arrow-adbc/adbc.h @@ -519,6 +519,14 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// \since ADBC API revision 1.1.0 #define ADBC_VERSION_1_1_0 1001000 +/// \brief ADBC revision 1.2.0. +/// +/// When passed to an AdbcDriverInitFunc(), the driver parameter must +/// point to an AdbcDriver. +/// +/// \since ADBC API revision 1.2.0 +#define ADBC_VERSION_1_2_0 1002000 + /// \brief Canonical option value for enabling an option. /// /// For use as the value in SetOption calls. From 11042fe60d777c75ae784d8a80156b0ec261c6be Mon Sep 17 00:00:00 2001 From: Matt Topol Date: Wed, 22 Oct 2025 15:40:58 -0400 Subject: [PATCH 3/5] fix definition --- c/include/arrow-adbc/adbc.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h index a0cf050aca..6b7a4c0bae 100644 --- a/c/include/arrow-adbc/adbc.h +++ b/c/include/arrow-adbc/adbc.h @@ -201,7 +201,7 @@ struct ArrowDeviceArray { #define ARROW_C_ASYNC_STREAM_INTERFACE struct ArrowAsyncTask { - int (*extract_data)(struct ArrowArrayTask* self, struct ArrowDeviceArray* out); + int (*extract_data)(struct ArrowAsyncTask* self, struct ArrowDeviceArray* out); void* private_data; }; From 8793b13f2c242a06f563d2686aab9293156e776e Mon Sep 17 00:00:00 2001 From: Matt Topol Date: Thu, 23 Oct 2025 12:43:13 -0400 Subject: [PATCH 4/5] add more functions from comments --- c/include/arrow-adbc/adbc.h | 294 ++++++++++++++++++++++++++++++++++-- 1 file changed, 283 insertions(+), 11 deletions(-) diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h index 6b7a4c0bae..1c1b29aaed 100644 --- a/c/include/arrow-adbc/adbc.h +++ b/c/include/arrow-adbc/adbc.h @@ -1262,19 +1262,58 @@ struct ADBC_EXPORT AdbcDriver { /// /// @{ + AdbcStatusCode (*ConnectionGetInfoAsync)(struct AdbcConnection*, const uint32_t*, + size_t, struct ArrowAsyncDeviceStreamHandler*, + struct AdbcError*); + AdbcStatusCode (*ConnectionGetObjectsAsync)(struct AdbcConnection*, int, const char*, + const char*, const char*, const char**, + const char*, + struct ArrowAsyncDeviceStreamHandler*, + struct AdbcError*); + AdbcStatusCode (*ConnectionGetTableSchemaAsync)(struct AdbcConnection*, const char*, + const char*, const char*, + struct ArrowAsyncDeviceStreamHandler*, + struct AdbcError*); + AdbcStatusCode (*ConnectionGetTableTypesAsync)(struct AdbcConnection*, + struct ArrowAsyncDeviceStreamHandler*, + struct AdbcError*); + AdbcStatusCode (*ConnectionGetStatisticsAsync)(struct AdbcConnection*, const char*, + const char*, const char*, char, + struct ArrowAsyncDeviceStreamHandler*, + struct AdbcError*); + AdbcStatusCode (*ConnectionGetStatisticNamesAsync)( + struct AdbcConnection*, struct ArrowAsyncDeviceStreamHandler*, struct AdbcError*); + AdbcStatusCode (*ConnectionReadPartitionAsync)(struct AdbcConnection*, const uint8_t*, + size_t, + struct ArrowAsyncDeviceStreamHandler*, + struct AdbcError*); + + AdbcStatusCode (*StatementExecuteSchemaAsync)(struct AdbcStatement*, + void (*callback)(struct AdbcStatement*, + struct ArrowSchema*, + struct AdbcError*), + struct AdbcError*); + AdbcStatusCode (*StatementNextResultSetSchema)(struct AdbcStatement*, + struct ArrowSchema*, struct AdbcError*); + AdbcStatusCode (*StatementNextResultSetSchemaAsync)( + struct AdbcStatement*, + void (*callback)(struct AdbcStatement*, struct ArrowSchema*, struct AdbcError*), + struct AdbcError*); + + AdbcStatusCode (*StatementExecutePartitionsAsync)( + struct AdbcStatement*, + void (*callback)(struct AdbcStatement*, struct ArrowSchema*, struct AdbcPartitions*, + int64_t*, struct AdbcError*), + struct AdbcError*); AdbcStatusCode (*StatementNextResultSet)(struct AdbcStatement*, struct ArrowArrayStream*, int64_t*, struct AdbcError*); AdbcStatusCode (*StatementExecuteQueryAsync)(struct AdbcStatement*, struct ArrowAsyncDeviceStreamHandler*, - int64_t*, struct AdbcError*); + struct AdbcError*); AdbcStatusCode (*StatementNextResultSetAsync)(struct AdbcStatement*, struct ArrowAsyncDeviceStreamHandler*, - int64_t*, struct AdbcError*); - AdbcStatusCode (*ConnectionReadPartitionAsync)(struct AdbcConnection*, const uint8_t*, - size_t, - struct ArrowAsyncDeviceStreamHandler*, - struct AdbcError*); + struct AdbcError*); /// @} }; @@ -1695,6 +1734,29 @@ AdbcStatusCode AdbcConnectionGetInfo(struct AdbcConnection* connection, struct ArrowArrayStream* out, struct AdbcError* error); +/// \brief Asynchronous version of AdbcConnectionGetInfo. +/// +/// See the documentation for AdbcConnectionGetInfo for details. The +/// AdbcConnection must outlive the populated ArrowAsyncDeviceStreamHandler. +/// +/// \since ADBC API revision 1.2.0 +/// +/// \param[in] connection The connection to query. +/// \param[in] info_codes A list of metadata codes to fetch, or NULL +/// to fetch all. +/// \param[in] info_codes_length The length of the info_codes +/// parameter. Ignored if info_codes is NULL. +/// \param[in] out_handler The result set handler. +/// \param[out] error Error details, if an error occurs. +/// +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver does not support async +/// execution, ADBC_STATUS_OK on success, or another error code on failure. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetInfoAsync( + struct AdbcConnection* connection, const uint32_t* info_codes, + size_t info_codes_length, struct ArrowAsyncDeviceStreamHandler* out_handler, + struct AdbcError* error); + /// \brief Get a hierarchical view of all catalogs, database schemas, /// tables, and columns. /// @@ -1807,6 +1869,49 @@ AdbcStatusCode AdbcConnectionGetObjects(struct AdbcConnection* connection, int d struct ArrowArrayStream* out, struct AdbcError* error); +/// \brief Asynchronous version of AdbcConnectionGetObjects to retrieve +/// metadata about catalogs, database schemas, tables, and columns. +/// +/// See documentation for AdbcConnectionGetObjects for details about +/// the result schema. +/// +/// This AdbcConnection must outlive the populated ArrowAsyncDeviceStreamHandler. +/// +/// \since ADBC API revision 1.2.0 +/// +/// \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 +/// will be null). If 2, display only catalogs and schemas +/// (i.e. db_schema_tables will be null), and so on. +/// \param[in] catalog Only show tables in the given catalog. If NULL, +/// do not filter by catalog. If an empty string, only show tables +/// without a catalog. May be a search pattern (see section +/// documentation). +/// \param[in] db_schema Only show tables in the given database schema. If +/// NULL, do not filter by database schema. If an empty string, only show +/// tables without a database schema. May be a search pattern (see section +/// documentation). +/// \param[in] table_name Only show tables with the given name. If NULL, do not +/// filter by name. May be a search pattern (see section documentation). +/// \param[in] table_type Only show tables matching one of the given table +/// types. If NULL, show tables of any type. Valid table types can be fetched +/// from GetTableTypes. Terminate the list with a NULL entry. +/// \param[in] column_name Only show columns with the given name. If +/// NULL, do not filter by name. May be a search pattern (see +/// section documentation). +/// \param[in] handler The async stream handler. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if async execution is not implemented, +/// ADBC_STATUS_OK if successful. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetObjectsAsync( + struct AdbcConnection* connection, int depth, const char* catalog, + const char* db_schema, const char* table_name, const char** table_type, + const char* column_name, struct ArrowAsyncDeviceStreamHandler* handler, + struct AdbcError* error); + /// \brief Get a string option of the connection. /// /// This must always be thread-safe (other operations are not), though @@ -1995,6 +2100,39 @@ AdbcStatusCode AdbcConnectionGetStatistics(struct AdbcConnection* connection, struct ArrowArrayStream* out, struct AdbcError* error); +/// \brief Asynchronous version of AdbcConnectionGetStatistics to +/// retrieve statistics about the data distribution of table(s). +/// +/// See documentation for AdbcConnectionGetStatistics for details about +/// the result schema. +/// +/// This AdbcConnection must outlive the populated ArrowAsyncDeviceStreamHandler. +/// +/// \since ADBC API revision 1.2.0 +/// +/// \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, approximate, or cached +/// values. The database may return approximate values regardless, +/// as indicated in the result. Requesting exact values may be +/// expensive or unsupported. +/// \param[in] handler The async stream handler. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if async execution is not implemented, +/// ADBC_STATUS_OK if successful. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetStatisticsAsync( + struct AdbcConnection* connection, const char* catalog, const char* db_schema, + const char* table_name, char approximate, + struct ArrowAsyncDeviceStreamHandler* handler, struct AdbcError* error); + /// \brief Get the names of statistics specific to this driver. /// /// The result is an Arrow dataset with the following schema: @@ -2013,6 +2151,27 @@ AdbcStatusCode AdbcConnectionGetStatisticNames(struct AdbcConnection* connection struct ArrowArrayStream* out, struct AdbcError* error); +/// \brief Asynchronous version of AdbcConnectionGetStatisticNames to +/// retrieve the names of statistics specific to this driver. +/// +/// See documentation for AdbcConnectionGetStatisticNames for details about +/// the result schema. +/// +/// This AdbcConnection must outlive the populated ArrowAsyncDeviceStreamHandler. +/// +/// \since ADBC API revision 1.2.0 +/// +/// \param[in] connection The database connection. +/// \param[in] handler The async stream handler. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if async execution is not implemented, +/// ADBC_STATUS_OK if successful. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetStatisticNamesAsync( + struct AdbcConnection* connection, struct ArrowAsyncDeviceStreamHandler* handler, + struct AdbcError* error); + /// \brief Get the Arrow schema of a table. /// /// \param[in] connection The database connection. @@ -2046,6 +2205,26 @@ AdbcStatusCode AdbcConnectionGetTableTypes(struct AdbcConnection* connection, struct ArrowArrayStream* out, struct AdbcError* error); +/// \brief Asynchronous version of AdbcConnectionGetTableTypes to +/// retrieve a list of table types in the database. +/// +/// See documentation for AdbcConnectionGetTableTypes for details about +/// the result schema. +/// +/// This AdbcConnection must outlive the populated ArrowAsyncDeviceStreamHandler. +/// +/// \since ADBC API revision 1.2.0 +/// \param[in] connection The database connection. +/// \param[in] handler The async stream handler. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if async execution is not implemented, +/// ADBC_STATUS_OK if successful. +ADBC_EXPORT +AdbcStatusCode AdbcConnectionGetTableTypesAsync( + struct AdbcConnection* connection, struct ArrowAsyncDeviceStreamHandler* handler, + struct AdbcError* error); + /// @} /// \defgroup adbc-connection-partition Partitioned Results @@ -2086,7 +2265,12 @@ AdbcStatusCode AdbcConnectionReadPartition(struct AdbcConnection* connection, /// /// A partition can be retrieved from AdbcPartitions. /// -/// This AdbcConnection must outlive the ArrowAsyncDeviceStreamHandler. +/// This AdbcConnection must stay valid until after the callbacks in the +/// ArrowAsyncDeviceStreamHandler are invoked (or it is cancelled) and +/// it is released. +/// +/// The serialized_partition only needs to remain valid until the first +/// callback is invoked. /// /// \since ADBC API revision 1.2.0 /// @@ -2216,8 +2400,6 @@ AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement, /// \param[in] statement The statement to execute. /// \param[in] handler The async stream handler whose callbacks to use /// to deliver results. -/// \param[out] rows_affected The number of rows affected if known, else -1. Pass -/// NULL if the client does not want this information. /// \param[out] error An optional location to return an error message if necessary. /// /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver does not support async execution, @@ -2225,7 +2407,7 @@ AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement, ADBC_EXPORT AdbcStatusCode AdbcStatementExecuteQueryAsync( struct AdbcStatement* statement, struct ArrowAsyncDeviceStreamHandler* handler, - int64_t* rows_affected, struct AdbcError* error); + struct AdbcError* error); /// \brief Retrieve the next result set from a multi-statement execution /// asynchronously. @@ -2247,7 +2429,7 @@ AdbcStatusCode AdbcStatementExecuteQueryAsync( ADBC_EXPORT AdbcStatusCode AdbcStatementNextResultSetAsync( struct AdbcStatement* statement, struct ArrowAsyncDeviceStreamHandler* handler, - int64_t* rows_affected, struct AdbcError* error); + struct AdbcError* error); /// \brief Get the schema of the result set of a query without /// executing it. @@ -2270,6 +2452,78 @@ AdbcStatusCode AdbcStatementExecuteSchema(struct AdbcStatement* statement, struct ArrowSchema* schema, struct AdbcError* error); +/// \brief Retrieve the schema of the next result set from a +/// multi-statement query passed to AdbcStatementExecuteSchema. +/// +/// This invalidates any prior result sets. +/// +/// Depending on the driver, this may require first executing +/// AdbcStatementPrepare. +/// +/// \since ADBC API revision 1.2.0 +/// +/// \param[in] statement The statement to retrieve the next result set schema from. +/// \param[out] schema 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 +/// multi-result set execution, ADBC_STATUS_OK if next result set schema is +/// being returned successfully. ADBC_STATUS_NOT_FOUND is returned +/// when there are no more result sets. +ADBC_EXPORT +AdbcStatusCode AdbcStatementNextResultSetSchema(struct AdbcStatement* statement, + struct ArrowSchema* schema, + struct AdbcError* error); + +/// \brief Asynchronous version of AdbcStatementNextResultSetSchema to +/// retrieve the schema of the next result set from a +/// multi-statement query passed to AdbcStatementExecuteSchema. +/// +/// This invalidates any prior result sets. +/// +/// Depending on the driver, this may require first executing +/// AdbcStatementPrepare. +/// +/// \since ADBC API revision 1.2.0 +/// +/// \param[in] statement The statement to retrieve the next result set schema from. +/// \param[in] callback The callback to invoke with the result schema +/// once it is available. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver does not support multi-result +/// set execution, ADBC_STATUS_OK if next result set schema is being returned +/// successfully. ADBC_STATUS_NOT_FOUND is returned when there are no more result sets. +ADBC_EXPORT +AdbcStatusCode AdbcStatementNextResultSetSchemaAsync( + struct AdbcStatement* statement, + void (*callback)(struct AdbcStatement*, struct ArrowSchema*, struct AdbcError*), + struct AdbcError* error); + +/// \brief Asynchronous version of AdbcStatementExecuteSchema to 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.2.0 +/// +/// \param[in] statement The statement to execute. +/// \param[in] callback The callback to invoke with the result schema +/// once it is available. +/// \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 AdbcStatementExecuteSchemaAsync(struct AdbcStatement* statement, + void (*callback)(struct AdbcStatement*, + struct ArrowSchema*, + struct AdbcError*), + struct AdbcError* error); + /// \brief Turn this statement into a prepared statement to be /// executed multiple times. /// @@ -2599,6 +2853,24 @@ AdbcStatusCode AdbcStatementExecutePartitions(struct AdbcStatement* statement, int64_t* rows_affected, struct AdbcError* error); +/// \brief Asynchronous version of AdbcStatementExecutePartitions to +/// get the results as a partitioned result set. +/// +/// \since ADBC API revision 1.2.0 +/// \param[in] statement The statement to execute. +/// \param[in] callback The callback to invoke with the result schema and +/// partitions once they are available. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver does not support +/// partitioned results +ADBC_EXPORT +AdbcStatusCode AdbcStatementExecutePartitionsAsync( + struct AdbcStatement* statement, + void (*callback)(struct AdbcStatement*, struct ArrowSchema*, struct AdbcPartitions*, + int64_t, struct AdbcError*), + struct AdbcError* error); + /// @} /// @} From b70139e652d15b26d205d3b6141bc49f73add131 Mon Sep 17 00:00:00 2001 From: Matt Topol Date: Fri, 24 Oct 2025 15:46:51 -0400 Subject: [PATCH 5/5] add async variation of prepare --- c/include/arrow-adbc/adbc.h | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h index 1c1b29aaed..437ef1d549 100644 --- a/c/include/arrow-adbc/adbc.h +++ b/c/include/arrow-adbc/adbc.h @@ -1288,6 +1288,10 @@ struct ADBC_EXPORT AdbcDriver { struct ArrowAsyncDeviceStreamHandler*, struct AdbcError*); + AdbcStatusCode (*StatementPrepareAsync)(struct AdbcStatement*, + void (*callback)(struct AdbcStatement*, + struct AdbcError*), + struct AdbcError*); AdbcStatusCode (*StatementExecuteSchemaAsync)(struct AdbcStatement*, void (*callback)(struct AdbcStatement*, struct ArrowSchema*, @@ -2532,6 +2536,24 @@ ADBC_EXPORT AdbcStatusCode AdbcStatementPrepare(struct AdbcStatement* statement, struct AdbcError* error); +/// \brief Asynchronous version of AdbcStatementPrepare to turn this +/// statement into a prepared statement to be executed multiple times. +/// +/// This invalidates any prior result sets. +/// +/// \since ADBC API revision 1.2.0 +/// \param[in] statement The statement to prepare. +/// \param[in] callback The callback to invoke once preparation is complete. +/// \param[out] error An optional location to return an error +/// message if necessary. +/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver does not support async +/// execution, ADBC_STATUS_OK if the preparation has started successfully. +ADBC_EXPORT +AdbcStatusCode AdbcStatementPrepareAsync(struct AdbcStatement* statement, + void (*callback)(struct AdbcStatement*, + struct AdbcError*), + struct AdbcError* error); + /// \defgroup adbc-statement-sql SQL Semantics /// Functions for executing SQL queries, or querying SQL-related /// metadata. Drivers are not required to support both SQL and