diff options
| -rw-r--r-- | doc/src/sgml/spi.sgml | 41 | ||||
| -rw-r--r-- | src/backend/executor/execMain.c | 6 |
2 files changed, 29 insertions, 18 deletions
diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml index ea6bfc2a3f5..5232e001b8a 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 440438b1807..56be2a78d81 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 |