begriffs open source - ai-pg/blob - full-docs/man3/SPI_execute_plan_extended.3

   1 '\" t
   2 .\"     Title: SPI_execute_plan_extended
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "SPI_EXECUTE_PLAN_EXTENDED" "3" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 SPI_execute_plan_extended \- execute a statement prepared by \fBSPI_prepare\fR
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 int SPI_execute_plan_extended(SPIPlanPtr \fIplan\fR,
  36                               const SPIExecuteOptions * \fIoptions\fR)
  37 .fi
  38 .SH "DESCRIPTION"
  39 .PP
  40 \fBSPI_execute_plan_extended\fR
  41 executes a statement prepared by
  42 \fBSPI_prepare\fR
  43 or one of its siblings\&. This function is equivalent to
  44 \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\&.
  45 .PP
  46 Query parameter values are represented by a
  47 ParamListInfo
  48 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
  49 ParamListInfo\&.
  50 .PP
  51 Also, instead of always accumulating the result tuples into a
  52 \fISPI_tuptable\fR
  53 structure, tuples can be passed to a caller\-supplied
  54 DestReceiver
  55 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\&.
  56 .SH "ARGUMENTS"
  57 .PP
  58 SPIPlanPtr \fIplan\fR
  59 .RS 4
  60 prepared statement (returned by
  61 \fBSPI_prepare\fR)
  62 .RE
  63 .PP
  64 const SPIExecuteOptions * \fIoptions\fR
  65 .RS 4
  66 struct containing optional arguments
  67 .RE
  68 .PP
  69 Callers should always zero out the entire
  70 \fIoptions\fR
  71 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
  72 \fIoptions\fR
  73 fields are:
  74 .PP
  75 ParamListInfo \fIparams\fR
  76 .RS 4
  77 data structure containing query parameter types and values; NULL if none
  78 .RE
  79 .PP
  80 bool \fIread_only\fR
  81 .RS 4
  82 true
  83 for read\-only execution
  84 .RE
  85 .PP
  86 bool \fIallow_nonatomic\fR
  87 .RS 4
  88 true
  89 allows non\-atomic execution of CALL and DO statements (but this field is ignored unless the
  90 SPI_OPT_NONATOMIC
  91 flag was passed to
  92 \fBSPI_connect_ext\fR)
  93 .RE
  94 .PP
  95 bool \fImust_return_tuples\fR
  96 .RS 4
  97 if
  98 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)
  99 .RE
 100 .PP
 101 uint64 \fItcount\fR
 102 .RS 4
 103 maximum number of rows to return, or
 104 0
 105 for no limit
 106 .RE
 107 .PP
 108 DestReceiver * \fIdest\fR
 109 .RS 4
 110 DestReceiver
 111 object that will receive any tuples emitted by the query; if NULL, result tuples are accumulated into a
 112 \fISPI_tuptable\fR
 113 structure, as in
 114 \fBSPI_execute_plan\fR
 115 .RE
 116 .PP
 117 ResourceOwner \fIowner\fR
 118 .RS 4
 119 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\&.
 120 .RE
 121 .SH "RETURN VALUE"
 122 .PP
 123 The return value is the same as for
 124 \fBSPI_execute_plan\fR\&.
 125 .PP
 126 When
 127 \fIoptions\->dest\fR
 128 is NULL,
 129 \fISPI_processed\fR
 130 and
 131 \fISPI_tuptable\fR
 132 are set as in
 133 \fBSPI_execute_plan\fR\&. When
 134 \fIoptions\->dest\fR
 135 is not NULL,
 136 \fISPI_processed\fR
 137 is set to zero and
 138 \fISPI_tuptable\fR
 139 is set to NULL\&. If a tuple count is required, the caller\*(Aqs
 140 DestReceiver
 141 object must calculate it\&.