8000 Fix SPI documentation for new handling of ExecutorRun's count parameter. · danielcode/postgres@ecfd994 · GitHub 10000
[go: up one dir, main page]
Skip to content

Commit ecfd994

Browse files
tglsfdctglsfdc
committed
Fix SPI documentation for new handling of ExecutorRun's count parameter.
Since 9.0, the count parameter has only limited the number of tuples actually returned by the executor. It doesn't affect the behavior of INSERT/UPDATE/DELETE unless RETURNING is specified, because without RETURNING, the ModifyTable plan node doesn't return control to execMain.c for each tuple. And we only check the limit at the top level. While this behavioral change was unintentional at the time, discussion of bug #6572 led us to the conclusion that we prefer the new behavior anyway, and so we should just adjust the docs to match rather than change the code. Accordingly, do that. Back-patch as far as 9.0 so that the docs match the code in each branch.
1 parent 6c77ce3 commit ecfd994

File tree

2 files changed

+29
-18
lines changed

2 files changed

+29
-18
lines changed

‎doc/src/sgml/spi.sgml‎

Lines changed: 25 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -316,20 +316,32 @@ int SPI_execute(const char * <parameter>command</parameter>, bool <parameter>rea
316316
<para>
317317
If <parameter>count</parameter> is zero then the command is executed
318318
for all rows that it applies to. If <parameter>count</parameter>
319-
is greater than 0, then the number of rows for which the command
320-
will be executed is restricted (much like a
321-
<literal>LIMIT</literal> clause). For example:
319+
is greater than zero, then no more than <parameter>count</parameter> rows
320+
will be retrieved; execution stops when the count is reached, much like
321+
adding a <literal>LIMIT</literal> clause to the query. For example,
322+
<programlisting>
323+
SPI_execute("SELECT * FROM foo", true, 5);
324+
</programlisting>
325+
will retrieve at most 5 rows from the table. Note that such a limit
326+
is only effective when the command actually returns rows. For example,
322327
<programlisting>
323328
SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);
324329
</programlisting>
325-
will allow at most 5 rows to be inserted into the table.
330+
inserts all rows from <structname>bar</>, ignoring the
331+
<parameter>count</parameter> parameter. However, with
332+
<programlisting>
333+
SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);
334+
</programlisting>
335+
at most 5 rows would be inserted, since execution would stop after the
336+
fifth <literal>RETURNING</> result row is retrieved.
326337
</para>
327338

328339
<para>
329340
You can pass multiple commands in one string;
330341
<function>SPI_execute</function> returns the
331342
result for the command executed last. The <parameter>count</parameter>
332-
limit applies to each command separately, but it is not applied to
343+
limit applies to each command separately (even though only the last
344+
result will actually be returned). The limit is not applied to any
333345
hidden commands generated by rules.
334346
</para>
335347

@@ -431,7 +443,7 @@ typedef struct
431443
<term><literal>long <parameter>count</parameter></literal></term>
432444
<listitem>
433445
<para>
434-
maximum number of rows to process or return,
446+
maximum number of rows to return,
435447
or <literal>0</> for no limit
436448
</para>
437449
</listitem>
@@ -608,15 +620,12 @@ typedef struct
608620
<title>Notes</title>
609621

610622
<para>
611-
The functions <function>SPI_execute</function>,
612-
<function>SPI_exec</function>,
613-
<function>SPI_execute_plan</function>, and
614-
<function>SPI_execp</function> change both
623+
All SPI query-execution functions set both
615624
<varname>SPI_processed</varname> and
616625
<varname>SPI_tuptable</varname> (just the pointer, not the contents
617626
of the structure). Save these two global variables into local
618627
procedure variables if you need to access the result table of
619-
<function>SPI_execute</function> or a related function
628+
<function>SPI_execute</function> or another query-execution function
620629
across later calls.
621630
</para>
622631
</refsect1>
@@ -671,7 +680,7 @@ int SPI_exec(const char * <parameter>command</parameter>, long <parameter>count<
671680
<term><literal>long <parameter>count</parameter></literal></term>
672681
<listitem>
673682
<para>
674-
maximum number of rows to process or return,
683+
maximum number of rows to return,
675684
or <literal>0</> for no limit
676685
</para>
677686
</listitem>
@@ -810,7 +819,7 @@ int SPI_execute_with_args(const char *<parameter>command</parameter>,
810819
<term><literal>long <parameter>count</parameter></literal></term>
811820
<listitem>
812821
<para>
813-
maximum number of rows to process or return,
822+
maximum number of rows to return,
814823
or <literal>0</> for no limit
815824
</para>
816825
</listitem>
@@ -1454,7 +1463,7 @@ int SPI_execute_plan(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>
14541463
<term><literal>long <parameter>count</parameter></literal></term>
14551464
<listitem>
14561465
<para>
1457-
maximum number of rows to process or return,
1466+
maximum number of rows to return,
14581467
or <literal>0</> for no limit
14591468
</para>
14601469
</listitem>
@@ -1572,7 +1581,7 @@ int SPI_execute_plan_with_paramlist(SPIPlanPtr <parameter>plan</parameter>,
15721581
<term><literal>long <parameter>count</parameter></literal></term>
15731582
<listitem>
15741583
<para>
1575-
maximum number of rows to process or return,
1584+
maximum number of rows to return,
15761585
or <literal>0</> for no limit
15771586
</para>
15781587
</listitem>
@@ -1673,7 +1682,7 @@ int SPI_execp(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>values<
16731682
<term><literal>long <parameter>count</parameter></literal></term>
16741683
<listitem>
16751684
<para>
1676-
maximum number of rows to process or return,
1685+
maximum number of rows to return,
16771686
or <literal>0</> for no limit
16781687
</para>
16791688
</listitem>

‎src/backend/executor/execMain.c‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,9 @@ standard_ExecutorStart(QueryDesc *queryDesc, int eflags)
226226
* we retrieve up to 'count' tuples in the specified direction.
227227
*
228228
* Note: count = 0 is interpreted as no portal limit, i.e., run to
229-
* completion.
229+
* completion. Also note that the count limit is only applied to
230+
* retrieved tuples, not for instance to those inserted/updated/deleted
231+
* by a ModifyTable plan node.
230232
*
231233
* There is no return value, but output tuples (if any) are sent to
232234
* the destination receiver specified in the QueryDesc; and the number
@@ -1348,7 +1350,7 @@ ExecEndPlan(PlanState *planstate, EState *estate)
13481350
/* ----------------------------------------------------------------
13491351
* ExecutePlan
13501352
*
1351-
* Processes the query plan until we have processed 'numberTuples' tuples,
1353+
* Processes the query plan until we have retrieved 'numberTuples' tuples,
13521354
* moving in the specified direction.
13531355
*
13541356
* Runs to completion if numberTuples is 0

0 commit comments

Comments
 (0)
0