diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
index 033e2249096..2d0a4addbfd 100644
--- a/doc/src/sgml/spi.sgml
+++ b/doc/src/sgml/spi.sgml
@@ -316,13 +316,24 @@ int SPI_execute(const char * command, bool rea
If count is zero then the command is executed
for all rows that it applies to. If count
- is greater than 0, then the number of rows for which the command
- will be executed is restricted (much like a
- LIMIT clause). For example:
+ is greater than zero, then no more than count rows
+ will be retrieved; execution stops when the count is reached, much like
+ adding a LIMIT clause to the query. For example,
+
+SPI_execute("SELECT * FROM foo", true, 5);
+
+ 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,
SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);
- will allow at most 5 rows to be inserted into the table.
+ inserts all rows from bar, ignoring the
+ count parameter. However, with
+
+SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);
+
+ at most 5 rows would be inserted, since execution would stop after the
+ fifth RETURNING result row is retrieved.
@@ -331,7 +342,8 @@ SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);
whole string will be parsed and planned before execution begins.
SPI_execute returns the
result for the command executed last. The count
- 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.
@@ -435,7 +447,8 @@ typedef struct
long count
- maximum number of rows to process or return
+ maximum number of rows to return,
+ or 0 for no limit
@@ -611,15 +624,12 @@ typedef struct
Notes
- The functions SPI_execute,
- SPI_exec,
- SPI_execute_plan, and
- SPI_execp change both
+ All SPI query-execution functions set both
SPI_processed and
SPI_tuptable (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
- SPI_execute or a related function
+ SPI_execute or another query-execution function
across later calls.
@@ -674,7 +684,8 @@ int SPI_exec(const char * command, long count<
long count
- maximum number of rows to process or return
+ maximum number of rows to return,
+ or 0 for no limit
@@ -813,7 +824,8 @@ int SPI_execute_with_args(const char *command,
long count
- maximum number of rows to process or return
+ maximum number of rows to return,
+ or 0 for no limit
@@ -1431,7 +1443,8 @@ int SPI_execute_plan(SPIPlanPtr plan, Datum *
long count
- maximum number of rows to process or return
+ maximum number of rows to return,
+ or 0 for no limit
@@ -1550,7 +1563,8 @@ int SPI_execute_plan_with_paramlist(SPIPlanPtr plan,
long count
- maximum number of rows to process or return
+ maximum number of rows to return,
+ or 0 for no limit
@@ -1650,7 +1664,8 @@ int SPI_execp(SPIPlanPtr plan, Datum * values<
long count
- maximum number of rows to process or return
+ maximum number of rows to return,
+ or 0 for no limit
diff --git a/src/backend/executor/execMain.c b/src/backend/executor/execMain.c
index 657a778290a..35fa55be377 100644
--- a/src/backend/executor/execMain.c
+++ b/src/backend/executor/execMain.c
@@ -207,7 +207,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
@@ -1184,7 +1186,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