Collaboration diagram for Managing Statements:

Modules
	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
ADBC_EXPORT AdbcStatusCode	AdbcStatementNew (struct AdbcConnection connection, struct AdbcStatement statement, struct AdbcError *error)
	Create a new statement for a given connection.

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

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

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

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

ADBC_EXPORT 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.

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

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

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

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

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

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

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

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

ADBC_EXPORT 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.

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

ADBC_EXPORT 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).

Function Documentation

◆ AdbcStatementNew()

ADBC_EXPORT 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.

◆ AdbcStatementRelease()

ADBC_EXPORT 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.

◆ AdbcStatementExecuteQuery()

ADBC_EXPORT 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()

ADBC_EXPORT 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]	out	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.

◆ AdbcStatementPrepare()

ADBC_EXPORT 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.

◆ AdbcStatementBind()

ADBC_EXPORT 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()

ADBC_EXPORT 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()

ADBC_EXPORT 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.

◆ AdbcStatementGetOption()

ADBC_EXPORT 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()

ADBC_EXPORT 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.

◆ AdbcStatementGetOptionInt()

ADBC_EXPORT 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.

◆ AdbcStatementGetOptionDouble()

ADBC_EXPORT 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.

◆ AdbcStatementGetParameterSchema()

ADBC_EXPORT 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.

◆ AdbcStatementSetOption()

ADBC_EXPORT 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()

ADBC_EXPORT 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

◆ AdbcStatementSetOptionInt()

ADBC_EXPORT 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

◆ AdbcStatementSetOptionDouble()

ADBC_EXPORT 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

Modules

Classes

Functions

Detailed Description

Function Documentation

◆ AdbcStatementNew()

◆ AdbcStatementRelease()

◆ AdbcStatementExecuteQuery()

◆ AdbcStatementExecuteSchema()

◆ AdbcStatementPrepare()

◆ AdbcStatementBind()

◆ AdbcStatementBindStream()

◆ AdbcStatementCancel()

◆ AdbcStatementGetOption()

◆ AdbcStatementGetOptionBytes()

◆ AdbcStatementGetOptionInt()

◆ AdbcStatementGetOptionDouble()

◆ AdbcStatementGetParameterSchema()

◆ AdbcStatementSetOption()

◆ AdbcStatementSetOptionBytes()

◆ AdbcStatementSetOptionInt()

◆ AdbcStatementSetOptionDouble()