diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
index ea6bfc2a3f53b082e47de3c55ea3309c3799b378..5232e001b8af7ee65a0bb5dfcc3ec5ff4945e733 100644
--- a/doc/src/sgml/spi.sgml
+++ b/doc/src/sgml/spi.sgml
@@ -316,20 +316,32 @@ int SPI_execute(const char * <parameter>command</parameter>, bool <parameter>rea
<para>
If <parameter>count</parameter> is zero then the command is executed
for all rows that it applies to. If <parameter>count</parameter>
- is greater than 0, then the number of rows for which the command
- will be executed is restricted (much like a
- <literal>LIMIT</literal> clause). For example:
+ is greater than zero, then no more than <parameter>count</parameter> rows
+ will be retrieved; execution stops when the count is reached, much like
+ adding a <literal>LIMIT</literal> clause to the query. For example,
+<programlisting>
+SPI_execute("SELECT * FROM foo", true, 5);
+</programlisting>
+ will retrieve at most 5 rows from the table. Note that such a limit
+ is only effective when the command actually returns rows. For example,
<programlisting>
SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);
</programlisting>
- will allow at most 5 rows to be inserted into the table.
+ inserts all rows from <structname>bar</>, ignoring the
+ <parameter>count</parameter> parameter. However, with
+<programlisting>
+SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);
+</programlisting>
+ at most 5 rows would be inserted, since execution would stop after the
+ fifth <literal>RETURNING</> result row is retrieved.
</para>
<para>
You can pass multiple commands in one string;
<function>SPI_execute</function> returns the
result for the command executed last. The <parameter>count</parameter>
- limit applies to each command separately, but it is not applied to
+ limit applies to each command separately (even though only the last
+ result will actually be returned). The limit is not applied to any
hidden commands generated by rules.
</para>
@@ -431,7 +443,7 @@ typedef struct
<term><literal>long <parameter>count</parameter></literal></term>
<listitem>
<para>
- maximum number of rows to process or return,
+ maximum number of rows to return,
or <literal>0</> for no limit
</para>
</listitem>
@@ -608,15 +620,12 @@ typedef struct
<title>Notes</title>
<para>
- The functions <function>SPI_execute</function>,
- <function>SPI_exec</function>,
- <function>SPI_execute_plan</function>, and
- <function>SPI_execp</function> change both
+ All SPI query-execution functions set both
<varname>SPI_processed</varname> and
<varname>SPI_tuptable</varname> (just the pointer, not the contents
of the structure). Save these two global variables into local
procedure variables if you need to access the result table of
- <function>SPI_execute</function> or a related function
+ <function>SPI_execute</function> or another query-execution function
across later calls.
</para>
</refsect1>
@@ -671,7 +680,7 @@ int SPI_exec(const char * <parameter>command</parameter>, long <parameter>count<
<term><literal>long <parameter>count</parameter></literal></term>
<listitem>
<para>
- maximum number of rows to process or return,
+ maximum number of rows to return,
or <literal>0</> for no limit
</para>
</listitem>
@@ -810,7 +819,7 @@ int SPI_execute_with_args(const char *<parameter>command</parameter>,
<term><literal>long <parameter>count</parameter></literal></term>
<listitem>
<para>
- maximum number of rows to process or return,
+ maximum number of rows to return,
or <literal>0</> for no limit
</para>
</listitem>
@@ -1454,7 +1463,7 @@ int SPI_execute_plan(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>
<term><literal>long <parameter>count</parameter></literal></term>
<listitem>
<para>
- maximum number of rows to process or return,
+ maximum number of rows to return,
or <literal>0</> for no limit
</para>
</listitem>
@@ -1572,7 +1581,7 @@ int SPI_execute_plan_with_paramlist(SPIPlanPtr <parameter>plan</parameter>,
<term><literal>long <parameter>count</parameter></literal></term>
<listitem>
<para>
- maximum number of rows to process or return,
+ maximum number of rows to return,
or <literal>0</> for no limit
</para>
</listitem>
@@ -1673,7 +1682,7 @@ int SPI_execp(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>values<
<term><literal>long <parameter>count</parameter></literal></term>
<listitem>
<para>
- maximum number of rows to process or return,
+ maximum number of rows to return,
or <literal>0</> for no limit
</para>
</listitem>
diff --git a/src/backend/executor/execMain.c b/src/backend/executor/execMain.c
index 440438b1807ef684ca56f094108f465bda1e55c5..56be2a78d81c82c4308c5115639d533b6ddf50aa 100644
--- a/src/backend/executor/execMain.c
+++ b/src/backend/executor/execMain.c
@@ -226,7 +226,9 @@ standard_ExecutorStart(QueryDesc *queryDesc, int eflags)
* we retrieve up to 'count' tuples in the specified direction.
*
* Note: count = 0 is interpreted as no portal limit, i.e., run to
- * completion.
+ * completion. Also note that the count limit is only applied to
+ * retrieved tuples, not for instance to those inserted/updated/deleted
+ * by a ModifyTable plan node.
*
* There is no return value, but output tuples (if any) are sent to
* the destination receiver specified in the QueryDesc; and the number
@@ -1348,7 +1350,7 @@ ExecEndPlan(PlanState *planstate, EState *estate)
/* ----------------------------------------------------------------
* ExecutePlan
*
- * Processes the query plan until we have processed 'numberTuples' tuples,
+ * Processes the query plan until we have retrieved 'numberTuples' tuples,
* moving in the specified direction.
*
* Runs to completion if numberTuples is 0