1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SPI_execute_plan_extended</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-execute-plan.html" title="SPI_execute_plan" /><link rel="next" href="spi-spi-execute-plan-with-paramlist.html" title="SPI_execute_plan_with_paramlist" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_execute_plan_extended</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-execute-plan.html" title="SPI_execute_plan">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-execute-plan-with-paramlist.html" title="SPI_execute_plan_with_paramlist">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-EXECUTE-PLAN-EXTENDED"><div class="titlepage"></div><a id="id-1.8.12.8.16.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_execute_plan_extended</span></h2><p>SPI_execute_plan_extended — execute a statement prepared by <code class="function">SPI_prepare</code></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
int SPI_execute_plan_extended(SPIPlanPtr <em class="parameter"><code>plan</code></em>,
const SPIExecuteOptions * <em class="parameter"><code>options</code></em>)
</pre></div><div class="refsect1" id="id-1.8.12.8.16.5"><h2>Description</h2><p>
<code class="function">SPI_execute_plan_extended</code> executes a statement
prepared by <code class="function">SPI_prepare</code> or one of its siblings.
This function is equivalent to <code class="function">SPI_execute_plan</code>,
except that information about the parameter values to be passed to the
query is presented differently, and additional execution-controlling
options can be passed.
</p><p>
Query parameter values are represented by
a <code class="literal">ParamListInfo</code> 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 <code class="literal">ParamListInfo</code>.
</p><p>
Also, instead of always accumulating the result tuples into a
<code class="varname">SPI_tuptable</code> structure, tuples can be passed to a
caller-supplied <code class="literal">DestReceiver</code> 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.
</p></div><div class="refsect1" id="id-1.8.12.8.16.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>
prepared statement (returned by <code class="function">SPI_prepare</code>)
</p></dd><dt><span class="term"><code class="literal">const SPIExecuteOptions * <em class="parameter"><code>options</code></em></code></span></dt><dd><p>
struct containing optional arguments
</p></dd></dl></div><p>
Callers should always zero out the entire <em class="parameter"><code>options</code></em>
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 <em class="parameter"><code>options</code></em> fields are:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ParamListInfo <em class="parameter"><code>params</code></em></code></span></dt><dd><p>
data structure containing query parameter types and values; NULL if none
</p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>allow_nonatomic</code></em></code></span></dt><dd><p>
<code class="literal">true</code> allows non-atomic execution of CALL and DO
statements
</p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>must_return_tuples</code></em></code></span></dt><dd><p>
if <code class="literal">true</code>, 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)
</p></dd><dt><span class="term"><code class="literal">uint64 <em class="parameter"><code>tcount</code></em></code></span></dt><dd><p>
maximum number of rows to return,
or <code class="literal">0</code> for no limit
</p></dd><dt><span class="term"><code class="literal">DestReceiver * <em class="parameter"><code>dest</code></em></code></span></dt><dd><p>
<code class="literal">DestReceiver</code> object that will receive any tuples
emitted by the query; if NULL, result tuples are accumulated into
a <code class="varname">SPI_tuptable</code> structure, as
in <code class="function">SPI_execute_plan</code>
</p></dd><dt><span class="term"><code class="literal">ResourceOwner <em class="parameter"><code>owner</code></em></code></span></dt><dd><p>
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.
</p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.16.7"><h2>Return Value</h2><p>
The return value is the same as for <code class="function">SPI_execute_plan</code>.
</p><p>
When <em class="parameter"><code>options->dest</code></em> is NULL,
<code class="varname">SPI_processed</code> and
<code class="varname">SPI_tuptable</code> are set as in
<code class="function">SPI_execute_plan</code>.
When <em class="parameter"><code>options->dest</code></em> is not NULL,
<code class="varname">SPI_processed</code> is set to zero and
<code class="varname">SPI_tuptable</code> is set to NULL. If a tuple count
is required, the caller's <code class="literal">DestReceiver</code> object must
calculate it.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-execute-plan.html" title="SPI_execute_plan">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-execute-plan-with-paramlist.html" title="SPI_execute_plan_with_paramlist">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_execute_plan </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_execute_plan_with_paramlist</td></tr></table></div></body></html>
|
