EVOLUTION-MANAGER

Edit File: SPI_execute_plan_extended.3

'\" t .\" Title: SPI_execute_plan_extended .\" Author: The PostgreSQL Global Development Group .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> .\" Date: 2025 .\" Manual: PostgreSQL 14.18 Documentation .\" Source: PostgreSQL 14.18 .\" Language: English .\" .TH "SPI_EXECUTE_PLAN_EXTENDED" "3" "2025" "PostgreSQL 14.18" "PostgreSQL 14.18 Documentation" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" SPI_execute_plan_extended \- execute a statement prepared by \fBSPI_prepare\fR .SH "SYNOPSIS" .sp .nf int SPI_execute_plan_extended(SPIPlanPtr \fIplan\fR, const SPIExecuteOptions * \fIoptions\fR) .fi .SH "DESCRIPTION" .PP \fBSPI_execute_plan_extended\fR executes a statement prepared by \fBSPI_prepare\fR or one of its siblings\&. This function is equivalent to \fBSPI_execute_plan\fR, except that information about the parameter values to be passed to the query is presented differently, and additional execution\-controlling options can be passed\&. .PP Query parameter values are represented by a ParamListInfo struct, which is convenient for passing down values that are already available in that format\&. Dynamic parameter sets can also be used, via hook functions specified in ParamListInfo\&. .PP Also, instead of always accumulating the result tuples into a \fISPI_tuptable\fR structure, tuples can be passed to a caller\-supplied DestReceiver object as they are generated by the executor\&. This is particularly helpful for queries that might generate many tuples, since the data can be processed on\-the\-fly instead of being accumulated in memory\&. .SH "ARGUMENTS" .PP SPIPlanPtr \fIplan\fR .RS 4 prepared statement (returned by \fBSPI_prepare\fR) .RE .PP const SPIExecuteOptions * \fIoptions\fR .RS 4 struct containing optional arguments .RE .PP Callers should always zero out the entire \fIoptions\fR struct, then fill whichever fields they want to set\&. This ensures forward compatibility of code, since any fields that are added to the struct in future will be defined to behave backwards\-compatibly if they are zero\&. The currently available \fIoptions\fR fields are: .PP ParamListInfo \fIparams\fR .RS 4 data structure containing query parameter types and values; NULL if none .RE .PP bool \fIread_only\fR .RS 4 true for read\-only execution .RE .PP bool \fIallow_nonatomic\fR .RS 4 true allows non\-atomic execution of CALL and DO statements (but this field is ignored unless the SPI_OPT_NONATOMIC flag was passed to \fBSPI_connect_ext\fR) .RE .PP bool \fImust_return_tuples\fR .RS 4 if true, raise error if the query is not of a kind that returns tuples (this does not forbid the case where it happens to return zero tuples) .RE .PP uint64 \fItcount\fR .RS 4 maximum number of rows to return, or 0 for no limit .RE .PP DestReceiver * \fIdest\fR .RS 4 DestReceiver object that will receive any tuples emitted by the query; if NULL, result tuples are accumulated into a \fISPI_tuptable\fR structure, as in \fBSPI_execute_plan\fR .RE .PP ResourceOwner \fIowner\fR .RS 4 The resource owner that will hold a reference count on the plan while it is executed\&. If NULL, CurrentResourceOwner is used\&. Ignored for non\-saved plans, as SPI does not acquire reference counts on those\&. .RE .SH "RETURN VALUE" .PP The return value is the same as for \fBSPI_execute_plan\fR\&. .PP When \fIoptions\->dest\fR is NULL, \fISPI_processed\fR and \fISPI_tuptable\fR are set as in \fBSPI_execute_plan\fR\&. When \fIoptions\->dest\fR is not NULL, \fISPI_processed\fR is set to zero and \fISPI_tuptable\fR is set to NULL\&. If a tuple count is required, the caller\*(Aqs DestReceiver object must calculate it\&.