PostgreSQL 16 文档: SPI_execute_plan_extended

SPI_execute_plan_extended
上一个	向上	47.1. 接口函数	主页	下一个

SPI_execute_plan_extended

SPI_execute_plan_extended — 执行由 SPI_prepare 准备的语句

概要

int SPI_execute_plan_extended(SPIPlanPtr plan,
                              const SPIExecuteOptions * options)

说明

SPI_execute_plan_extended 执行由 SPI_prepare 或其同级函数准备的语句。此函数等同于 SPI_execute_plan，不同之处在于以不同的方式呈现要传递给查询的参数值的信息，并且可以传递额外的执行控制选项。

查询参数值由 ParamListInfo 结构表示，这便于传递已采用该格式的值。还可以通过 ParamListInfo 中指定的挂钩函数使用动态参数集。

此外，不必总是将结果元组累积到 SPI_tuptable 结构中，而可以将元组传递给调用方提供的 DestReceiver 对象，因为它们是由执行器生成的。这对可能生成许多元组的查询特别有用，因为可以实时处理数据，而不是在内存中累积数据。

参数

SPIPlanPtr plan: 已准备的语句（由 SPI_prepare 返回）
const SPIExecuteOptions * options: 包含可选参数的结构

调用方应始终将整个 options 结构体清零，然后填充他们想要设置的任何字段。这确保了代码的前向兼容性，因为将来添加到结构体中的任何字段都将被定义为在为零时向后兼容。当前可用的 options 字段为

ParamListInfo params: 包含查询参数类型和值的数据结构；如果无，则为 NULL
bool read_only: true 表示只读执行
bool allow_nonatomic: true 允许对 CALL 和 DO 语句进行非原子执行
bool must_return_tuples: 如果为 true，则在查询不是返回元组的类型时引发错误（这并不禁止它碰巧返回零个元组的情况）
uint64 tcount: 要返回的最大行数，或 0 表示无限制
DestReceiver * dest: DestReceiver 对象，它将接收查询发出的任何元组；如果为 NULL，则结果元组将累积到 SPI_tuptable 结构体中，如 SPI_execute_plan 中所示
ResourceOwner owner: 在执行计划时将持有其引用计数的资源所有者。如果为 NULL，则使用 CurrentResourceOwner。对于未保存的计划，将忽略此项，因为 SPI 不会获取这些计划的引用计数。

返回值

返回值与 SPI_execute_plan 相同。

当 options->dest 为 NULL 时，SPI_processed 和 SPI_tuptable 的设置与 SPI_execute_plan 中相同。当 options->dest 不为 NULL 时，SPI_processed 设置为零，SPI_tuptable 设置为 NULL。如果需要元组计数，则调用方的 DestReceiver 对象必须计算它。