Topics
	Partitioned Results

	SQL Semantics

	Substrait Semantics

Classes
struct	AdbcStatement
	A container for all state needed to execute a database query, such as the query itself, parameters for prepared statements, driver parameters, etc. More...

Functions
AdbcStatusCode	AdbcStatementNew (struct AdbcConnection connection, struct AdbcStatement statement, struct AdbcError *error)
	Create a new statement for a given connection.

AdbcStatusCode	AdbcStatementRelease (struct AdbcStatement statement, struct AdbcError error)
	Destroy a statement.

AdbcStatusCode	AdbcStatementExecuteQuery (struct AdbcStatement statement, struct ArrowArrayStream out, int64_t rows_affected, struct AdbcError error)
	Execute a statement and get the results.

AdbcStatusCode	AdbcStatementExecuteSchema (struct AdbcStatement statement, struct ArrowSchema schema, struct AdbcError *error)
	Get the schema of the result set of a query without executing it.

AdbcStatusCode	AdbcStatementPrepare (struct AdbcStatement statement, struct AdbcError error)
	Turn this statement into a prepared statement to be executed multiple times.

AdbcStatusCode	AdbcStatementBind (struct AdbcStatement statement, struct ArrowArray values, struct ArrowSchema schema, struct AdbcError error)
	Bind Arrow data. This can be used for bulk inserts or prepared statements.

AdbcStatusCode	AdbcStatementBindStream (struct AdbcStatement statement, struct ArrowArrayStream stream, struct AdbcError *error)
	Bind Arrow data. This can be used for bulk inserts or prepared statements.

AdbcStatusCode	AdbcStatementCancel (struct AdbcStatement statement, struct AdbcError error)
	Cancel execution of an in-progress query.

AdbcStatusCode	AdbcStatementGetOption (struct AdbcStatement statement, const char key, char value, size_t length, struct AdbcError *error)
	Get a string option of the statement.

AdbcStatusCode	AdbcStatementGetOptionBytes (struct AdbcStatement statement, const char key, uint8_t value, size_t length, struct AdbcError *error)
	Get a bytestring option of the statement.

AdbcStatusCode	AdbcStatementGetOptionInt (struct AdbcStatement statement, const char key, int64_t value, struct AdbcError error)
	Get an integer option of the statement.

AdbcStatusCode	AdbcStatementGetOptionDouble (struct AdbcStatement statement, const char key, double value, struct AdbcError error)
	Get a double option of the statement.

AdbcStatusCode	AdbcStatementGetParameterSchema (struct AdbcStatement statement, struct ArrowSchema schema, struct AdbcError *error)
	Get the schema for bound parameters.

AdbcStatusCode	AdbcStatementSetOption (struct AdbcStatement statement, const char key, const char value, struct AdbcError error)
	Set a string option on a statement.

AdbcStatusCode	AdbcStatementSetOptionBytes (struct AdbcStatement statement, const char key, const uint8_t value, size_t length, struct AdbcError error)
	Set a bytestring option on a statement.

AdbcStatusCode	AdbcStatementSetOptionInt (struct AdbcStatement statement, const char key, int64_t value, struct AdbcError *error)
	Set an integer option on a statement.

AdbcStatusCode	AdbcStatementSetOptionDouble (struct AdbcStatement statement, const char key, double value, struct AdbcError *error)
	Set a double option on a statement.

Detailed Description

Applications should first initialize a statement with AdbcStatementNew. Then, the statement should be configured with functions like AdbcStatementSetSqlQuery and AdbcStatementSetOption. Finally, the statement can be executed with AdbcStatementExecuteQuery (or call AdbcStatementPrepare first to turn it into a prepared statement instead).

Class Documentation

◆ AdbcStatement

struct AdbcStatement

A container for all state needed to execute a database query, such as the query itself, parameters for prepared statements, driver parameters, etc.

Statements may represent queries or prepared statements.

Statements may be used multiple times and can be reconfigured (e.g. they can be reused to execute multiple different queries). However, executing a statement (and changing certain other state) will invalidate result sets obtained prior to that execution.

Multiple statements may be created from a single connection. However, the driver may block or error if they are used concurrently (whether from a single thread or multiple threads).

Statements are not required to be thread-safe, but they can be used from multiple threads so long as clients take care to serialize accesses to a statement.

Public Attributes
void *	private_data
	Opaque implementation-defined state. This field is NULLPTR iff the connection is unintialized/freed.

struct AdbcDriver *	private_driver
	The associated driver (used by the driver manager to help track state).

Member Data Documentation

◆ private_data

void* AdbcStatement::private_data

Opaque implementation-defined state. This field is NULLPTR iff the connection is unintialized/freed.

◆ private_driver

struct AdbcDriver* AdbcStatement::private_driver

The associated driver (used by the driver manager to help track state).

Function Documentation

◆ AdbcStatementBind()

AdbcStatusCode AdbcStatementBind	(	struct AdbcStatement *	statement,
		struct ArrowArray *	values,
		struct ArrowSchema *	schema,
		struct AdbcError *	error )

Bind Arrow data. This can be used for bulk inserts or prepared statements.

Parameters

[in]	statement	The statement to bind to.
[in]	values	The values to bind. The driver will call the release callback itself, although it may not do this until the statement is released.
[in]	schema	The schema of the values to bind.
[out]	error	An optional location to return an error message if necessary.

◆ AdbcStatementBindStream()

AdbcStatusCode AdbcStatementBindStream	(	struct AdbcStatement *	statement,
		struct ArrowArrayStream *	stream,
		struct AdbcError *	error )

Bind Arrow data. This can be used for bulk inserts or prepared statements.

Parameters

[in]	statement	The statement to bind to.
[in]	stream	The values to bind. The driver will call the release callback itself, although it may not do this until the statement is released.
[out]	error	An optional location to return an error message if necessary.

◆ AdbcStatementCancel()

AdbcStatusCode AdbcStatementCancel	(	struct AdbcStatement *	statement,
		struct AdbcError *	error )

Cancel execution of an in-progress query.

This can be called during AdbcStatementExecuteQuery (or similar), or while consuming an ArrowArrayStream returned from such. Calling this function should make the other functions return ADBC_STATUS_CANCELLED (from ADBC functions) or ECANCELED (from methods of ArrowArrayStream). (It is not guaranteed to, for instance, the result set may be buffered in memory already.)

This must always be thread-safe (other operations are not). It is not necessarily signal-safe.

Since: ADBC API revision 1.1.0

Parameters

[in]	statement	The statement to cancel.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_INVALID_STATE if there is no query to cancel.; ADBC_STATUS_UNKNOWN if the query could not be cancelled.

◆ AdbcStatementExecuteQuery()

AdbcStatusCode AdbcStatementExecuteQuery	(	struct AdbcStatement *	statement,
		struct ArrowArrayStream *	out,
		int64_t *	rows_affected,
		struct AdbcError *	error )

Execute a statement and get the results.

This invalidates any prior result sets. This AdbcStatement must outlive the returned ArrowArrayStream.

Since ADBC 1.1.0: releasing the returned ArrowArrayStream without consuming it fully is equivalent to calling AdbcStatementCancel.

Parameters

[in]	statement	The statement to execute.
[out]	out	The results. Pass NULL if the client does not expect a result set.
[out]	rows_affected	The number of rows affected if known, else -1. Pass NULL if the client does not want this information.
[out]	error	An optional location to return an error message if necessary.

◆ AdbcStatementExecuteSchema()

AdbcStatusCode AdbcStatementExecuteSchema	(	struct AdbcStatement *	statement,
		struct ArrowSchema *	schema,
		struct AdbcError *	error )

Get the schema of the result set of a query without executing it.

This invalidates any prior result sets.

Depending on the driver, this may require first executing AdbcStatementPrepare.

Since: ADBC API revision 1.1.0

Parameters

[in]	statement	The statement to execute.
[out]	schema	The result schema.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_IMPLEMENTED if the driver does not support this.

◆ AdbcStatementGetOption()

AdbcStatusCode AdbcStatementGetOption	(	struct AdbcStatement *	statement,
		const char *	key,
		char *	value,
		size_t *	length,
		struct AdbcError *	error )

Get a string option of the statement.

This must always be thread-safe (other operations are not), though given the semantics here, it is not recommended to call GetOption concurrently with itself.

length must be provided and must be the size of the buffer pointed to by value. If there is sufficient space, the driver will copy the option value (including the null terminator) to buffer and set length to the size of the actual value. If the buffer is too small, no data will be written and length will be set to the required length.

In other words:

If output length <= input length, value will contain a value with length bytes.
If output length > input length, nothing has been written to value.

For standard options, drivers must always support getting the option value (if they support getting option values at all) via the type specified in the option. (For example, an option set via SetOptionDouble must be retrievable via GetOptionDouble.) Drivers may also support getting a converted option value via other getters if needed. (For example, getting the string representation of a double option.)

Since: ADBC API revision 1.1.0

Parameters

[in]	statement	The statement.
[in]	key	The option to get.
[out]	value	The option value.
[in,out]	length	The length of value.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_FOUND if the option is not recognized.

◆ AdbcStatementGetOptionBytes()

AdbcStatusCode AdbcStatementGetOptionBytes	(	struct AdbcStatement *	statement,
		const char *	key,
		uint8_t *	value,
		size_t *	length,
		struct AdbcError *	error )

Get a bytestring option of the statement.

This must always be thread-safe (other operations are not), though given the semantics here, it is not recommended to call GetOptionBytes concurrently with itself.

length must be provided and must be the size of the buffer pointed to by value. If there is sufficient space, the driver will copy the option value to buffer and set length to the size of the actual value. If the buffer is too small, no data will be written and length will be set to the required length.

In other words:

If output length <= input length, value will contain a value with length bytes.
If output length > input length, nothing has been written to value.

For standard options, drivers must always support getting the option value (if they support getting option values at all) via the type specified in the option. (For example, an option set via SetOptionDouble must be retrievable via GetOptionDouble.) Drivers may also support getting a converted option value via other getters if needed. (For example, getting the string representation of a double option.)

Since: ADBC API revision 1.1.0

Parameters

[in]	statement	The statement.
[in]	key	The option to get.
[out]	value	The option value.
[in,out]	length	The option value length.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_FOUND if the option is not recognized.

◆ AdbcStatementGetOptionDouble()

AdbcStatusCode AdbcStatementGetOptionDouble	(	struct AdbcStatement *	statement,
		const char *	key,
		double *	value,
		struct AdbcError *	error )

Get a double option of the statement.

This must always be thread-safe (other operations are not).

For standard options, drivers must always support getting the option value (if they support getting option values at all) via the type specified in the option. (For example, an option set via SetOptionDouble must be retrievable via GetOptionDouble.) Drivers may also support getting a converted option value via other getters if needed. (For example, getting the string representation of a double option.)

Since: ADBC API revision 1.1.0

Parameters

[in]	statement	The statement.
[in]	key	The option to get.
[out]	value	The option value.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_FOUND if the option is not recognized.

◆ AdbcStatementGetOptionInt()

AdbcStatusCode AdbcStatementGetOptionInt	(	struct AdbcStatement *	statement,
		const char *	key,
		int64_t *	value,
		struct AdbcError *	error )

Get an integer option of the statement.

This must always be thread-safe (other operations are not).

For standard options, drivers must always support getting the option value (if they support getting option values at all) via the type specified in the option. (For example, an option set via SetOptionDouble must be retrievable via GetOptionDouble.) Drivers may also support getting a converted option value via other getters if needed. (For example, getting the string representation of a double option.)

Since: ADBC API revision 1.1.0

Parameters

[in]	statement	The statement.
[in]	key	The option to get.
[out]	value	The option value.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_FOUND if the option is not recognized.

◆ AdbcStatementGetParameterSchema()

AdbcStatusCode AdbcStatementGetParameterSchema	(	struct AdbcStatement *	statement,
		struct ArrowSchema *	schema,
		struct AdbcError *	error )

Get the schema for bound parameters.

This retrieves an Arrow schema describing the number, names, and types of the parameters in a parameterized statement. The fields of the schema should be in order of the ordinal position of the parameters; named parameters should appear only once.

If the parameter does not have a name, or the name cannot be determined, the name of the corresponding field in the schema will be an empty string. If the type cannot be determined, the type of the corresponding field will be NA (NullType).

This should be called after AdbcStatementPrepare.

Returns: ADBC_STATUS_NOT_IMPLEMENTED if the schema cannot be determined.

◆ AdbcStatementNew()

AdbcStatusCode AdbcStatementNew	(	struct AdbcConnection *	connection,
		struct AdbcStatement *	statement,
		struct AdbcError *	error )

Create a new statement for a given connection.

Callers pass in a zero-initialized AdbcStatement.

Drivers should allocate their internal data structure and set the private_data field to point to the newly allocated struct. This struct should be released when AdbcStatementRelease is called.

◆ AdbcStatementPrepare()

AdbcStatusCode AdbcStatementPrepare	(	struct AdbcStatement *	statement,
		struct AdbcError *	error )

Turn this statement into a prepared statement to be executed multiple times.

This invalidates any prior result sets.

◆ AdbcStatementRelease()

AdbcStatusCode AdbcStatementRelease	(	struct AdbcStatement *	statement,
		struct AdbcError *	error )

Destroy a statement.

Parameters

[in]	statement	The statement to release.
[out]	error	An optional location to return an error message if necessary.

◆ AdbcStatementSetOption()

AdbcStatusCode AdbcStatementSetOption	(	struct AdbcStatement *	statement,
		const char *	key,
		const char *	value,
		struct AdbcError *	error )

Set a string option on a statement.

Parameters

[in]	statement	The statement.
[in]	key	The option to set.
[in]	value	The option value.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized.

◆ AdbcStatementSetOptionBytes()

AdbcStatusCode AdbcStatementSetOptionBytes	(	struct AdbcStatement *	statement,
		const char *	key,
		const uint8_t *	value,
		size_t	length,
		struct AdbcError *	error )

Set a bytestring option on a statement.

Since: ADBC API revision 1.1.0

Parameters

[in]	statement	The statement.
[in]	key	The option to set.
[in]	value	The option value.
[in]	length	The option value length.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized

◆ AdbcStatementSetOptionDouble()

AdbcStatusCode AdbcStatementSetOptionDouble	(	struct AdbcStatement *	statement,
		const char *	key,
		double	value,
		struct AdbcError *	error )

Set a double option on a statement.

Since: ADBC API revision 1.1.0

Parameters

[in]	statement	The statement.
[in]	key	The option to set.
[in]	value	The option value.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized

◆ AdbcStatementSetOptionInt()

AdbcStatusCode AdbcStatementSetOptionInt	(	struct AdbcStatement *	statement,
		const char *	key,
		int64_t	value,
		struct AdbcError *	error )

Set an integer option on a statement.

Since: ADBC API revision 1.1.0

Parameters

[in]	statement	The statement.
[in]	key	The option to set.
[in]	value	The option value.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized

Topics

Classes

Functions

Detailed Description

Class Documentation

◆ AdbcStatement

Public Attributes

Member Data Documentation

◆ private_data

◆ private_driver

Function Documentation

◆ AdbcStatementBind()

◆ AdbcStatementBindStream()

◆ AdbcStatementCancel()

◆ AdbcStatementExecuteQuery()

◆ AdbcStatementExecuteSchema()

◆ AdbcStatementGetOption()

◆ AdbcStatementGetOptionBytes()

◆ AdbcStatementGetOptionDouble()

◆ AdbcStatementGetOptionInt()

◆ AdbcStatementGetParameterSchema()

◆ AdbcStatementNew()

◆ AdbcStatementPrepare()

◆ AdbcStatementRelease()

◆ AdbcStatementSetOption()

◆ AdbcStatementSetOptionBytes()

◆ AdbcStatementSetOptionDouble()

◆ AdbcStatementSetOptionInt()