diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
index 1b41cb40b3c..7a61802eb22 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.
@@ -432,7 +444,8 @@ typedef struct
long count
- maximum number of rows to process or return
+ maximum number of rows to return,
+ or 0 for no limit
@@ -608,15 +621,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.
@@ -671,7 +681,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
@@ -808,7 +819,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
@@ -1424,7 +1436,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
@@ -1541,7 +1554,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
@@ -1641,7 +1655,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 8a43db7d6ab..5139c3b8e50 100644
--- a/src/backend/executor/execMain.c
+++ b/src/backend/executor/execMain.c
@@ -239,7 +239,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
@@ -1395,7 +1397,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