主题
	分区结果

	SQL 语义

	Substrait 语义

类
结构体	AdbcStatement
	用于容纳执行数据库查询所需的所有状态的容器，例如查询本身、预处理语句的参数、驱动程序参数等。更多...

函数
AdbcStatusCode	AdbcStatementNew (struct AdbcConnection connection, struct AdbcStatement statement, struct AdbcError *error)
	为给定的连接创建一个新语句。

AdbcStatusCode	AdbcStatementRelease (struct AdbcStatement statement, struct AdbcError error)
	销毁一个语句。

AdbcStatusCode	AdbcStatementExecuteQuery (struct AdbcStatement statement, struct ArrowArrayStream out, int64_t rows_affected, struct AdbcError error)
	执行一个语句并获取结果。

AdbcStatusCode	AdbcStatementExecuteSchema (struct AdbcStatement statement, struct ArrowSchema schema, struct AdbcError *error)
	获取查询结果集的模式，而不执行查询。

AdbcStatusCode	AdbcStatementPrepare (struct AdbcStatement statement, struct AdbcError error)
	将此语句转换为预处理语句，以便多次执行。

AdbcStatusCode	AdbcStatementBind (struct AdbcStatement statement, struct ArrowArray values, struct ArrowSchema schema, struct AdbcError error)
	绑定 Arrow 数据。这可用于批量插入或预处理语句。

AdbcStatusCode	AdbcStatementBindStream (struct AdbcStatement statement, struct ArrowArrayStream stream, struct AdbcError *error)
	绑定 Arrow 数据。这可用于批量插入或预处理语句。

AdbcStatusCode	AdbcStatementCancel (struct AdbcStatement statement, struct AdbcError error)
	取消正在进行的查询的执行。

AdbcStatusCode	AdbcStatementGetOption (struct AdbcStatement statement, const char key, char value, size_t length, struct AdbcError *error)
	获取语句的字符串选项。

AdbcStatusCode	AdbcStatementGetOptionBytes (struct AdbcStatement statement, const char key, uint8_t value, size_t length, struct AdbcError *error)
	获取语句的字节串选项。

AdbcStatusCode	AdbcStatementGetOptionInt (struct AdbcStatement statement, const char key, int64_t value, struct AdbcError error)
	获取语句的整数选项。

AdbcStatusCode	AdbcStatementGetOptionDouble (struct AdbcStatement statement, const char key, double value, struct AdbcError error)
	获取语句的双精度浮点数选项。

AdbcStatusCode	AdbcStatementGetParameterSchema (struct AdbcStatement statement, struct ArrowSchema schema, struct AdbcError *error)
	获取绑定参数的模式。

AdbcStatusCode	AdbcStatementSetOption (struct AdbcStatement statement, const char key, const char value, struct AdbcError error)
	在语句上设置字符串选项。

AdbcStatusCode	AdbcStatementSetOptionBytes (struct AdbcStatement statement, const char key, const uint8_t value, size_t length, struct AdbcError error)
	在语句上设置字节串选项。

AdbcStatusCode	AdbcStatementSetOptionInt (struct AdbcStatement statement, const char key, int64_t value, struct AdbcError *error)
	在语句上设置整数选项。

AdbcStatusCode	AdbcStatementSetOptionDouble (struct AdbcStatement statement, const char key, double value, struct AdbcError *error)
	在语句上设置双精度浮点数选项。

详细描述

应用程序应首先使用 AdbcStatementNew 初始化语句。然后，应使用 AdbcStatementSetSqlQuery 和 AdbcStatementSetOption 等函数配置语句。最后，可以使用 AdbcStatementExecuteQuery 执行语句（或先调用 AdbcStatementPrepare 将其转换为预处理语句）。

类文档

◆ AdbcStatement

struct AdbcStatement

用于容纳执行数据库查询所需的所有状态的容器，例如查询本身、预处理语句的参数、驱动程序参数等。

语句可以表示查询或预处理语句。

语句可以多次使用并且可以重新配置（例如，它们可以重复使用以执行多个不同的查询）。但是，执行语句（以及更改某些其他状态）将使在该执行之前获得的结果集无效。

可以从单个连接创建多个语句。但是，如果同时使用它们（无论是来自单个线程还是多个线程），驱动程序可能会阻止或出错。

语句不需要是线程安全的，但是它们可以从多个线程中使用，只要客户端注意序列化对语句的访问即可。

公共属性
void *	private_data
	不透明的实现定义状态。如果连接未初始化/释放，则此字段为 NULLPTR。

struct AdbcDriver *	private_driver
	关联的驱动程序（由驱动程序管理器使用以帮助跟踪状态）。

成员数据文档

◆ private_data

void* AdbcStatement::private_data

不透明的实现定义状态。如果连接未初始化/释放，则此字段为 NULLPTR。

◆ private_driver

struct AdbcDriver* AdbcStatement::private_driver

关联的驱动程序（由驱动程序管理器使用以帮助跟踪状态）。

函数文档

◆ AdbcStatementBind()

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

绑定 Arrow 数据。这可用于批量插入或预处理语句。

参数

[in]	statement	要绑定的语句。
[in]	values	要绑定的值。驱动程序将自行调用 release 回调，尽管它可能要等到语句释放后才会这样做。
[in]	schema	要绑定的值的模式。
[out]	error	必要时返回错误消息的可选位置。

◆ AdbcStatementBindStream()

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

绑定 Arrow 数据。这可用于批量插入或预处理语句。

参数

[in]	statement	要绑定的语句。
[in]	stream	要绑定的值。驱动程序将自行调用 release 回调，尽管它可能要等到语句释放后才会这样做。
[out]	error	必要时返回错误消息的可选位置。

◆ AdbcStatementCancel()

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

取消正在进行的查询的执行。

可以在 AdbcStatementExecuteQuery（或类似函数）期间调用此函数，或者在使用从此类函数返回的 ArrowArrayStream 时调用此函数。调用此函数应使其他函数返回 ADBC_STATUS_CANCELLED（来自 ADBC 函数）或 ECANCELED（来自 ArrowArrayStream 的方法）。（不能保证，例如，结果集可能已缓冲在内存中。）

这必须始终是线程安全的（其他操作不是）。它不一定是信号安全的。

自: ADBC API 修订版 1.1.0

参数

[in]	statement	要取消的语句。
[out]	error	必要时返回错误消息的可选位置。

返回值: 如果没有要取消的查询，则返回 ADBC_STATUS_INVALID_STATE。; 如果无法取消查询，则返回 ADBC_STATUS_UNKNOWN。

◆ AdbcStatementExecuteQuery()

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

执行一个语句并获取结果。

这会使任何先前的结果集无效。此 AdbcStatement 必须比返回的 ArrowArrayStream 存活更久。

自 ADBC 1.1.0 起：在未完全使用返回的 ArrowArrayStream 的情况下释放它等效于调用 AdbcStatementCancel。

参数

[in]	statement	要执行的语句。
[out]	out	结果。如果客户端不期望结果集，则传递 NULL。
[out]	rows_affected	受影响的行数（如果已知），否则为 -1。如果客户端不想要此信息，则传递 NULL。
[out]	error	必要时返回错误消息的可选位置。

◆ AdbcStatementExecuteSchema()

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

获取查询结果集的模式，而不执行查询。

这会使任何先前的结果集无效。

根据驱动程序的不同，这可能需要首先执行 AdbcStatementPrepare。

自: ADBC API 修订版 1.1.0

参数

[in]	statement	要执行的语句。
[out]	schema	结果模式。
[out]	error	必要时返回错误消息的可选位置。

返回值: 如果驱动程序不支持此功能，则返回 ADBC_STATUS_NOT_IMPLEMENTED。

◆ AdbcStatementGetOption()

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

获取语句的字符串选项。

这必须始终是线程安全的（其他操作不是），但鉴于此处的语义，不建议同时调用 GetOption 本身。

必须提供 length，并且必须是由 value 指向的缓冲区的大小。如果有足够的空间，驱动程序会将选项值（包括 null 终止符）复制到缓冲区，并将 length 设置为实际值的大小。如果缓冲区太小，则不会写入任何数据，并且 length 将设置为所需的长度。

换句话说

如果输出 length <= 输入 length，则 value 将包含一个带有 length 字节的值。
如果输出 length > 输入 length，则没有任何内容写入到 value。

对于标准选项，驱动程序必须始终支持通过选项中指定的类型获取选项值（如果它们完全支持获取选项值）。（例如，通过 SetOptionDouble 设置的选项必须可以通过 GetOptionDouble 检索。）如果需要，驱动程序还可以支持通过其他 getter 获取转换后的选项值。（例如，获取双精度浮点数选项的字符串表示形式。）

自: ADBC API 修订版 1.1.0

参数

[in]	statement	语句。
[in]	key	要获取的选项。
[out]	value	选项值。
[in,out]	length	value 的长度。
[out]	error	必要时返回错误消息的可选位置。

返回值: 如果未识别该选项，则返回 ADBC_STATUS_NOT_FOUND。

◆ AdbcStatementGetOptionBytes()

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

获取语句的字节串选项。

这必须始终是线程安全的（其他操作不是），但鉴于此处的语义，不建议同时调用 GetOptionBytes 本身。

必须提供 length，并且它必须是指向 value 的缓冲区的大小。如果空间足够，驱动程序会将选项值复制到缓冲区，并将 length 设置为实际值的大小。如果缓冲区太小，则不会写入任何数据，并且 length 将设置为所需的长度。

换句话说

如果输出 length <= 输入 length，则 value 将包含一个带有 length 字节的值。
如果输出 length > 输入 length，则没有任何内容写入到 value。

对于标准选项，驱动程序必须始终支持通过选项中指定的类型获取选项值（如果它们完全支持获取选项值）。（例如，通过 SetOptionDouble 设置的选项必须可以通过 GetOptionDouble 检索。）如果需要，驱动程序还可以支持通过其他 getter 获取转换后的选项值。（例如，获取双精度浮点数选项的字符串表示形式。）

自: ADBC API 修订版 1.1.0

参数

[in]	statement	语句。
[in]	key	要获取的选项。
[out]	value	选项值。
[in,out]	length	选项值的长度。
[out]	error	必要时返回错误消息的可选位置。

返回值: 如果未识别该选项，则返回 ADBC_STATUS_NOT_FOUND。

◆ AdbcStatementGetOptionDouble()

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

获取语句的双精度浮点数选项。

这必须始终是线程安全的（其他操作则不是）。

对于标准选项，驱动程序必须始终支持通过选项中指定的类型获取选项值（如果它们完全支持获取选项值）。（例如，通过 SetOptionDouble 设置的选项必须可以通过 GetOptionDouble 检索。）如果需要，驱动程序还可以支持通过其他 getter 获取转换后的选项值。（例如，获取双精度浮点数选项的字符串表示形式。）

自: ADBC API 修订版 1.1.0

参数

[in]	statement	语句。
[in]	key	要获取的选项。
[out]	value	选项值。
[out]	error	必要时返回错误消息的可选位置。

返回值: 如果未识别该选项，则返回 ADBC_STATUS_NOT_FOUND。

◆ AdbcStatementGetOptionInt()

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

获取语句的整数选项。

这必须始终是线程安全的（其他操作则不是）。

对于标准选项，驱动程序必须始终支持通过选项中指定的类型获取选项值（如果它们完全支持获取选项值）。（例如，通过 SetOptionDouble 设置的选项必须可以通过 GetOptionDouble 检索。）如果需要，驱动程序还可以支持通过其他 getter 获取转换后的选项值。（例如，获取双精度浮点数选项的字符串表示形式。）

自: ADBC API 修订版 1.1.0

参数

[in]	statement	语句。
[in]	key	要获取的选项。
[out]	value	选项值。
[out]	error	必要时返回错误消息的可选位置。

返回值: 如果未识别该选项，则返回 ADBC_STATUS_NOT_FOUND。

◆ AdbcStatementGetParameterSchema()

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

获取绑定参数的模式。

这将检索一个 Arrow schema，描述参数化语句中参数的数量、名称和类型。schema 的字段应该按照参数的顺序位置排列；命名参数应该只出现一次。

如果参数没有名称，或者无法确定名称，则 schema 中相应字段的名称将为空字符串。如果无法确定类型，则相应字段的类型将为 NA (NullType)。

应该在 AdbcStatementPrepare 之后调用此函数。

返回值: 如果无法确定 schema，则返回 ADBC_STATUS_NOT_IMPLEMENTED。

◆ AdbcStatementNew()

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

为给定的连接创建一个新语句。

调用者传入一个零初始化的 AdbcStatement。

驱动程序应该分配其内部数据结构，并将 private_data 字段设置为指向新分配的结构。当调用 AdbcStatementRelease 时，应该释放该结构。

◆ AdbcStatementPrepare()

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

将此语句转换为预处理语句，以便多次执行。

这会使任何先前的结果集无效。

◆ AdbcStatementRelease()

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

销毁一个语句。

参数

[in]	statement	要释放的语句。
[out]	error	必要时返回错误消息的可选位置。

◆ AdbcStatementSetOption()

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

在语句上设置字符串选项。

参数

[in]	statement	语句。
[in]	key	要设置的选项。
[in]	value	选项值。
[out]	error	必要时返回错误消息的可选位置。

返回值: 如果该选项无法识别，则返回 ADBC_STATUS_NOT_IMPLEMENTED。

◆ AdbcStatementSetOptionBytes()

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

在语句上设置字节串选项。

自: ADBC API 修订版 1.1.0

参数

[in]	statement	语句。
[in]	key	要设置的选项。
[in]	value	选项值。
[in]	length	选项值的长度。
[out]	error	必要时返回错误消息的可选位置。

返回值: 如果选项无法识别，则返回 ADBC_STATUS_NOT_IMPLEMENTED

◆ AdbcStatementSetOptionDouble()

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

在语句上设置双精度浮点数选项。

自: ADBC API 修订版 1.1.0

参数

[in]	statement	语句。
[in]	key	要设置的选项。
[in]	value	选项值。
[out]	error	必要时返回错误消息的可选位置。

返回值: 如果选项无法识别，则返回 ADBC_STATUS_NOT_IMPLEMENTED

◆ AdbcStatementSetOptionInt()

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

在语句上设置整数选项。

自: ADBC API 修订版 1.1.0

参数

[in]	statement	语句。
[in]	key	要设置的选项。
[in]	value	选项值。
[out]	error	必要时返回错误消息的可选位置。

返回值: 如果选项无法识别，则返回 ADBC_STATUS_NOT_IMPLEMENTED

主题

类

函数

详细描述

类文档

◆ AdbcStatement

公共属性

成员数据文档

◆ private_data

◆ private_driver

函数文档

◆ AdbcStatementBind()

◆ AdbcStatementBindStream()

◆ AdbcStatementCancel()

◆ AdbcStatementExecuteQuery()

◆ AdbcStatementExecuteSchema()

◆ AdbcStatementGetOption()

◆ AdbcStatementGetOptionBytes()

◆ AdbcStatementGetOptionDouble()

◆ AdbcStatementGetOptionInt()

◆ AdbcStatementGetParameterSchema()

◆ AdbcStatementNew()

◆ AdbcStatementPrepare()

◆ AdbcStatementRelease()

◆ AdbcStatementSetOption()

◆ AdbcStatementSetOptionBytes()

◆ AdbcStatementSetOptionDouble()

◆ AdbcStatementSetOptionInt()