2025年9月25日: PostgreSQL 18 釋出!
支援版本: 當前 (18) / 17 / 16 / 15 / 14
開發版本: devel

SPI_execute_extended

SPI_execute_extended — 使用外部引數執行命令

概要

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,那麼結果行(tuples)將在生成時傳遞給該物件,而不是累積在 SPI_tuptable 中。使用呼叫者提供的 DestReceiver 物件對於可能生成許多行的查詢特別有用,因為資料可以即時處理,而不是累積在記憶體中。

引數

const char * command

command string

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 相同

ResourceOwner owner

此欄位是為了與 SPI_execute_plan_extended 保持一致性而存在的,但它被忽略了,因為 SPI_execute_extended 使用的計劃永遠不會被儲存。

返回值

返回值與 SPI_execute 相同。

options->dest 為 NULL 時,SPI_processedSPI_tuptable 的設定與 SPI_execute 相同。當 options->dest 不為 NULL 時,SPI_processed 被設定為零,SPI_tuptable 被設定為 NULL。如果需要行計數,呼叫者的 DestReceiver 物件必須計算它。

提交更正

如果您在文件中發現任何不正確、與您對特定功能的體驗不符或需要進一步澄清的內容,請使用 此表單 報告文件問題。