PostgreSQL 17 文档: SPI_execute_plan_extended

SPI_execute_plan_extended
上一个	向上	45.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 语句（但此字段在未将 SPI_OPT_NONATOMIC 标志传递给 SPI_connect_ext 时将被忽略）
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 对象必须对其进行计算。