This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch spec-1.2.0
in repository https://gitbox.apache.org/repos/asf/arrow-adbc.git
The following commit(s) were added to refs/heads/spec-1.2.0 by this push:
new 120a65c0b feat(c/include/arrow-adbc): Add AdbcStatementRequestSchema
(#3623)
120a65c0b is described below
commit 120a65c0bcf58109b879b269f58788a73d8d116a
Author: Dewey Dunnington <[email protected]>
AuthorDate: Wed Jul 22 01:31:03 2026 -0400
feat(c/include/arrow-adbc): Add AdbcStatementRequestSchema (#3623)
This PR proposes a 1.2 spec addition `AdbcStatementRequestSchema()`.
There are a few decisions here and while I put specific language in I
think any version of these is still helpful:
- I wrote this up as this best-effort (like the PyCapsule
`requested_schema`). I think this is better for negotiation (e.g., the
caller calls execute schema, requests a schema with all
strings/binary/list columns as views, and the driver produces
string/binary views but not list views because it doesn't implement
those). A strict version is also useful and might generate better
errors.
- Maybe `struct ArrowSchema*` should be `const ArrowSchema*`. I'm not
sure this matters (mostly the C struct will be populated specifically
for this call and they are easy to copy).
- No opinions on `RequestSchema` as the name if there's a better one
The capability to do this is built in to the Postgres driver already for
some types (the COPY reader was designed to always accept an arbitrary
ArrowSchema, which we currently just infer before constructing the
reader).
Other 1.2 spec additions in
https://github.com/apache/arrow-adbc/pull/3607 (which also contains the
infrastructure for a new ADBC minor version).
Closes #1514 .
---------
Co-authored-by: David Li <[email protected]>
---
c/driver_manager/adbc_driver_manager.cc | 21 ++++++++++++++++++
c/include/arrow-adbc/adbc.h | 37 ++++++++++++++++++++++++++++++++
go/adbc/drivermgr/adbc_driver_manager.cc | 21 ++++++++++++++++++
go/adbc/drivermgr/arrow-adbc/adbc.h | 37 ++++++++++++++++++++++++++++++++
4 files changed, 116 insertions(+)
diff --git a/c/driver_manager/adbc_driver_manager.cc
b/c/driver_manager/adbc_driver_manager.cc
index 15d98c00b..7cf2c424b 100644
--- a/c/driver_manager/adbc_driver_manager.cc
+++ b/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: \
@@ -3382,6 +3399,10 @@ AdbcStatusCode
AdbcLoadDriverFromInitFunc(AdbcDriverInitFunc init_func, int vers
FILL_DEFAULT(driver, StatementSetOptionDouble);
FILL_DEFAULT(driver, StatementSetOptionInt);
}
+ if (version >= ADBC_VERSION_1_2_0) {
+ auto* driver = reinterpret_cast<struct AdbcDriver*>(raw_driver);
+ FILL_DEFAULT(driver, StatementRequestSchema);
+ }
return ADBC_STATUS_OK;
diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h
index a461795ce..b3e856f0d 100644
--- a/c/include/arrow-adbc/adbc.h
+++ b/c/include/arrow-adbc/adbc.h
@@ -1516,6 +1516,9 @@ struct ADBC_EXPORT AdbcDriver {
AdbcStatusCode (*StatementExecuteMulti)(struct AdbcStatement*,
struct AdbcMultiResultSet*, struct
AdbcError*);
+ AdbcStatusCode (*StatementRequestSchema)(struct AdbcStatement*, struct
ArrowSchema*,
+ struct AdbcError*);
+
/// @}
};
@@ -2557,6 +2560,40 @@ 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
+/// schema request is intended to modify only the types or
+/// widen the nullability of types in the original schema;
+/// column reordering or changing the number of returned columns
+/// is not a goal of this feature.
+///
+/// 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.
///
diff --git a/go/adbc/drivermgr/adbc_driver_manager.cc
b/go/adbc/drivermgr/adbc_driver_manager.cc
index 15d98c00b..7cf2c424b 100644
--- a/go/adbc/drivermgr/adbc_driver_manager.cc
+++ b/go/adbc/drivermgr/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: \
@@ -3382,6 +3399,10 @@ AdbcStatusCode
AdbcLoadDriverFromInitFunc(AdbcDriverInitFunc init_func, int vers
FILL_DEFAULT(driver, StatementSetOptionDouble);
FILL_DEFAULT(driver, StatementSetOptionInt);
}
+ if (version >= ADBC_VERSION_1_2_0) {
+ auto* driver = reinterpret_cast<struct AdbcDriver*>(raw_driver);
+ FILL_DEFAULT(driver, StatementRequestSchema);
+ }
return ADBC_STATUS_OK;
diff --git a/go/adbc/drivermgr/arrow-adbc/adbc.h
b/go/adbc/drivermgr/arrow-adbc/adbc.h
index a461795ce..b3e856f0d 100644
--- a/go/adbc/drivermgr/arrow-adbc/adbc.h
+++ b/go/adbc/drivermgr/arrow-adbc/adbc.h
@@ -1516,6 +1516,9 @@ struct ADBC_EXPORT AdbcDriver {
AdbcStatusCode (*StatementExecuteMulti)(struct AdbcStatement*,
struct AdbcMultiResultSet*, struct
AdbcError*);
+ AdbcStatusCode (*StatementRequestSchema)(struct AdbcStatement*, struct
ArrowSchema*,
+ struct AdbcError*);
+
/// @}
};
@@ -2557,6 +2560,40 @@ 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
+/// schema request is intended to modify only the types or
+/// widen the nullability of types in the original schema;
+/// column reordering or changing the number of returned columns
+/// is not a goal of this feature.
+///
+/// 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.
///
