PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗

SPI_execute_extended

SPI_execute_extended — 执行带行外参数的命令

Synopsis

int SPI_execute_extended(const char *command,
                         const SPIExecuteOptions * options)

描述

SPI_execute_extended 执行一条可能包含对 外部提供的参数的引用的命令。 命令文本以 $n 引用一个参数, options->params 对象 (如果提供)为每个这样的符号提供值和类型信息。 各种执行选项也可以在 options 结构中指定。

options->params 对象通常应当把每个 参数标记为 PARAM_FLAG_CONST 标志, 因为查询总是使用一次性计划。

如果 options->dest 不是 NULL, 结果元组会在执行器生成它们时被传给那个对象, 而不是被累积在 SPI_tuptable 中。 使用调用者提供的 DestReceiver 对象对可能生成许多元组的查询 特别有帮助,因为数据可以被即时处理而不必在内存中 累积。

参数

const char * command

命令字符串

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_execute 中那样被累积到一个 SPI_tuptable 结构中

ResourceOwner owner

这个字段是为了与 SPI_execute_plan_extended 保持一致而 存在的,但它会被忽略,因为 SPI_execute_extended 使用的计划永远不会 被保存。

返回值

返回值与 SPI_execute 相同。

当 options->dest 为 NULL 时, SPI_processed 和 SPI_tuptable 的设置方式与 SPI_execute 相同。 当 options->dest 不为 NULL 时, SPI_processed 被设为零, SPI_tuptable 被设为 NULL。 如果需要元组计数,调用者的 DestReceiver 对象必须自行计算。