feat(c/include/arrow-adbc): Add AdbcStatementRequestSchema

c/driver_manager/adbc_driver_manager.cc

@@ -1764,6 +1764,12 @@ AdbcStatusCode StatementSetSubstraitPlan(struct AdbcStatement*, const uint8_t*,
   return ADBC_STATUS_NOT_IMPLEMENTED;
 }
 
+AdbcStatusCode StatementRequestSchema(struct AdbcStatement*, struct ArrowSchema*,
+                                      struct AdbcError* error) {
+  SetError(error, "AdbcStatementRequestSchema not implemented");
+  return ADBC_STATUS_NOT_IMPLEMENTED;
+}
+
 /// Temporary state while the database is being configured.
 struct TempDatabase {
   std::unordered_map<std::string, std::string> options;
@@ -3159,6 +3165,17 @@ AdbcStatusCode AdbcStatementSetSubstraitPlan(struct AdbcStatement* statement,
                                                               error);
 }
 
+AdbcStatusCode AdbcStatementRequestSchema(struct AdbcStatement* statement,
+                                          struct ArrowSchema* schema,
+                                          struct AdbcError* error) {
+  if (!statement->private_driver) {
+    SetError(error, "AdbcStatementRequestSchema: must call AdbcStatementNew first");
+    return ADBC_STATUS_INVALID_STATE;
+  }
+  INIT_ERROR(error, statement);
+  return statement->private_driver->StatementRequestSchema(statement, schema, error);
+}
+
 const char* AdbcStatusCodeMessage(AdbcStatusCode code) {
 #define CASE(CONSTANT)         \
   case ADBC_STATUS_##CONSTANT: \
@@ -3346,6 +3363,7 @@ AdbcStatusCode AdbcLoadDriverFromInitFunc(AdbcDriverInitFunc init_func, int vers
     FILL_DEFAULT(driver, StatementSetOption);
     FILL_DEFAULT(driver, StatementSetSqlQuery);
     FILL_DEFAULT(driver, StatementSetSubstraitPlan);
+    FILL_DEFAULT(driver, StatementRequestSchema);
   }
   if (version >= ADBC_VERSION_1_1_0) {
     auto* driver = reinterpret_cast<struct AdbcDriver*>(raw_driver);

c/include/arrow-adbc/adbc.h

@@ -1255,6 +1255,10 @@ struct ADBC_EXPORT AdbcDriver {
   AdbcStatusCode (*StatementSetOptionInt)(struct AdbcStatement*, const char*, int64_t,
                                           struct AdbcError*);
 
+  // ADBC 1.2
+  AdbcStatusCode (*StatementRequestSchema)(struct AdbcStatement*, struct ArrowSchema*,
+                                           struct AdbcError*);
+
   /// @}
 
   /// \defgroup adbc-1.2.0 ADBC API Revision 1.2.0
@@ -2293,6 +2297,36 @@ AdbcStatusCode AdbcStatementExecuteSchema(struct AdbcStatement* statement,
                                           struct ArrowSchema* schema,
                                           struct AdbcError* error);
 
+/// \brief Request the schema of the next statement execution
+///
+/// Allows the caller to request a specific schema based on prior
+/// information or user input. This may be used to ensure a
+/// consistent schema when executing queries against a database
+/// with row-based types (e.g., SQLite) or a database whose types
+/// are implemented with row-based parameters where Arrow prefers
+/// type-level parameters (e.g., NUMERIC for PostgreSQL).
+///
+/// The provided schema is a request and not a guarantee (i.e.,
+/// callers must use the schema provided by the output stream to
+/// interpret the result).
+///
+/// Calling AdbcStatementRequestSchema() must not affect the result
+/// of AdbcStatementExecuteSchema (which always infers its result
+/// from the input query).
+///
+/// \since ADBC API revision 1.2.0
+///
+/// \param[in] statement The statement to execute.
+/// \param[in] schema The requested 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 AdbcStatementRequestSchema(struct AdbcStatement* statement,
+                                          struct ArrowSchema* schema,
+                                          struct AdbcError* error);
+
 /// \brief Turn this statement into a prepared statement to be
 ///   executed multiple times.
 ///