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

   1 '\" t
   2 .\"     Title: SPI_execute_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_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_extended \- execute a command with out\-of\-line parameters
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 int SPI_execute_extended(const char *\fIcommand\fR,
  36                          const SPIExecuteOptions * \fIoptions\fR)
  37 .fi
  38 .SH "DESCRIPTION"
  39 .PP
  40 \fBSPI_execute_extended\fR
  41 executes a command that might include references to externally supplied parameters\&. The command text refers to a parameter as
  42 $\fIn\fR, and the
  43 \fIoptions\->params\fR
  44 object (if supplied) provides values and type information for each such symbol\&. Various execution options can be specified in the
  45 \fIoptions\fR
  46 struct, too\&.
  47 .PP
  48 The
  49 \fIoptions\->params\fR
  50 object should normally mark each parameter with the
  51 PARAM_FLAG_CONST
  52 flag, since a one\-shot plan is always used for the query\&.
  53 .PP
  54 If
  55 \fIoptions\->dest\fR
  56 is not NULL, then result tuples are passed to that object as they are generated by the executor, instead of being accumulated in
  57 \fISPI_tuptable\fR\&. Using a caller\-supplied
  58 DestReceiver
  59 object 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\&.
  60 .SH "ARGUMENTS"
  61 .PP
  62 const char * \fIcommand\fR
  63 .RS 4
  64 command string
  65 .RE
  66 .PP
  67 const SPIExecuteOptions * \fIoptions\fR
  68 .RS 4
  69 struct containing optional arguments
  70 .RE
  71 .PP
  72 Callers should always zero out the entire
  73 \fIoptions\fR
  74 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
  75 \fIoptions\fR
  76 fields are:
  77 .PP
  78 ParamListInfo \fIparams\fR
  79 .RS 4
  80 data structure containing query parameter types and values; NULL if none
  81 .RE
  82 .PP
  83 bool \fIread_only\fR
  84 .RS 4
  85 true
  86 for read\-only execution
  87 .RE
  88 .PP
  89 bool \fIallow_nonatomic\fR
  90 .RS 4
  91 true
  92 allows non\-atomic execution of CALL and DO statements (but this field is ignored unless the
  93 SPI_OPT_NONATOMIC
  94 flag was passed to
  95 \fBSPI_connect_ext\fR)
  96 .RE
  97 .PP
  98 bool \fImust_return_tuples\fR
  99 .RS 4
 100 if
 101 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)
 102 .RE
 103 .PP
 104 uint64 \fItcount\fR
 105 .RS 4
 106 maximum number of rows to return, or
 107 0
 108 for no limit
 109 .RE
 110 .PP
 111 DestReceiver * \fIdest\fR
 112 .RS 4
 113 DestReceiver
 114 object that will receive any tuples emitted by the query; if NULL, result tuples are accumulated into a
 115 \fISPI_tuptable\fR
 116 structure, as in
 117 \fBSPI_execute\fR
 118 .RE
 119 .PP
 120 ResourceOwner \fIowner\fR
 121 .RS 4
 122 This field is present for consistency with
 123 \fBSPI_execute_plan_extended\fR, but it is ignored, since the plan used by
 124 \fBSPI_execute_extended\fR
 125 is never saved\&.
 126 .RE
 127 .SH "RETURN VALUE"
 128 .PP
 129 The return value is the same as for
 130 \fBSPI_execute\fR\&.
 131 .PP
 132 When
 133 \fIoptions\->dest\fR
 134 is NULL,
 135 \fISPI_processed\fR
 136 and
 137 \fISPI_tuptable\fR
 138 are set as in
 139 \fBSPI_execute\fR\&. When
 140 \fIoptions\->dest\fR
 141 is not NULL,
 142 \fISPI_processed\fR
 143 is set to zero and
 144 \fISPI_tuptable\fR
 145 is set to NULL\&. If a tuple count is required, the caller\*(Aqs
 146 DestReceiver
 147 object must calculate it\&.