Skip to content

Commit

Permalink
[Format][C][Java] Simplify Execute/Query interface
Browse files Browse the repository at this point in the history 
Fixes apache#61.
  • Loading branch information
@lidavidm
lidavidm committed Aug 17, 2022
1 parent 1aee47e commit fb2f385
Show file tree
Hide file tree
Showing 5 changed files with 138 additions and 145 deletions.
155 changes: 85 additions & 70 deletions adbc.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -387,16 +387,22 @@ AdbcStatusCode AdbcConnectionRelease(struct AdbcConnection* connection,
/// \defgroup adbc-connection-metadata Metadata
/// Functions for retrieving metadata about the database.
///
/// Generally, these functions return an AdbcStatement that can be evaluated to
/// get the metadata as Arrow data. The returned metadata has an expected
/// schema given in the function docstring. Schema fields are nullable unless
/// otherwise marked.
///
/// Some functions accept "search pattern" arguments, which are strings that
/// can contain the special character "%" to match zero or more characters, or
/// "_" to match exactly one character. (See the documentation of
/// DatabaseMetaData in JDBC or "Pattern Value Arguments" in the ODBC
/// documentation.) Escaping is not currently supported.
/// Generally, these functions return an ArrowArrayStream that can be
/// consumed to get the metadata as Arrow data. The returned metadata
/// has an expected schema given in the function docstring. Schema
/// fields are nullable unless otherwise marked. While no
/// AdbcStatement is used in these functions, the result set may count
/// as an active statement to the driver for the purposes of
/// concurrency management (e.g. if the driver has a limit on
/// concurrent active statements and it must execute a SQL query
/// internally in order to implement the metadata function).
///
/// Some functions accept "search pattern" arguments, which are
/// strings that can contain the special character "%" to match zero
/// or more characters, or "_" to match exactly one character. (See
/// the documentation of DatabaseMetaData in JDBC or "Pattern Value
/// Arguments" in the ODBC documentation.) Escaping is not currently
/// supported.
///
/// @{

Expand Down Expand Up @@ -430,13 +436,12 @@ AdbcStatusCode AdbcConnectionRelease(struct AdbcConnection* connection,
/// to fetch all.
/// \param[in] info_codes_length The length of the info_codes
/// parameter. Ignored if info_codes is NULL.
/// \param[out] statement The result set. AdbcStatementGetStream can
/// be called immediately; do not call Execute or Prepare.
/// \param[out] out The result set.
/// \param[out] error Error details, if an error occurs.
ADBC_EXPORT
AdbcStatusCode AdbcConnectionGetInfo(struct AdbcConnection* connection,
uint32_t* info_codes, size_t info_codes_length,
struct AdbcStatement* statement,
struct ArrowArrayStream* out,
struct AdbcError* error);

/// \brief The database vendor/product name (e.g. the server name).
Expand Down Expand Up @@ -555,15 +560,14 @@ AdbcStatusCode AdbcConnectionGetInfo(struct AdbcConnection* connection,
/// \param[in] column_name Only show columns with the given name. If
/// NULL, do not filter by name. May be a search pattern (see
/// section documentation).
/// \param[out] statement The result set. AdbcStatementGetStream can
/// be called immediately; do not call Execute or Prepare.
/// \param[out] out The result set.
/// \param[out] error Error details, if an error occurs.
ADBC_EXPORT
AdbcStatusCode AdbcConnectionGetObjects(struct AdbcConnection* connection, int depth,
const char* catalog, const char* db_schema,
const char* table_name, const char** table_type,
const char* column_name,
struct AdbcStatement* statement,
struct ArrowArrayStream* out,
struct AdbcError* error);

#define ADBC_OBJECT_DEPTH_ALL 0
Expand Down Expand Up @@ -596,11 +600,11 @@ AdbcStatusCode AdbcConnectionGetTableSchema(struct AdbcConnection* connection,
/// table_type | utf8 not null
///
/// \param[in] connection The database connection.
/// \param[out] statement The result set.
/// \param[out] out The result set.
/// \param[out] error Error details, if an error occurs.
ADBC_EXPORT
AdbcStatusCode AdbcConnectionGetTableTypes(struct AdbcConnection* connection,
struct AdbcStatement* statement,
struct ArrowArrayStream* out,
struct AdbcError* error);

/// @}
Expand Down Expand Up @@ -718,17 +722,48 @@ ADBC_EXPORT
AdbcStatusCode AdbcStatementRelease(struct AdbcStatement* statement,
struct AdbcError* error);

/// \brief Execute a statement.
///
/// This invalidates any prior result sets (AdbcStatementGetStream).
/// \brief Execute a statement and get the results.
///
/// This invalidates any prior result sets.
///
/// \param[in] statement The statement to execute.
/// \param[in] out_type The expected result type:
/// - ADBC_OUTPUT_TYPE_NONE if the query should not generate a
/// result set;
/// - ADBC_OUTPUT_TYPE_ARROW for an ArrowArrayStream;
/// - ADBC_OUTPUT_TYPE_PARTITIONS for a count of partitions (see \ref
/// adbc-statement-partition below).
/// The result set will be in out.
/// \param[out] out The results. Must be NULL for output type NONE, a
/// pointer to an ArrowArrayStream for ARROW_ARRAY_STREAM, or a
/// pointer to a size_t for PARTITIONS.
/// \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.
ADBC_EXPORT
AdbcStatusCode AdbcStatementExecute(struct AdbcStatement* statement,
AdbcStatusCode AdbcStatementExecute(struct AdbcStatement* statement, int output_type,
void* out, int64_t* rows_affected,
struct AdbcError* error);

/// \brief No results are expected from AdbcStatementExecute. Pass
/// NULL to out.
#define ADBC_OUTPUT_TYPE_NONE 0
/// \brief Arrow data is expected from AdbcStatementExecute. Pass
/// ArrowArrayStream* to out.
#define ADBC_OUTPUT_TYPE_ARROW 1
/// \brief Partitions are expected from AdbcStatementExecute. Pass
/// size_t* to out to get the number of partitions, and use
/// AdbcStatementGetPartitionDesc to get a partition.
///
/// Drivers are not required to support partitioning. In that case,
/// AdbcStatementExecute will return ADBC_STATUS_NOT_IMPLEMENTED.
#define ADBC_OUTPUT_TYPE_PARTITIONS 2

/// \brief Turn this statement into a prepared statement to be
/// executed multiple times.
///
/// This invalidates any prior result sets (AdbcStatementGetStream).
/// This invalidates any prior result sets.
ADBC_EXPORT
AdbcStatusCode AdbcStatementPrepare(struct AdbcStatement* statement,
struct AdbcError* error);
Expand Down Expand Up @@ -827,34 +862,20 @@ AdbcStatusCode AdbcStatementGetParameterSchema(struct AdbcStatement* statement,
struct ArrowSchema* schema,
struct AdbcError* error);

/// \brief Read the result of a statement.
///
/// This method can be called only once per execution of the
/// statement. It may not be called if any of the partitioning methods
/// have been called (see below).
///
/// This invalidates any prior result sets (AdbcStatementGetStream).
///
/// \return out A stream of Arrow data. The stream itself must be
/// released before the statement is released.
ADBC_EXPORT
AdbcStatusCode AdbcStatementGetStream(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
struct AdbcError* error);

/// \brief Set a string option on a statement.
ADBC_EXPORT
AdbcStatusCode AdbcStatementSetOption(struct AdbcStatement* statement, const char* key,
const char* value, struct AdbcError* error);

/// \defgroup adbc-statement-ingestion Bulk Data Ingestion
/// While it is possible to insert data via prepared statements, it
/// can be more efficient to explicitly perform a bulk insert. For
/// While it is possible to insert data via prepared statements, it can
/// be more efficient to explicitly perform a bulk insert. For
/// compatible drivers, this can be accomplished by setting up and
/// executing a statement. Instead of setting a SQL query or
/// Substrait plan, bind the source data via AdbcStatementBind, and
/// set the name of the table to be created via AdbcStatementSetOption
/// and the options below.
/// executing a statement. Instead of setting a SQL query or Substrait
/// plan, bind the source data via AdbcStatementBind, and set the name
/// of the table to be created via AdbcStatementSetOption and the
/// options below. Then, call AdbcStatementExecute with
/// ADBC_OUTPUT_TYPE_NONE.
///
/// @{

Expand All @@ -880,36 +901,30 @@ AdbcStatusCode AdbcStatementSetOption(struct AdbcStatement* statement, const cha
/// Some backends may internally partition the results. These
/// partitions are exposed to clients who may wish to integrate them
/// with a threaded or distributed execution model, where partitions
/// can be divided among threads or machines. Partitions are exposed
/// as an iterator.
/// can be divided among threads or machines and fetched in parallel.
///
/// Drivers are not required to support partitioning. In this case,
/// num_partitions will return 0. They are required to support
/// AdbcStatementGetStream.
/// To use partitioning, pass ADBC_OUTPUT_TYPE_PARTITIONS to
/// AdbcStatementExecute. Then, use these functions to get the actual
/// partition descriptors. Call AdbcConnectionDeserializePartitionDesc
/// to turn the individual descriptors into AdbcStatement instances.
///
/// If any of the partitioning methods are called,
/// AdbcStatementGetStream may not be called, and vice versa.
/// Drivers are not required to support partitioning.
///
/// @{

/// \brief Get the length of the serialized descriptor for the current
/// partition.
/// \brief Get the length of a serialized descriptor for a partition.
///
/// This method must be called first, before calling other partitioning
/// methods. This method may block and perform I/O.
/// \param[in] statement The statement.
/// \param[out] length The length of the serialized partition, or 0 if there
/// are no more partitions.
/// \param[in] index Which partition to get.
/// \param[out] length The length of the serialized partition.
/// \param[out] error An optional location to return an error message if
/// necessary.
ADBC_EXPORT
AdbcStatusCode AdbcStatementGetPartitionDescSize(struct AdbcStatement* statement,
size_t* length, struct AdbcError* error);
size_t index, size_t* length,
struct AdbcError* error);

/// \brief Get the serialized descriptor for the current partition, and advance
/// the iterator.
///
/// This method may block and perform I/O.
/// \brief Get the serialized descriptor for a partition.
///
/// A partition can be turned back into a statement via
/// AdbcConnectionDeserializePartitionDesc. Effectively, this means
Expand All @@ -918,14 +933,15 @@ AdbcStatusCode AdbcStatementGetPartitionDescSize(struct AdbcStatement* statement
/// getting the arrow::flight::Ticket.
///
/// \param[in] statement The statement.
/// \param[in] index Which partition to get.
/// \param[out] partition_desc A caller-allocated buffer, to which the
/// serialized partition will be written. The length to allocate can be
/// queried with AdbcStatementGetPartitionDescSize.
/// \param[out] error An optional location to return an error message if
/// necessary.
ADBC_EXPORT
AdbcStatusCode AdbcStatementGetPartitionDesc(struct AdbcStatement* statement,
uint8_t* partition_desc,
size_t index, uint8_t* partition_desc,
struct AdbcError* error);

/// @}
Expand Down Expand Up @@ -967,7 +983,7 @@ struct ADBC_EXPORT AdbcDriver {
AdbcStatusCode (*DatabaseRelease)(struct AdbcDatabase*, struct AdbcError*);

AdbcStatusCode (*ConnectionGetInfo)(struct AdbcConnection*, uint32_t*, size_t,
struct AdbcStatement*, struct AdbcError*);
struct ArrowArrayStream*, struct AdbcError*);
AdbcStatusCode (*ConnectionNew)(struct AdbcConnection*, struct AdbcError*);
AdbcStatusCode (*ConnectionSetOption)(struct AdbcConnection*, const char*, const char*,
struct AdbcError*);
Expand Down Expand Up @@ -1000,15 +1016,14 @@ struct ADBC_EXPORT AdbcDriver {
struct ArrowSchema*, struct AdbcError*);
AdbcStatusCode (*StatementBindStream)(struct AdbcStatement*, struct ArrowArrayStream*,
struct AdbcError*);
AdbcStatusCode (*StatementExecute)(struct AdbcStatement*, struct AdbcError*);
AdbcStatusCode (*StatementExecute)(struct AdbcStatement*, int, void*, int64_t*,
struct AdbcError*);
AdbcStatusCode (*StatementPrepare)(struct AdbcStatement*, struct AdbcError*);
AdbcStatusCode (*StatementGetParameterSchema)(struct AdbcStatement*,
struct ArrowSchema*, struct AdbcError*);
AdbcStatusCode (*StatementGetStream)(struct AdbcStatement*, struct ArrowArrayStream*,
struct AdbcError*);
AdbcStatusCode (*StatementGetPartitionDescSize)(struct AdbcStatement*, size_t*,
AdbcStatusCode (*StatementGetPartitionDescSize)(struct AdbcStatement*, size_t, size_t*,
struct AdbcError*);
AdbcStatusCode (*StatementGetPartitionDesc)(struct AdbcStatement*, uint8_t*,
AdbcStatusCode (*StatementGetPartitionDesc)(struct AdbcStatement*, size_t, uint8_t*,
struct AdbcError*);
AdbcStatusCode (*StatementSetOption)(struct AdbcStatement*, const char*, const char*,
struct AdbcError*);
Expand Down Expand Up @@ -1038,7 +1053,7 @@ typedef AdbcStatusCode (*AdbcDriverInitFunc)(size_t count, struct AdbcDriver* dr
// struct/entrypoint instead?

// For use with count
#define ADBC_VERSION_0_0_1 26
#define ADBC_VERSION_0_0_1 27

/// @}

Expand Down
43 changes: 16 additions & 27 deletions c/driver_manager/adbc_driver_manager.cc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,22 +98,18 @@ AdbcStatusCode StatementBind(struct AdbcStatement*, struct ArrowArray*,
return ADBC_STATUS_NOT_IMPLEMENTED;
}

AdbcStatusCode StatementExecute(struct AdbcStatement*, struct AdbcError* error) {
return ADBC_STATUS_NOT_IMPLEMENTED;
}

AdbcStatusCode StatementGetParameterSchema(struct AdbcStatement* statement,
struct ArrowSchema* schema,
struct AdbcError* error) {
return ADBC_STATUS_NOT_IMPLEMENTED;
}

AdbcStatusCode StatementGetPartitionDesc(struct AdbcStatement*, uint8_t*,
AdbcStatusCode StatementGetPartitionDesc(struct AdbcStatement*, size_t, uint8_t*,
struct AdbcError*) {
return ADBC_STATUS_NOT_IMPLEMENTED;
}

AdbcStatusCode StatementGetPartitionDescSize(struct AdbcStatement*, size_t*,
AdbcStatusCode StatementGetPartitionDescSize(struct AdbcStatement*, size_t, size_t*,
struct AdbcError*) {
return ADBC_STATUS_NOT_IMPLEMENTED;
}
Expand Down Expand Up @@ -328,13 +324,13 @@ AdbcStatusCode AdbcConnectionCommit(struct AdbcConnection* connection,

AdbcStatusCode AdbcConnectionGetInfo(struct AdbcConnection* connection,
uint32_t* info_codes, size_t info_codes_length,
struct AdbcStatement* statement,
struct ArrowArrayStream* out,
struct AdbcError* error) {
if (!connection->private_driver) {
return ADBC_STATUS_INVALID_STATE;
}
return connection->private_driver->ConnectionGetInfo(
connection, info_codes, info_codes_length, statement, error);
return connection->private_driver->ConnectionGetInfo(connection, info_codes,
info_codes_length, out, error);
}

AdbcStatusCode AdbcConnectionGetObjects(struct AdbcConnection* connection, int depth,
Expand Down Expand Up @@ -454,32 +450,34 @@ AdbcStatusCode AdbcStatementBindStream(struct AdbcStatement* statement,
return statement->private_driver->StatementBindStream(statement, stream, error);
}

AdbcStatusCode AdbcStatementExecute(struct AdbcStatement* statement,
AdbcStatusCode AdbcStatementExecute(struct AdbcStatement* statement, int output_type,
void* out, int64_t* rows_affected,
struct AdbcError* error) {
if (!statement->private_driver) {
return ADBC_STATUS_INVALID_STATE;
}
return statement->private_driver->StatementExecute(statement, error);
return statement->private_driver->StatementExecute(statement, output_type, out,
rows_affected, error);
}

AdbcStatusCode AdbcStatementGetPartitionDesc(struct AdbcStatement* statement,
uint8_t* partition_desc,
size_t index, uint8_t* partition_desc,
struct AdbcError* error) {
if (!statement->private_driver) {
return ADBC_STATUS_INVALID_STATE;
}
return statement->private_driver->StatementGetPartitionDesc(statement, partition_desc,
error);
return statement->private_driver->StatementGetPartitionDesc(statement, index,
partition_desc, error);
}

AdbcStatusCode AdbcStatementGetPartitionDescSize(struct AdbcStatement* statement,
size_t* length,
size_t index, size_t* length,
struct AdbcError* error) {
if (!statement->private_driver) {
return ADBC_STATUS_INVALID_STATE;
}
return statement->private_driver->StatementGetPartitionDescSize(statement, length,
error);
return statement->private_driver->StatementGetPartitionDescSize(statement, index,
length, error);
}

AdbcStatusCode AdbcStatementGetParameterSchema(struct AdbcStatement* statement,
Expand All @@ -491,15 +489,6 @@ AdbcStatusCode AdbcStatementGetParameterSchema(struct AdbcStatement* statement,
return statement->private_driver->StatementGetParameterSchema(statement, schema, error);
}

AdbcStatusCode AdbcStatementGetStream(struct AdbcStatement* statement,
struct ArrowArrayStream* out,
struct AdbcError* error) {
if (!statement->private_driver) {
return ADBC_STATUS_INVALID_STATE;
}
return statement->private_driver->StatementGetStream(statement, out, error);
}

AdbcStatusCode AdbcStatementNew(struct AdbcConnection* connection,
struct AdbcStatement* statement,
struct AdbcError* error) {
Expand Down Expand Up @@ -718,10 +707,10 @@ AdbcStatusCode AdbcLoadDriver(const char* driver_name, const char* entrypoint,
FILL_DEFAULT(driver, ConnectionRollback);
FILL_DEFAULT(driver, ConnectionSetOption);

CHECK_REQUIRED(driver, StatementExecute);
CHECK_REQUIRED(driver, StatementNew);
CHECK_REQUIRED(driver, StatementRelease);
FILL_DEFAULT(driver, StatementBind);
FILL_DEFAULT(driver, StatementExecute);
FILL_DEFAULT(driver, StatementGetParameterSchema);
FILL_DEFAULT(driver, StatementGetPartitionDesc);
FILL_DEFAULT(driver, StatementGetPartitionDescSize);
Expand Down
Loading

0 comments on commit fb2f385

Please sign in to comment.