diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/spi.sgml | 47 |
1 files changed, 31 insertions, 16 deletions
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> |