From: Tom Lane Date: Thu, 24 Jan 2013 23:34:00 +0000 (-0500) Subject: Fix SPI documentation for new handling of ExecutorRun's count parameter. X-Git-Tag: REL9_3_BETA1~437 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2ddc600f8f0252a0864e85d5cc1eeb3b9687d7e9;p=postgresql 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. --- diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml index 9668766413..13391689c7 100644 --- a/doc/src/sgml/spi.sgml +++ b/doc/src/sgml/spi.sgml @@ -316,20 +316,32 @@ 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. You can pass multiple commands in one string; 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. @@ -434,7 +446,7 @@ 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 +623,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 +683,7 @@ 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 +822,7 @@ 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 @@ -1457,7 +1466,7 @@ 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 @@ -1575,7 +1584,7 @@ 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 @@ -1676,7 +1685,7 @@ 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 23a6a61256..e39911f16b 100644 --- a/src/backend/executor/execMain.c +++ b/src/backend/executor/execMain.c @@ -228,7 +228,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 @@ -1358,7 +1360,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