database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-12-21 05:21:08 +03:00
Code Activity

Doc: clarify behavior of row-limit arguments in the PLs' SPI wrappers.

Browse Source 
plperl, plpython, and pltcl all provide query-execution functions
that are thin wrappers around SPI_execute() or its variants.
The SPI functions document their row-count limit arguments clearly,
as "maximum number of rows to return, or 0 for no limit".  However
the PLs' documentation failed to explain this special behavior of
zero, so that a reader might well assume it means "fetch zero
rows".  Improve that.

Daniel Gustafsson and Tom Lane, per report from Kieran McCusker

Discussion: https://postgr.es/m/CAGgUQ6H6qYScctOhktQ9HLFDDoafBKHyUgJbZ6q_dOApnzNTXg@mail.gmail.com
This commit is contained in:
Tom Lane
2023-05-02 17:55:01 -04:00
parent 08237056f8
commit 6489875ce6
3 changed files with 32 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
doc/src/sgml/plperl.sgml
View File

@@ -441,7 +441,7 @@ use strict;
<variablelist>
<varlistentry>
<term>
<literal><function>spi_exec_query</function>(<replaceable>query</replaceable> [, <replaceable>max-rows</replaceable>])</literal>
<literal><function>spi_exec_query</function>(<replaceable>query</replaceable> [, <replaceable>limit</replaceable>])</literal>
<indexterm>
<primary>spi_exec_query</primary>
<secondary>in PL/Perl</secondary>
@@ -449,9 +449,17 @@ use strict;
</term>
<listitem>
<para>
<literal>spi_exec_query</literal> executes an SQL command and
returns the entire row set as a reference to an array of hash
references. <emphasis>You should only use this command when you know
<function>spi_exec_query</function> executes an SQL command and
returns the entire row set as a reference to an array of hash references.
If <replaceable>limit</replaceable> is specified and is greater than zero,
then <function>spi_exec_query</function> retrieves at
most <replaceable>limit</replaceable> rows, much as if the query included
a <literal>LIMIT</literal> clause. Omitting <replaceable>limit</replaceable>
or specifying it as zero results in no row limit.
</para>
<para>
<emphasis>You should only use this command when you know
that the result set will be relatively small.</emphasis> Here is an
example of a query (<command>SELECT</command> command) with the
optional maximum number of rows:
@@ -643,7 +651,10 @@ $plan = spi_prepare('SELECT * FROM test WHERE id &gt; $1 AND name = $2',
by <literal>spi_exec_query</literal>, or in <literal>spi_query_prepared</literal> which returns a cursor
exactly as <literal>spi_query</literal> does, which can be later passed to <literal>spi_fetchrow</literal>.
The optional second parameter to <literal>spi_exec_prepared</literal> is a hash reference of attributes;
the only attribute currently supported is <literal>limit</literal>, which sets the maximum number of rows returned by a query.
the only attribute currently supported is <literal>limit</literal>, which
sets the maximum number of rows returned from the query.
Omitting <literal>limit</literal> or specifying it as zero results in no
row limit.
</para>
<para>