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 * <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> @@ -331,7 +342,8 @@ SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5); whole string will be parsed and planned before execution begins. <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> @@ -435,7 +447,8 @@ 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> </varlistentry> @@ -611,15 +624,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> @@ -674,7 +684,8 @@ 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> </varlistentry> @@ -813,7 +824,8 @@ 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> </varlistentry> @@ -1431,7 +1443,8 @@ 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> </varlistentry> @@ -1550,7 +1563,8 @@ 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> </varlistentry> @@ -1650,7 +1664,8 @@ 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> </varlistentry> 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