You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by "zeroshade (via GitHub)" <gi...@apache.org> on 2026/01/08 18:04:13 UTC
[PR] feat: Spec multi-result-set API [arrow-adbc]
zeroshade opened a new pull request, #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871
Extracted from #3607 with influence by the comments there and https://github.com/apache/arrow-adbc/compare/main...CurtHagenlocher:arrow-adbc:MoreResults, this contains a proposal for handling multi-result set query execution via ADBC by adding a new function for drivers, `AdbcStatementNextResultSet`.
This also includes the necessary changes for an ADBC API Revision 1.2.0 (macro defines and so on). The comment above the function includes all the semantic definitions of the behavior.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "CurtHagenlocher (via GitHub)" <gi...@apache.org>.
CurtHagenlocher commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2710612535
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
> And/or, some flag or otherwise a way to indicate that you only want the schema, so the returned ArrowArrayStreams will only have get_schema and won't return any data.
FWIW, that's the approach that ADO.NET takes. You pass a flag when executing a command to say "schema only" and then the results you get back look just like normal query results except that they have no rows.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#issuecomment-3726663154
Should we make a branch for spec changes?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "felipecrv (via GitHub)" <gi...@apache.org>.
felipecrv commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2715259444
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
Review Comment:
Oh. I see. The term "result set" is really overloaded. So what you're trying to say is that Arrow stream consumed so far must stay active/available, but the database can stop producing Arrow streams that would be made available here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2715053976
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
Review Comment:
I think this is more referring to the case where result sets are returned while other result sets are still being executed. Not to the ArrowArrayStreams themselves
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2789154699
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
Added `ExecuteSchemaMulti`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2715346264
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcResultSetRelease(struct AdbcResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next result set from a multi-result-set execution.
Review Comment:
Or even better specifically say `AdbcMultiResultSet` and `ArrowArrayStream`?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2686801782
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2070,57 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \brief Retrieve the next result set from a multi-result-set execution.
+///
+/// This AdbcStatement must outlive the returned ArrowArrayStream.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// For an execution that returns multiple result sets, this can be called after
+/// iterating the first result set to get the next and subsequent result sets. A
+/// driver MAY support calling AdbcStatementNextResultSet while the previous result is
+/// still being consumed (i.e. before the previous ArrowArrayStream is released),
+/// but this is not required. If the driver does not support this, it should return
+/// ADBC_STATUS_INVALID_STATE if the previous result set is still active. Otherwise
+/// a driver should return ADBC_STATUS_OK to indicate successful execution of this
+/// function regardless of whether or not an additional result set is available.
+///
+/// If the original execution was via AdbcStatementExecuteSchema, then the
+/// ArrowArrayStream populated by this function should only contain the schema of the
+/// result set and not any data.
+///
+/// Either partitions or out must be NULL to indicate which style of output is desired
+/// by the caller. Supplying non-NULL values to both must result in
+/// ADBC_STATUS_INVALID_ARGUMENT. If the original execution was via
+/// AdbcStatementExecuteQuery and the call to AdbcStatementNextResultSet has a non-NULL
+/// partitions, or the original was via AdbcStatementExecutePartitions and this call has a
+/// non-NULL out, then the driver may choose to return the data in a different style than
+/// the original result set. If it does not (or cannot) then it should return
+/// ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The driver indicates that no additional result sets are available by setting the
+/// release callback on out (or partitions, whichever was not-NULL) to NULL and returning
+/// ADBC_STATUS_OK.
+///
+/// \param[in] statement The statement to fetch a subsequent result for
+/// \param[out] out The result stream to populate, or NULL if using partitions
+/// \param[out] partitions The partitions to populate, or NULL if using out
+/// \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_INVALID_STATE if called at an inappropriate time but the
+/// driver does support multi-result set execution, ADBC_STATUS_INVALID_ARGUMENT if both
+/// out and partitions are non-NULL, or if the output style is incompatible with the
+/// original execution, and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
+ struct ArrowArrayStream* out,
+ struct AdbcPartitions* partitions,
+ int64_t* rows_affected,
+ struct AdbcError* error);
Review Comment:
> Does that mean the user has to explicitly set it back to NULL? Or that the statement should have internally set it to NULL when it was executed? That's kind of annoying if you're trying to re-use the same Statement instance to execute the same query multiple times if you have to re-set the query to execute it again.
That was my initial thought as well and why I'm not a fan of this pattern.
> I suggested privately that there should be a new ExecuteMulti method that explicitly returns a multi-result-set stream. That encodes the user's expectation up-front that there will be multiple result sets from the query, and doesn't require Statement itself to become any more stateful than it is now.
This could be a way to create an `AdbcResultSet` type struct without a breaking change. Using `Execute` only provides a single result set and `ExecuteMulti` would return a struct that would have a `NextResultSet` callback, etc.
Thoughts everyone?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#issuecomment-3729435567
I've changed the base for this PR to point to the spec-1.2.0 branch.
Now we just need people to weigh in on the proposal :smile:
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "paleolimbot (via GitHub)" <gi...@apache.org>.
paleolimbot commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2677821244
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2070,57 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \brief Retrieve the next result set from a multi-result-set execution.
+///
+/// This AdbcStatement must outlive the returned ArrowArrayStream.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// For an execution that returns multiple result sets, this can be called after
+/// iterating the first result set to get the next and subsequent result sets. A
+/// driver MAY support calling AdbcStatementNextResultSet while the previous result is
+/// still being consumed (i.e. before the previous ArrowArrayStream is released),
+/// but this is not required. If the driver does not support this, it should return
+/// ADBC_STATUS_INVALID_STATE if the previous result set is still active. Otherwise
+/// a driver should return ADBC_STATUS_OK to indicate successful execution of this
+/// function regardless of whether or not an additional result set is available.
+///
+/// If the original execution was via AdbcStatementExecuteSchema, then the
+/// ArrowArrayStream populated by this function should only contain the schema of the
+/// result set and not any data.
+///
+/// Either partitions or out must be NULL to indicate which style of output is desired
+/// by the caller. Supplying non-NULL values to both must result in
+/// ADBC_STATUS_INVALID_ARGUMENT. If the original execution was via
+/// AdbcStatementExecuteQuery and the call to AdbcStatementNextResultSet has a non-NULL
+/// partitions, or the original was via AdbcStatementExecutePartitions and this call has a
+/// non-NULL out, then the driver may choose to return the data in a different style than
+/// the original result set. If it does not (or cannot) then it should return
+/// ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The driver indicates that no additional result sets are available by setting the
+/// release callback on out (or partitions, whichever was not-NULL) to NULL and returning
+/// ADBC_STATUS_OK.
+///
+/// \param[in] statement The statement to fetch a subsequent result for
+/// \param[out] out The result stream to populate, or NULL if using partitions
+/// \param[out] partitions The partitions to populate, or NULL if using out
+/// \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_INVALID_STATE if called at an inappropriate time but the
+/// driver does support multi-result set execution, ADBC_STATUS_INVALID_ARGUMENT if both
+/// out and partitions are non-NULL, or if the output style is incompatible with the
+/// original execution, and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
+ struct ArrowArrayStream* out,
+ struct AdbcPartitions* partitions,
+ int64_t* rows_affected,
+ struct AdbcError* error);
Review Comment:
Would it be possible to have this just be:
```c
ADBC_EXPORT
AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
struct AdbcError* error);
```
...and then subsequent calls to `AdbcStatementExecute()`, `AdbcStatementExecuteSchema()`, `AdbcStatementExecutePartitions()`, and future async versions of all of those don't have to be redefined?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "paleolimbot (via GitHub)" <gi...@apache.org>.
paleolimbot commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2734735682
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
An option seems inconsistent with the existing `AdbcStatementExecuteSchema()`/`AdbcStatementExecute()` and may be confusing? The idea behind the extra struct + extra callbacks was to avoid more state to track in the statement at the expense of needing more functions. (I'm not particularly against the option but it does seem like in this case that the dedicated function at least constraints the state tracking by the driver to the new API).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2796286660
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,110 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the MultiResultSetNext
+/// or MultiResultSetNextPartitions functions on the AdbcMultiResultSet struct to iterate
+/// through the result sets. The caller is responsible for calling the release function
+/// when finished with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcMultiResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcMultiResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcMultiResultSetRelease(struct AdbcMultiResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next ArrowArrayStream from an AdbcMultiResultSet.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The driver can decide whether to allow fetching the next result set
+/// as a single stream or as a set of partitions. If the driver does not
+/// support fetching the next result set as a stream (indicating it should
+/// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+///
+/// To indicate that no additional result sets are available, this should return
+/// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+/// pattern is that after calling `StatementExecuteMulti`, the caller would
+/// then call `MultiResultSetNext` repeatedly until it returns ADBC_STATUS_OK and
+/// sets the release callback to NULL, indicating that there are no more result sets.
Review Comment:
Should we leave it up to a driver to determine whether it's allowed? (i.e. "A driver MAY invalidate the current result set when MultiResultSetNext is called") or should we explicitly state that it *is* invalidated when calling MultiResultSetNext and thus *require* that behavior?
I personally lean towards the latter rather than the former for consistency, but it would prevent a driver from technically *allowing* it if it supports it. Thoughts?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2796269038
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2183,72 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief Retrieve schema for statement that potentially returns multiple result sets
+///
+/// \since ADBC API revision 1.2.0
+///
+/// This can be used to retrieve the schemas of all result sets without
+/// executing the statement. If the driver does not support this, it should return
+/// ADBC_STATUS_NOT_IMPLEMENTED.
+///
+/// The ArrowArrayStream objects populated by calls to `MultiResultSetNext` with the
+/// results struct returned by this function should have a valid schema but no data (i.e.
+/// `get_next` should return EOS immediately). This allows clients to inspect the schemas
+/// of all result sets before consuming any data, which can be useful for certain
+/// applications such as query planning or UI display of results.
+///
+/// \param[in] statement The statement to execute.
+/// \param[out] results The result set struct to populate with the schemas of the result
+/// sets.
+/// \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,
+/// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementExecuteMulti(struct AdbcStatement* statement,
Review Comment:
yes, oops.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "paleolimbot (via GitHub)" <gi...@apache.org>.
paleolimbot commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2775644495
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,111 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcMultiResultSet struct to iterate through
+/// the result sets. The caller is responsible for calling the release function when
+/// finished with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcMultiResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcMultiResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcResultSetRelease(struct AdbcMultiResultSet* result_set,
+ struct AdbcError* error);
Review Comment:
Should this be`AdbcMultiResultSetRelease` (same question for the other two functions)?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2678360000
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2070,57 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \brief Retrieve the next result set from a multi-result-set execution.
+///
+/// This AdbcStatement must outlive the returned ArrowArrayStream.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// For an execution that returns multiple result sets, this can be called after
+/// iterating the first result set to get the next and subsequent result sets. A
+/// driver MAY support calling AdbcStatementNextResultSet while the previous result is
+/// still being consumed (i.e. before the previous ArrowArrayStream is released),
+/// but this is not required. If the driver does not support this, it should return
+/// ADBC_STATUS_INVALID_STATE if the previous result set is still active. Otherwise
+/// a driver should return ADBC_STATUS_OK to indicate successful execution of this
+/// function regardless of whether or not an additional result set is available.
+///
+/// If the original execution was via AdbcStatementExecuteSchema, then the
+/// ArrowArrayStream populated by this function should only contain the schema of the
+/// result set and not any data.
+///
+/// Either partitions or out must be NULL to indicate which style of output is desired
+/// by the caller. Supplying non-NULL values to both must result in
+/// ADBC_STATUS_INVALID_ARGUMENT. If the original execution was via
+/// AdbcStatementExecuteQuery and the call to AdbcStatementNextResultSet has a non-NULL
+/// partitions, or the original was via AdbcStatementExecutePartitions and this call has a
+/// non-NULL out, then the driver may choose to return the data in a different style than
+/// the original result set. If it does not (or cannot) then it should return
+/// ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The driver indicates that no additional result sets are available by setting the
+/// release callback on out (or partitions, whichever was not-NULL) to NULL and returning
+/// ADBC_STATUS_OK.
+///
+/// \param[in] statement The statement to fetch a subsequent result for
+/// \param[out] out The result stream to populate, or NULL if using partitions
+/// \param[out] partitions The partitions to populate, or NULL if using out
+/// \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_INVALID_STATE if called at an inappropriate time but the
+/// driver does support multi-result set execution, ADBC_STATUS_INVALID_ARGUMENT if both
+/// out and partitions are non-NULL, or if the output style is incompatible with the
+/// original execution, and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
+ struct ArrowArrayStream* out,
+ struct AdbcPartitions* partitions,
+ int64_t* rows_affected,
+ struct AdbcError* error);
Review Comment:
(I think we need some way to differentiate, in that case, "I want to start a new query" vs "I want to continue executing the query". And ideally we remain backwards-compatible, so that calling ExecuteQuery again would start a new query as it currently does.)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2692557668
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2070,57 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \brief Retrieve the next result set from a multi-result-set execution.
+///
+/// This AdbcStatement must outlive the returned ArrowArrayStream.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// For an execution that returns multiple result sets, this can be called after
+/// iterating the first result set to get the next and subsequent result sets. A
+/// driver MAY support calling AdbcStatementNextResultSet while the previous result is
+/// still being consumed (i.e. before the previous ArrowArrayStream is released),
+/// but this is not required. If the driver does not support this, it should return
+/// ADBC_STATUS_INVALID_STATE if the previous result set is still active. Otherwise
+/// a driver should return ADBC_STATUS_OK to indicate successful execution of this
+/// function regardless of whether or not an additional result set is available.
+///
+/// If the original execution was via AdbcStatementExecuteSchema, then the
+/// ArrowArrayStream populated by this function should only contain the schema of the
+/// result set and not any data.
+///
+/// Either partitions or out must be NULL to indicate which style of output is desired
+/// by the caller. Supplying non-NULL values to both must result in
+/// ADBC_STATUS_INVALID_ARGUMENT. If the original execution was via
+/// AdbcStatementExecuteQuery and the call to AdbcStatementNextResultSet has a non-NULL
+/// partitions, or the original was via AdbcStatementExecutePartitions and this call has a
+/// non-NULL out, then the driver may choose to return the data in a different style than
+/// the original result set. If it does not (or cannot) then it should return
+/// ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The driver indicates that no additional result sets are available by setting the
+/// release callback on out (or partitions, whichever was not-NULL) to NULL and returning
+/// ADBC_STATUS_OK.
+///
+/// \param[in] statement The statement to fetch a subsequent result for
+/// \param[out] out The result stream to populate, or NULL if using partitions
+/// \param[out] partitions The partitions to populate, or NULL if using out
+/// \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_INVALID_STATE if called at an inappropriate time but the
+/// driver does support multi-result set execution, ADBC_STATUS_INVALID_ARGUMENT if both
+/// out and partitions are non-NULL, or if the output style is incompatible with the
+/// original execution, and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
+ struct ArrowArrayStream* out,
+ struct AdbcPartitions* partitions,
+ int64_t* rows_affected,
+ struct AdbcError* error);
Review Comment:
That sounds ok to me.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "paleolimbot (via GitHub)" <gi...@apache.org>.
paleolimbot commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2709104465
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
I'm not sure if it would be used for anything, but DataFusion could in theory do this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2709229790
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
I don't think it's necessarily worthwhile to have a NextSchema free function. `NextResultSet` returns an `ArrowArrayStream` which has `get_schema`, and the `NextResultSetPartitions` function can output the schema explicitly.
My concern is what precisely happens if they call `NextSchema` again without calling `NextResultSet` first. Does it move on and pull the schema of the next one? Does it return the same schema again until `NextResultSet` is called? I believe that depending on the user either one could be valid or desired, making it difficult to pick one.
In both cases, it's trivially easy to get the schema before you start consuming the data (either via `get_schema` on the `ArrowArrayStream` or by the schema returned by `NextResultPartitions`.
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
Review Comment:
docs updated to say this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#issuecomment-3773939849
Updated based on the most recent comments, converted the callback members of `AdbcResultSet` to instead be free functions (along with the corresponding callback members in the `AdbcDriver` struct.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "CurtHagenlocher (via GitHub)" <gi...@apache.org>.
CurtHagenlocher commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2706306680
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2070,57 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \brief Retrieve the next result set from a multi-result-set execution.
+///
+/// This AdbcStatement must outlive the returned ArrowArrayStream.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// For an execution that returns multiple result sets, this can be called after
+/// iterating the first result set to get the next and subsequent result sets. A
+/// driver MAY support calling AdbcStatementNextResultSet while the previous result is
+/// still being consumed (i.e. before the previous ArrowArrayStream is released),
+/// but this is not required. If the driver does not support this, it should return
+/// ADBC_STATUS_INVALID_STATE if the previous result set is still active. Otherwise
+/// a driver should return ADBC_STATUS_OK to indicate successful execution of this
+/// function regardless of whether or not an additional result set is available.
+///
+/// If the original execution was via AdbcStatementExecuteSchema, then the
+/// ArrowArrayStream populated by this function should only contain the schema of the
+/// result set and not any data.
+///
+/// Either partitions or out must be NULL to indicate which style of output is desired
+/// by the caller. Supplying non-NULL values to both must result in
+/// ADBC_STATUS_INVALID_ARGUMENT. If the original execution was via
+/// AdbcStatementExecuteQuery and the call to AdbcStatementNextResultSet has a non-NULL
+/// partitions, or the original was via AdbcStatementExecutePartitions and this call has a
+/// non-NULL out, then the driver may choose to return the data in a different style than
+/// the original result set. If it does not (or cannot) then it should return
+/// ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The driver indicates that no additional result sets are available by setting the
+/// release callback on out (or partitions, whichever was not-NULL) to NULL and returning
+/// ADBC_STATUS_OK.
+///
+/// \param[in] statement The statement to fetch a subsequent result for
+/// \param[out] out The result stream to populate, or NULL if using partitions
+/// \param[out] partitions The partitions to populate, or NULL if using out
+/// \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_INVALID_STATE if called at an inappropriate time but the
+/// driver does support multi-result set execution, ADBC_STATUS_INVALID_ARGUMENT if both
+/// out and partitions are non-NULL, or if the output style is incompatible with the
+/// original execution, and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
+ struct ArrowArrayStream* out,
+ struct AdbcPartitions* partitions,
+ int64_t* rows_affected,
+ struct AdbcError* error);
Review Comment:
The ODBC, JDBC and ADO.NET APIs all work in this fashion. One thing to consider for databases which support stored procedures is that it may not be possible to know in advance how many result sets they will return. I know this is true for MSSQL and think it might be true for PostgreSQL as well.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2715057807
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcResultSetRelease(struct AdbcResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next result set from a multi-result-set execution.
Review Comment:
Yes
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "felipecrv (via GitHub)" <gi...@apache.org>.
felipecrv commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2795831077
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
That's a good call. Creates more structure for people implementing drivers.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2796274105
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,110 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the MultiResultSetNext
+/// or MultiResultSetNextPartitions functions on the AdbcMultiResultSet struct to iterate
+/// through the result sets. The caller is responsible for calling the release function
+/// when finished with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcMultiResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcMultiResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcMultiResultSetRelease(struct AdbcMultiResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next ArrowArrayStream from an AdbcMultiResultSet.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The driver can decide whether to allow fetching the next result set
+/// as a single stream or as a set of partitions. If the driver does not
+/// support fetching the next result set as a stream (indicating it should
+/// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+///
+/// To indicate that no additional result sets are available, this should return
+/// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+/// pattern is that after calling `StatementExecuteMulti`, the caller would
+/// then call `MultiResultSetNext` repeatedly until it returns ADBC_STATUS_OK and
+/// sets the release callback to NULL, indicating that there are no more result sets.
+/// It is not an error to repeatedly call `MultiResultSetNext` after the last result set
+/// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+/// NULL release callback.
+///
+/// \param[in] result_set The result set struct to fetch the next result from.
+/// \param[out] out The result stream to populate
+/// \param[out] rows_affected The number of rows affected if known, else -
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+/// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
Review Comment:
artifact of the previous design. it no longer applies here give that we've decoupled everything by having these standalone functions on the separate MultiResultSet object
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2715062423
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcResultSetRelease(struct AdbcResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next result set from a multi-result-set execution.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The AdbcResultSet must outlive the returned ArrowArrayStream.
Review Comment:
Providing this guarantee allows for shared state to live in the AdbcResultSet object and safely get cleaned up during a call to `release` without having to worry about whether or not there are still outstanding ArrowArrayStreams that refer to it.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "davidhcoe (via GitHub)" <gi...@apache.org>.
davidhcoe commented on PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#issuecomment-3775530586
@jadewang-db and @eric-wang-1990 are interested in this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2710591006
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
Maybe we can also have an ExecuteSchemaMulti? And/or, some flag or otherwise a way to indicate that you only want the schema, so the returned ArrowArrayStreams will only have get_schema and won't return any data.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2710436045
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
Review Comment:
Yes, thanks!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2706978425
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
Although, it'd probably be better to indicate the desire for that up front so that the driver can choose what to do properly. (And actually, I'm not sure if database clients generally support this in the first place...)
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
Review Comment:
Maybe we should also have a pointer to the AdbcDriver as with the other structs?
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
Review Comment:
I think I'd vaguely prefer these as free functions to make it so that there's only one struct that needs possible extension later.
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
Did we also want a NextSchema callback?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "abonander (via GitHub)" <gi...@apache.org>.
abonander commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2683112181
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2070,57 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \brief Retrieve the next result set from a multi-result-set execution.
+///
+/// This AdbcStatement must outlive the returned ArrowArrayStream.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// For an execution that returns multiple result sets, this can be called after
+/// iterating the first result set to get the next and subsequent result sets. A
+/// driver MAY support calling AdbcStatementNextResultSet while the previous result is
+/// still being consumed (i.e. before the previous ArrowArrayStream is released),
+/// but this is not required. If the driver does not support this, it should return
+/// ADBC_STATUS_INVALID_STATE if the previous result set is still active. Otherwise
+/// a driver should return ADBC_STATUS_OK to indicate successful execution of this
+/// function regardless of whether or not an additional result set is available.
+///
+/// If the original execution was via AdbcStatementExecuteSchema, then the
+/// ArrowArrayStream populated by this function should only contain the schema of the
+/// result set and not any data.
+///
+/// Either partitions or out must be NULL to indicate which style of output is desired
+/// by the caller. Supplying non-NULL values to both must result in
+/// ADBC_STATUS_INVALID_ARGUMENT. If the original execution was via
+/// AdbcStatementExecuteQuery and the call to AdbcStatementNextResultSet has a non-NULL
+/// partitions, or the original was via AdbcStatementExecutePartitions and this call has a
+/// non-NULL out, then the driver may choose to return the data in a different style than
+/// the original result set. If it does not (or cannot) then it should return
+/// ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The driver indicates that no additional result sets are available by setting the
+/// release callback on out (or partitions, whichever was not-NULL) to NULL and returning
+/// ADBC_STATUS_OK.
+///
+/// \param[in] statement The statement to fetch a subsequent result for
+/// \param[out] out The result stream to populate, or NULL if using partitions
+/// \param[out] partitions The partitions to populate, or NULL if using out
+/// \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_INVALID_STATE if called at an inappropriate time but the
+/// driver does support multi-result set execution, ADBC_STATUS_INVALID_ARGUMENT if both
+/// out and partitions are non-NULL, or if the output style is incompatible with the
+/// original execution, and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
+ struct ArrowArrayStream* out,
+ struct AdbcPartitions* partitions,
+ int64_t* rows_affected,
+ struct AdbcError* error);
Review Comment:
> Maybe we can specify that the query must be `NULL` in those cases?
Does that mean the user has to explicitly set it back to `NULL`? Or that the statement should have internally set it to `NULL` when it was executed? That's kind of annoying if you're trying to re-use the same `Statement` instance to execute the same query multiple times if you have to re-set the query to execute it again. Some users might expect that they need to hold on to the `Statement` to execute it without paying the cost of preparing it again. They might even try to cache `Statement`s that they've already prepared alongside the parent connection.
---
Including the partitions API makes this method weirdly modal, I would say if you wanted to lean into the partitions API then you should commit to it and just return a partition from here. Or just split it into two separate methods.
But it's already hard to understand from the API design how you're supposed to use partitions, much less how you're supposed to implement them in the driver. Having to go _back_ to the connection to read the partition doesn't make a ton of sense to me, unless it's a separate query or protocol command to read from it, like fetching from a named cursor.
---
I suggested privately that there should be a new `ExecuteMulti` method that explicitly returns a multi-result-set stream. That encodes the user's expectation up-front that there will be multiple result sets from the query, and doesn't require `Statement` itself to become any more stateful than it is now.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2709213639
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
Review Comment:
Is https://github.com/apache/arrow-adbc/pull/3871/commits/d88fccbd9848c53e5586460da94282cdf494afe9 what you were thinking? Free functions for `AdbcNextResultSet`, `AdbcNextResultSetPartitions`, and `AdbcResultSetRelease` and the struct being only the `private_data` and `private_driver` members?
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
Review Comment:
added
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2678910987
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2070,57 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \brief Retrieve the next result set from a multi-result-set execution.
+///
+/// This AdbcStatement must outlive the returned ArrowArrayStream.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// For an execution that returns multiple result sets, this can be called after
+/// iterating the first result set to get the next and subsequent result sets. A
+/// driver MAY support calling AdbcStatementNextResultSet while the previous result is
+/// still being consumed (i.e. before the previous ArrowArrayStream is released),
+/// but this is not required. If the driver does not support this, it should return
+/// ADBC_STATUS_INVALID_STATE if the previous result set is still active. Otherwise
+/// a driver should return ADBC_STATUS_OK to indicate successful execution of this
+/// function regardless of whether or not an additional result set is available.
+///
+/// If the original execution was via AdbcStatementExecuteSchema, then the
+/// ArrowArrayStream populated by this function should only contain the schema of the
+/// result set and not any data.
+///
+/// Either partitions or out must be NULL to indicate which style of output is desired
+/// by the caller. Supplying non-NULL values to both must result in
+/// ADBC_STATUS_INVALID_ARGUMENT. If the original execution was via
+/// AdbcStatementExecuteQuery and the call to AdbcStatementNextResultSet has a non-NULL
+/// partitions, or the original was via AdbcStatementExecutePartitions and this call has a
+/// non-NULL out, then the driver may choose to return the data in a different style than
+/// the original result set. If it does not (or cannot) then it should return
+/// ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The driver indicates that no additional result sets are available by setting the
+/// release callback on out (or partitions, whichever was not-NULL) to NULL and returning
+/// ADBC_STATUS_OK.
+///
+/// \param[in] statement The statement to fetch a subsequent result for
+/// \param[out] out The result stream to populate, or NULL if using partitions
+/// \param[out] partitions The partitions to populate, or NULL if using out
+/// \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_INVALID_STATE if called at an inappropriate time but the
+/// driver does support multi-result set execution, ADBC_STATUS_INVALID_ARGUMENT if both
+/// out and partitions are non-NULL, or if the output style is incompatible with the
+/// original execution, and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
+ struct ArrowArrayStream* out,
+ struct AdbcPartitions* partitions,
+ int64_t* rows_affected,
+ struct AdbcError* error);
Review Comment:
I tried to essentially handle all of the cases with the one function here (minus async) by specifying particular inputs as null or not. I'm don't particularly like having to figure out how to differentiate between the `Execute*` methods starting a new execution vs continuing after a call to `NextResultSet`, though that might just be bias from existing APIs I've used.
My thoughts were that the `Execute*` methods return a stream/schema/list of partitions, so calling `NextResultSet` should also do the same.
The other pattern I've seen would be that we'd create an `AdbcResult` struct which would have a NextResultSet callback on it (which IMO we should have done in the first place), but this would be a breaking change or at least require an entirely new set of functions.
@CurtHagenlocher @davidhcoe do either of you have any opinions on this?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#issuecomment-3726818006
I made https://github.com/apache/arrow-adbc/tree/spec-1.2.0
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#issuecomment-3726675034
> Should we make a branch for spec changes?
That makes sense, gather the spec updates in the branch and then eventually decide to push it as one thing.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade merged PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2780195743
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,111 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcMultiResultSet struct to iterate through
+/// the result sets. The caller is responsible for calling the release function when
+/// finished with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcMultiResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcMultiResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcResultSetRelease(struct AdbcMultiResultSet* result_set,
+ struct AdbcError* error);
Review Comment:
And `MultiResultSetNext`, etc, agreed
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1135,6 +1261,40 @@ 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.
+ ///
+ /// When a driver implementing an older spec is loaded by a newer
+ /// driver manager, the newer manager will allocate the new, expanded
+ /// AdbcDriver struct and attempt to have the driver initialize it with
+ /// the newer version. This must return an error, after which the driver
+ /// will try again with successively older versions all the way back to
+ /// ADBC_VERSION_1_0_0. The driver must not access the new fields,
+ /// which will carry undefined values.
Review Comment:
Probably we should describe the user perspective and driver perspective separately.
From the user perspective: the manager will return a fully populated struct, but some of the functions may fail with NOT_IMPLEMENTED.
From the driver perspective: they should not access members outside of the version specified by the driver manager. (Though this is already required by the contract on the init func, and also you have no other way of knowing the size of the struct, nor do you know whether it's the driver manager or something else calling you.) I don't think we need to specify what exactly the driver manager does here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "davidhcoe (via GitHub)" <gi...@apache.org>.
davidhcoe commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2694754635
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2070,57 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \brief Retrieve the next result set from a multi-result-set execution.
+///
+/// This AdbcStatement must outlive the returned ArrowArrayStream.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// For an execution that returns multiple result sets, this can be called after
+/// iterating the first result set to get the next and subsequent result sets. A
+/// driver MAY support calling AdbcStatementNextResultSet while the previous result is
+/// still being consumed (i.e. before the previous ArrowArrayStream is released),
+/// but this is not required. If the driver does not support this, it should return
+/// ADBC_STATUS_INVALID_STATE if the previous result set is still active. Otherwise
+/// a driver should return ADBC_STATUS_OK to indicate successful execution of this
+/// function regardless of whether or not an additional result set is available.
+///
+/// If the original execution was via AdbcStatementExecuteSchema, then the
+/// ArrowArrayStream populated by this function should only contain the schema of the
+/// result set and not any data.
+///
+/// Either partitions or out must be NULL to indicate which style of output is desired
+/// by the caller. Supplying non-NULL values to both must result in
+/// ADBC_STATUS_INVALID_ARGUMENT. If the original execution was via
+/// AdbcStatementExecuteQuery and the call to AdbcStatementNextResultSet has a non-NULL
+/// partitions, or the original was via AdbcStatementExecutePartitions and this call has a
+/// non-NULL out, then the driver may choose to return the data in a different style than
+/// the original result set. If it does not (or cannot) then it should return
+/// ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The driver indicates that no additional result sets are available by setting the
+/// release callback on out (or partitions, whichever was not-NULL) to NULL and returning
+/// ADBC_STATUS_OK.
+///
+/// \param[in] statement The statement to fetch a subsequent result for
+/// \param[out] out The result stream to populate, or NULL if using partitions
+/// \param[out] partitions The partitions to populate, or NULL if using out
+/// \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_INVALID_STATE if called at an inappropriate time but the
+/// driver does support multi-result set execution, ADBC_STATUS_INVALID_ARGUMENT if both
+/// out and partitions are non-NULL, or if the output style is incompatible with the
+/// original execution, and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
+ struct ArrowArrayStream* out,
+ struct AdbcPartitions* partitions,
+ int64_t* rows_affected,
+ struct AdbcError* error);
Review Comment:
I guess what I struggle with is how do you know when additional results are expected? Is there something that would split the SQL statements to know there are multiple? Do you always call AdbcStatementNextResultSet just to check if there is a second one?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "paleolimbot (via GitHub)" <gi...@apache.org>.
paleolimbot commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2692984624
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2070,57 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \brief Retrieve the next result set from a multi-result-set execution.
+///
+/// This AdbcStatement must outlive the returned ArrowArrayStream.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// For an execution that returns multiple result sets, this can be called after
+/// iterating the first result set to get the next and subsequent result sets. A
+/// driver MAY support calling AdbcStatementNextResultSet while the previous result is
+/// still being consumed (i.e. before the previous ArrowArrayStream is released),
+/// but this is not required. If the driver does not support this, it should return
+/// ADBC_STATUS_INVALID_STATE if the previous result set is still active. Otherwise
+/// a driver should return ADBC_STATUS_OK to indicate successful execution of this
+/// function regardless of whether or not an additional result set is available.
+///
+/// If the original execution was via AdbcStatementExecuteSchema, then the
+/// ArrowArrayStream populated by this function should only contain the schema of the
+/// result set and not any data.
+///
+/// Either partitions or out must be NULL to indicate which style of output is desired
+/// by the caller. Supplying non-NULL values to both must result in
+/// ADBC_STATUS_INVALID_ARGUMENT. If the original execution was via
+/// AdbcStatementExecuteQuery and the call to AdbcStatementNextResultSet has a non-NULL
+/// partitions, or the original was via AdbcStatementExecutePartitions and this call has a
+/// non-NULL out, then the driver may choose to return the data in a different style than
+/// the original result set. If it does not (or cannot) then it should return
+/// ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The driver indicates that no additional result sets are available by setting the
+/// release callback on out (or partitions, whichever was not-NULL) to NULL and returning
+/// ADBC_STATUS_OK.
+///
+/// \param[in] statement The statement to fetch a subsequent result for
+/// \param[out] out The result stream to populate, or NULL if using partitions
+/// \param[out] partitions The partitions to populate, or NULL if using out
+/// \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_INVALID_STATE if called at an inappropriate time but the
+/// driver does support multi-result set execution, ADBC_STATUS_INVALID_ARGUMENT if both
+/// out and partitions are non-NULL, or if the output style is incompatible with the
+/// original execution, and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
+ struct ArrowArrayStream* out,
+ struct AdbcPartitions* partitions,
+ int64_t* rows_affected,
+ struct AdbcError* error);
Review Comment:
It's a great point that there's already a lot of state to keep track of in a statement, although that bookeeping still has to happen somewhere (both for the driver, ensuring it doesn't call something that will crash, and the caller, ensuring it doesn't violate any constraint about holding multiple results). Possibly there is just no getting around a lot of new C functions (whether they're on some new `AdbcResultSet` or the existing `AdbcStatement`).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "felipecrv (via GitHub)" <gi...@apache.org>.
felipecrv commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2715057442
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
> > And/or, some flag or otherwise a way to indicate that you only want the schema, so the returned ArrowArrayStreams will only have get_schema and won't return any data.
>
> FWIW, that's the approach that ADO.NET takes. You pass a flag when executing a command to say "schema only" and then the results you get back look just like normal query results except that they have no rows.
This is doable with `Statement::set_option()` and proceeding normally as long as the driver and the database collaborate on making sure no result computation takes place and only the schema is returned.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2729035825
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1135,6 +1261,40 @@ 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.
+ ///
+ /// When a driver implementing an older spec is loaded by a newer
+ /// driver manager, the newer manager will allocate the new, expanded
+ /// AdbcDriver struct and attempt to have the driver initialize it with
+ /// the newer version. This must return an error, after which the driver
+ /// will try again with successively older versions all the way back to
+ /// ADBC_VERSION_1_0_0. The driver must not access the new fields,
+ /// which will carry undefined values.
Review Comment:
I believe this is in line with the current behavior. No attempt is made to pre-populate with functions that fail immediately (likely to avoid having to create separate versions for *every* callback going forward). We currently leave these members undefined in the struct. If we want to change this behavior, I'd prefer we do it in a different PR, not this one.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#issuecomment-3879357732
@lidavidm @paleolimbot I've updated based on the feedback including adding an `ExecuteSchemaMulti` function. Any other comments on this?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2796270797
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,110 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the MultiResultSetNext
+/// or MultiResultSetNextPartitions functions on the AdbcMultiResultSet struct to iterate
+/// through the result sets. The caller is responsible for calling the release function
+/// when finished with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcMultiResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcMultiResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcMultiResultSetRelease(struct AdbcMultiResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next ArrowArrayStream from an AdbcMultiResultSet.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The driver can decide whether to allow fetching the next result set
+/// as a single stream or as a set of partitions. If the driver does not
+/// support fetching the next result set as a stream (indicating it should
+/// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+///
+/// To indicate that no additional result sets are available, this should return
+/// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+/// pattern is that after calling `StatementExecuteMulti`, the caller would
+/// then call `MultiResultSetNext` repeatedly until it returns ADBC_STATUS_OK and
+/// sets the release callback to NULL, indicating that there are no more result sets.
+/// It is not an error to repeatedly call `MultiResultSetNext` after the last result set
+/// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+/// NULL release callback.
+///
+/// \param[in] result_set The result set struct to fetch the next result from.
+/// \param[out] out The result stream to populate
+/// \param[out] rows_affected The number of rows affected if known, else -
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+/// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+/// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+AdbcStatusCode AdbcMultiResultSetNext(struct AdbcMultiResultSet* result_set,
+ struct ArrowArrayStream* out,
+ int64_t* rows_affected, struct AdbcError* error);
+
+/// \brief Get the next result set from a multi-result-set execution as partitions.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The AdbcMultiResultSet must outlive the returned partitions.
Review Comment:
fair enough
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2796296524
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1135,6 +1261,40 @@ 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.
+ ///
+ /// When a driver implementing an older spec is loaded by a newer
+ /// driver manager, the newer manager will allocate the new, expanded
+ /// AdbcDriver struct and attempt to have the driver initialize it with
+ /// the newer version. This must return an error, after which the driver
+ /// will try again with successively older versions all the way back to
+ /// ADBC_VERSION_1_0_0. The driver must not access the new fields,
+ /// which will carry undefined values.
Review Comment:
How's the updated version?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2678359646
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2070,57 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \brief Retrieve the next result set from a multi-result-set execution.
+///
+/// This AdbcStatement must outlive the returned ArrowArrayStream.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// For an execution that returns multiple result sets, this can be called after
+/// iterating the first result set to get the next and subsequent result sets. A
+/// driver MAY support calling AdbcStatementNextResultSet while the previous result is
+/// still being consumed (i.e. before the previous ArrowArrayStream is released),
+/// but this is not required. If the driver does not support this, it should return
+/// ADBC_STATUS_INVALID_STATE if the previous result set is still active. Otherwise
+/// a driver should return ADBC_STATUS_OK to indicate successful execution of this
+/// function regardless of whether or not an additional result set is available.
+///
+/// If the original execution was via AdbcStatementExecuteSchema, then the
+/// ArrowArrayStream populated by this function should only contain the schema of the
+/// result set and not any data.
+///
+/// Either partitions or out must be NULL to indicate which style of output is desired
+/// by the caller. Supplying non-NULL values to both must result in
+/// ADBC_STATUS_INVALID_ARGUMENT. If the original execution was via
+/// AdbcStatementExecuteQuery and the call to AdbcStatementNextResultSet has a non-NULL
+/// partitions, or the original was via AdbcStatementExecutePartitions and this call has a
+/// non-NULL out, then the driver may choose to return the data in a different style than
+/// the original result set. If it does not (or cannot) then it should return
+/// ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The driver indicates that no additional result sets are available by setting the
+/// release callback on out (or partitions, whichever was not-NULL) to NULL and returning
+/// ADBC_STATUS_OK.
+///
+/// \param[in] statement The statement to fetch a subsequent result for
+/// \param[out] out The result stream to populate, or NULL if using partitions
+/// \param[out] partitions The partitions to populate, or NULL if using out
+/// \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_INVALID_STATE if called at an inappropriate time but the
+/// driver does support multi-result set execution, ADBC_STATUS_INVALID_ARGUMENT if both
+/// out and partitions are non-NULL, or if the output style is incompatible with the
+/// original execution, and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
+ struct ArrowArrayStream* out,
+ struct AdbcPartitions* partitions,
+ int64_t* rows_affected,
+ struct AdbcError* error);
Review Comment:
That's a reasonable idea. Maybe we can specify that the `query` must be NULL in those cases? (Though, that would translate weirdly into many of the language bindings, albeit they also don't necessarily have to be 1:1.)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2796317505
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1059,17 +1178,18 @@ struct ADBC_EXPORT AdbcDriver {
/// 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.
+ /// When a driver implementing an older spec is loaded by a newer
+ /// driver manager, the newer manager will allocate the new, expanded
+ /// AdbcDriver struct and attempt to have the driver initialize it with
+ /// the newer version. This must return an error, after which the driver
+ /// will try again with successively older versions all the way back to
+ /// ADBC_VERSION_1_0_0. The driver must not access the new fields,
+ /// which will carry undefined values.
Review Comment:
The new wording looks good but it seems the old wording is up here (I guess the old wording is from the previous revision). Maybe we just remove it from one of these places? No need to duplicate
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2706981515
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
Review Comment:
We can say this also cancels the query if not completed?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2729041310
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
Was there a decision made here to prefer an option vs a separate function for pulling just the schema? I can update the docs and add a constant for the option if that's the route we want to go.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "felipecrv (via GitHub)" <gi...@apache.org>.
felipecrv commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2715026879
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
Review Comment:
Can't I keep N threads consuming different `RecordBatch` readers and release the thing that gave me the readers i.e. the `AdbcResultSet`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2715104594
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1135,6 +1261,40 @@ 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.
+ ///
+ /// When a driver implementing an older spec is loaded by a newer
+ /// driver manager, the newer manager will allocate the new, expanded
+ /// AdbcDriver struct and attempt to have the driver initialize it with
+ /// the newer version. This must return an error, after which the driver
+ /// will try again with successively older versions all the way back to
+ /// ADBC_VERSION_1_0_0. The driver must not access the new fields,
+ /// which will carry undefined values.
Review Comment:
I'm not actually sure what this is trying to say, now that you point it out.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2715102834
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcResultSetRelease(struct AdbcResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next result set from a multi-result-set execution.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The AdbcResultSet must outlive the returned ArrowArrayStream.
Review Comment:
I think as we've discussed for other APIs it may be better to require the driver to handle the bookkeeping.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "paleolimbot (via GitHub)" <gi...@apache.org>.
paleolimbot commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2695194868
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2070,57 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \brief Retrieve the next result set from a multi-result-set execution.
+///
+/// This AdbcStatement must outlive the returned ArrowArrayStream.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// For an execution that returns multiple result sets, this can be called after
+/// iterating the first result set to get the next and subsequent result sets. A
+/// driver MAY support calling AdbcStatementNextResultSet while the previous result is
+/// still being consumed (i.e. before the previous ArrowArrayStream is released),
+/// but this is not required. If the driver does not support this, it should return
+/// ADBC_STATUS_INVALID_STATE if the previous result set is still active. Otherwise
+/// a driver should return ADBC_STATUS_OK to indicate successful execution of this
+/// function regardless of whether or not an additional result set is available.
+///
+/// If the original execution was via AdbcStatementExecuteSchema, then the
+/// ArrowArrayStream populated by this function should only contain the schema of the
+/// result set and not any data.
+///
+/// Either partitions or out must be NULL to indicate which style of output is desired
+/// by the caller. Supplying non-NULL values to both must result in
+/// ADBC_STATUS_INVALID_ARGUMENT. If the original execution was via
+/// AdbcStatementExecuteQuery and the call to AdbcStatementNextResultSet has a non-NULL
+/// partitions, or the original was via AdbcStatementExecutePartitions and this call has a
+/// non-NULL out, then the driver may choose to return the data in a different style than
+/// the original result set. If it does not (or cannot) then it should return
+/// ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The driver indicates that no additional result sets are available by setting the
+/// release callback on out (or partitions, whichever was not-NULL) to NULL and returning
+/// ADBC_STATUS_OK.
+///
+/// \param[in] statement The statement to fetch a subsequent result for
+/// \param[out] out The result stream to populate, or NULL if using partitions
+/// \param[out] partitions The partitions to populate, or NULL if using out
+/// \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_INVALID_STATE if called at an inappropriate time but the
+/// driver does support multi-result set execution, ADBC_STATUS_INVALID_ARGUMENT if both
+/// out and partitions are non-NULL, or if the output style is incompatible with the
+/// original execution, and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
+ struct ArrowArrayStream* out,
+ struct AdbcPartitions* partitions,
+ int64_t* rows_affected,
+ struct AdbcError* error);
Review Comment:
I'm only familiar with the libpq way of doing this where you call `PQgetResult()` until it returns NULL (although some libraries probably expose a way to access the number of statements in something that is prepared).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#issuecomment-3770265609
I've updated the PR based on the comments and discussion. Everyone please take a look and let me know what you think!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2692560709
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2070,57 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \brief Retrieve the next result set from a multi-result-set execution.
+///
+/// This AdbcStatement must outlive the returned ArrowArrayStream.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// For an execution that returns multiple result sets, this can be called after
+/// iterating the first result set to get the next and subsequent result sets. A
+/// driver MAY support calling AdbcStatementNextResultSet while the previous result is
+/// still being consumed (i.e. before the previous ArrowArrayStream is released),
+/// but this is not required. If the driver does not support this, it should return
+/// ADBC_STATUS_INVALID_STATE if the previous result set is still active. Otherwise
+/// a driver should return ADBC_STATUS_OK to indicate successful execution of this
+/// function regardless of whether or not an additional result set is available.
+///
+/// If the original execution was via AdbcStatementExecuteSchema, then the
+/// ArrowArrayStream populated by this function should only contain the schema of the
+/// result set and not any data.
+///
+/// Either partitions or out must be NULL to indicate which style of output is desired
+/// by the caller. Supplying non-NULL values to both must result in
+/// ADBC_STATUS_INVALID_ARGUMENT. If the original execution was via
+/// AdbcStatementExecuteQuery and the call to AdbcStatementNextResultSet has a non-NULL
+/// partitions, or the original was via AdbcStatementExecutePartitions and this call has a
+/// non-NULL out, then the driver may choose to return the data in a different style than
+/// the original result set. If it does not (or cannot) then it should return
+/// ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The driver indicates that no additional result sets are available by setting the
+/// release callback on out (or partitions, whichever was not-NULL) to NULL and returning
+/// ADBC_STATUS_OK.
+///
+/// \param[in] statement The statement to fetch a subsequent result for
+/// \param[out] out The result stream to populate, or NULL if using partitions
+/// \param[out] partitions The partitions to populate, or NULL if using out
+/// \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_INVALID_STATE if called at an inappropriate time but the
+/// driver does support multi-result set execution, ADBC_STATUS_INVALID_ARGUMENT if both
+/// out and partitions are non-NULL, or if the output style is incompatible with the
+/// original execution, and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementNextResultSet(struct AdbcStatement* statement,
+ struct ArrowArrayStream* out,
+ struct AdbcPartitions* partitions,
+ int64_t* rows_affected,
+ struct AdbcError* error);
Review Comment:
@paleolimbot and @davidhcoe / @CurtHagenlocher?
If everyone's okay with this idea I'll take a stab at updating this proposal accordingly
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2729019860
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcResultSetRelease(struct AdbcResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next result set from a multi-result-set execution.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The AdbcResultSet must outlive the returned ArrowArrayStream.
Review Comment:
So we're removing this requirement for consumers?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#issuecomment-3725052805
After discussion and agreement on the proposed function, I'll update the relevant implementations here of the other driver managers to leverage and expose this (python, rust, Go, etc.)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2762490248
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
In that case `ExecuteSchemaMulti` may be best
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2791070786
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,110 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the MultiResultSetNext
+/// or MultiResultSetNextPartitions functions on the AdbcMultiResultSet struct to iterate
+/// through the result sets. The caller is responsible for calling the release function
+/// when finished with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcMultiResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcMultiResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcMultiResultSetRelease(struct AdbcMultiResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next ArrowArrayStream from an AdbcMultiResultSet.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The driver can decide whether to allow fetching the next result set
+/// as a single stream or as a set of partitions. If the driver does not
+/// support fetching the next result set as a stream (indicating it should
+/// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+///
+/// To indicate that no additional result sets are available, this should return
+/// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+/// pattern is that after calling `StatementExecuteMulti`, the caller would
+/// then call `MultiResultSetNext` repeatedly until it returns ADBC_STATUS_OK and
+/// sets the release callback to NULL, indicating that there are no more result sets.
Review Comment:
I think a state we haven't addressed is whether you can call Next while still reading the previous result set or not. I hazard many databases will not support concurrency, especially because the queries may depend on each other...
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -2013,6 +2183,72 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
int64_t* rows_affected, struct AdbcError* error);
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief Retrieve schema for statement that potentially returns multiple result sets
+///
+/// \since ADBC API revision 1.2.0
+///
+/// This can be used to retrieve the schemas of all result sets without
+/// executing the statement. If the driver does not support this, it should return
+/// ADBC_STATUS_NOT_IMPLEMENTED.
+///
+/// The ArrowArrayStream objects populated by calls to `MultiResultSetNext` with the
+/// results struct returned by this function should have a valid schema but no data (i.e.
+/// `get_next` should return EOS immediately). This allows clients to inspect the schemas
+/// of all result sets before consuming any data, which can be useful for certain
+/// applications such as query planning or UI display of results.
+///
+/// \param[in] statement The statement to execute.
+/// \param[out] results The result set struct to populate with the schemas of the result
+/// sets.
+/// \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,
+/// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ADBC_EXPORT
+AdbcStatusCode AdbcStatementExecuteMulti(struct AdbcStatement* statement,
Review Comment:
Presumably this was meant to be ExecuteSchemaMulti?
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,110 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the MultiResultSetNext
+/// or MultiResultSetNextPartitions functions on the AdbcMultiResultSet struct to iterate
+/// through the result sets. The caller is responsible for calling the release function
+/// when finished with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcMultiResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcMultiResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcMultiResultSetRelease(struct AdbcMultiResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next ArrowArrayStream from an AdbcMultiResultSet.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The driver can decide whether to allow fetching the next result set
+/// as a single stream or as a set of partitions. If the driver does not
+/// support fetching the next result set as a stream (indicating it should
+/// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+///
+/// To indicate that no additional result sets are available, this should return
+/// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+/// pattern is that after calling `StatementExecuteMulti`, the caller would
+/// then call `MultiResultSetNext` repeatedly until it returns ADBC_STATUS_OK and
+/// sets the release callback to NULL, indicating that there are no more result sets.
+/// It is not an error to repeatedly call `MultiResultSetNext` after the last result set
+/// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+/// NULL release callback.
+///
+/// \param[in] result_set The result set struct to fetch the next result from.
+/// \param[out] out The result stream to populate
+/// \param[out] rows_affected The number of rows affected if known, else -
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+/// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
Review Comment:
When is "an inappropriate time"?
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,110 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the MultiResultSetNext
+/// or MultiResultSetNextPartitions functions on the AdbcMultiResultSet struct to iterate
+/// through the result sets. The caller is responsible for calling the release function
+/// when finished with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcMultiResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcMultiResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcMultiResultSetRelease(struct AdbcMultiResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next ArrowArrayStream from an AdbcMultiResultSet.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The driver can decide whether to allow fetching the next result set
+/// as a single stream or as a set of partitions. If the driver does not
+/// support fetching the next result set as a stream (indicating it should
+/// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+///
+/// To indicate that no additional result sets are available, this should return
+/// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+/// pattern is that after calling `StatementExecuteMulti`, the caller would
+/// then call `MultiResultSetNext` repeatedly until it returns ADBC_STATUS_OK and
+/// sets the release callback to NULL, indicating that there are no more result sets.
+/// It is not an error to repeatedly call `MultiResultSetNext` after the last result set
+/// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+/// NULL release callback.
+///
+/// \param[in] result_set The result set struct to fetch the next result from.
+/// \param[out] out The result stream to populate
+/// \param[out] rows_affected The number of rows affected if known, else -
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+/// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+/// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+AdbcStatusCode AdbcMultiResultSetNext(struct AdbcMultiResultSet* result_set,
+ struct ArrowArrayStream* out,
+ int64_t* rows_affected, struct AdbcError* error);
+
+/// \brief Get the next result set from a multi-result-set execution as partitions.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The AdbcMultiResultSet must outlive the returned partitions.
Review Comment:
I'm not sure about this (isn't the point of the partitions to be independent of the API objects?)
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1135,6 +1261,40 @@ 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.
+ ///
+ /// When a driver implementing an older spec is loaded by a newer
+ /// driver manager, the newer manager will allocate the new, expanded
+ /// AdbcDriver struct and attempt to have the driver initialize it with
+ /// the newer version. This must return an error, after which the driver
+ /// will try again with successively older versions all the way back to
+ /// ADBC_VERSION_1_0_0. The driver must not access the new fields,
+ /// which will carry undefined values.
Review Comment:
Ping @zeroshade, I think we should at least avoid specifying exactly what the driver manager does here, just that the driver manager expects that if it gives the driver a particular version, it should not try to access any functions defined after that version.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2796306825
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,110 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the MultiResultSetNext
+/// or MultiResultSetNextPartitions functions on the AdbcMultiResultSet struct to iterate
+/// through the result sets. The caller is responsible for calling the release function
+/// when finished with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcMultiResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcMultiResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcMultiResultSetRelease(struct AdbcMultiResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next ArrowArrayStream from an AdbcMultiResultSet.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The driver can decide whether to allow fetching the next result set
+/// as a single stream or as a set of partitions. If the driver does not
+/// support fetching the next result set as a stream (indicating it should
+/// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+///
+/// To indicate that no additional result sets are available, this should return
+/// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+/// pattern is that after calling `StatementExecuteMulti`, the caller would
+/// then call `MultiResultSetNext` repeatedly until it returns ADBC_STATUS_OK and
+/// sets the release callback to NULL, indicating that there are no more result sets.
Review Comment:
I think we can state MAY, and most code will then have to assume it will be invalidated; if you're coding to a specific driver release, then maybe you can make a stronger assumption.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "zeroshade (via GitHub)" <gi...@apache.org>.
zeroshade commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2789152668
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,111 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcMultiResultSet struct to iterate through
+/// the result sets. The caller is responsible for calling the release function when
+/// finished with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcMultiResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcMultiResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcResultSetRelease(struct AdbcMultiResultSet* result_set,
+ struct AdbcError* error);
Review Comment:
updated
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "lidavidm (via GitHub)" <gi...@apache.org>.
lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2710435416
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,95 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief Release the result set and any associated resources.
+ void (*release)(struct AdbcResultSet* result_set);
+
+ /// \brief Get the next result set from a multi-result-set execution.
+ ///
+ /// The AdbcResultSet must outlive the returned ArrowArrayStream.
+ ///
+ /// The driver can decide whether to allow fetching the next result set
+ /// as a single stream or as a set of partitions. If the driver does not
+ /// support fetching the next result set as a stream (indicating it should
+ /// be fetched as partitions), it should return ADBC_STATUS_NOT_IMPLEMENTED.
+ ///
+ /// To indicate that no additional result sets are available, this should return
+ /// ADBC_STATUS_OK and set the release callback on out to NULL. The expected
+ /// pattern is that after calling `StatementExecuteMulti`, the caller would
+ /// then call `NextResultSet` repeatedly until it returns ADBC_STATUS_OK and
+ /// sets the release callback to NULL, indicating that there are no more result sets.
+ /// It is not an error to repeatedly call `NextResultSet` after the last result set
+ /// has been reached; it should simply continue to return ADBC_STATUS_OK with a
+ /// NULL release callback.
+ ///
+ /// \param[in] self The result set struct to fetch the next result from.
+ /// \param[out] out The result stream to populate
+ /// \param[out] rows_affected The number of rows affected if known, else -
+ /// \param[out] error An optional location to return an error message if necessary.
+ ///
+ /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results
+ /// as partitions, ADBC_STATUS_INVALID_STATE if called at an inappropriate time,
+ /// and ADBC_STATUS_OK (or an appropriate error code) otherwise.
+ AdbcStatusCode (*NextResultSet)(struct AdbcResultSet* self,
Review Comment:
Well, but sometimes you just want the schema without getting any data, and in many cases you can do this without actually executing the query, which can save time and money.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "felipecrv (via GitHub)" <gi...@apache.org>.
felipecrv commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2715044853
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcResultSetRelease(struct AdbcResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next result set from a multi-result-set execution.
Review Comment:
What you mean here is `Get the next *ArrowArrayStream* ( our implementation of "result set") from a multi-result-set execution result that we call ResultSet", am I right?
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
Review Comment:
Shouldn't this be called `AdbcMultiResultSet`? Very famous database APIs like Java's [1] call `ResultSet` the set of ROWS returned after the execution of a single query/statement. Whereas here, AFAIU, this is supposed to be the thing that gives me different "results sets" (implemented as `ArrowArrayStream`).
By introducing `struct AdbcResultSet` for this use-case you might confuse people expecting this to be the equivalent of a classic database "result set".
[1] https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSet.html
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcResultSetRelease(struct AdbcResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next result set from a multi-result-set execution.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// The AdbcResultSet must outlive the returned ArrowArrayStream.
Review Comment:
Otherwise what? The `ArrowArrayStream` returns cancellation errors if polled again?
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1135,6 +1261,40 @@ 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.
+ ///
+ /// When a driver implementing an older spec is loaded by a newer
+ /// driver manager, the newer manager will allocate the new, expanded
+ /// AdbcDriver struct and attempt to have the driver initialize it with
+ /// the newer version. This must return an error, after which the driver
+ /// will try again with successively older versions all the way back to
+ /// ADBC_VERSION_1_0_0. The driver must not access the new fields,
+ /// which will carry undefined values.
Review Comment:
Shouldn't the manager populate them with functions that fail immediately?
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
Review Comment:
To be non error-prone, wrapper APIs will have to keep a strong reference to the `AdbcResultSet *` alive inside every Arrow stream produced by this `AdbcResultSet`. Do you agree? If that is the case, it would be better to handle the ref-counting inside the driver IMO.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Spec multi-result-set API [arrow-adbc]
Posted by "felipecrv (via GitHub)" <gi...@apache.org>.
felipecrv commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2715263810
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,113 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to iterate
+/// through the result sets of the execution. The caller can use the NextResultSet or
+/// NextResultSetPartitions functions on the AdbcResultSet struct to iterate through the
+/// result sets. The caller is responsible for calling the release function when finished
+/// with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcResultSetRelease(struct AdbcResultSet* result_set,
+ struct AdbcError* error);
+
+/// \brief Get the next result set from a multi-result-set execution.
Review Comment:
I think the term "result set" should be avoided in this file's comments and only "multi-result-set" and "Arrow stream" should be used.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org