diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/spi.sgml | 41 |
1 files changed, 25 insertions, 16 deletions
diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml index 96687664137..13391689c70 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> @@ -434,7 +446,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> @@ -611,15 +623,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 +683,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> @@ -813,7 +822,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> @@ -1457,7 +1466,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> @@ -1575,7 +1584,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> @@ -1676,7 +1685,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> |