1SPI_EXECUTE_EXTENDED(3)  PostgreSQL 15.4 Documentation SPI_EXECUTE_EXTENDED(3)
2
3
4

NAME

6       SPI_execute_extended - execute a command with out-of-line parameters
7

SYNOPSIS

9       int SPI_execute_extended(const char *command,
10                                const SPIExecuteOptions * options)
11

DESCRIPTION

13       SPI_execute_extended executes a command that might include references
14       to externally supplied parameters. The command text refers to a
15       parameter as $n, and the options->params object (if supplied) provides
16       values and type information for each such symbol. Various execution
17       options can be specified in the options struct, too.
18
19       The options->params object should normally mark each parameter with the
20       PARAM_FLAG_CONST flag, since a one-shot plan is always used for the
21       query.
22
23       If options->dest is not NULL, then result tuples are passed to that
24       object as they are generated by the executor, instead of being
25       accumulated in SPI_tuptable. Using a caller-supplied DestReceiver
26       object is particularly helpful for queries that might generate many
27       tuples, since the data can be processed on-the-fly instead of being
28       accumulated in memory.
29

ARGUMENTS

31       const char * command
32           command string
33
34       const SPIExecuteOptions * options
35           struct containing optional arguments
36
37       Callers should always zero out the entire options struct, then fill
38       whichever fields they want to set. This ensures forward compatibility
39       of code, since any fields that are added to the struct in future will
40       be defined to behave backwards-compatibly if they are zero. The
41       currently available options fields are:
42
43       ParamListInfo params
44           data structure containing query parameter types and values; NULL if
45           none
46
47       bool read_only
48           true for read-only execution
49
50       bool allow_nonatomic
51           true allows non-atomic execution of CALL and DO statements
52
53       bool must_return_tuples
54           if true, raise error if the query is not of a kind that returns
55           tuples (this does not forbid the case where it happens to return
56           zero tuples)
57
58       uint64 tcount
59           maximum number of rows to return, or 0 for no limit
60
61       DestReceiver * dest
62           DestReceiver object that will receive any tuples emitted by the
63           query; if NULL, result tuples are accumulated into a SPI_tuptable
64           structure, as in SPI_execute
65
66       ResourceOwner owner
67           This field is present for consistency with
68           SPI_execute_plan_extended, but it is ignored, since the plan used
69           by SPI_execute_extended is never saved.
70

RETURN VALUE

72       The return value is the same as for SPI_execute.
73
74       When options->dest is NULL, SPI_processed and SPI_tuptable are set as
75       in SPI_execute. When options->dest is not NULL, SPI_processed is set to
76       zero and SPI_tuptable is set to NULL. If a tuple count is required, the
77       caller's DestReceiver object must calculate it.
78
79
80
81PostgreSQL 15.4                      2023              SPI_EXECUTE_EXTENDED(3)
Impressum