postgres.git / summary / log / commit / refs
commit b00bae2e9103b4cd4fc97141b3aba2fa0ce532a8
Author: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue May 02 21:55:01 2023 +0000
First released in: 16.0, 11.20, 12.15, 13.11, 14.8, 15.3
Doc: clarify behavior of row-limit arguments in the PLs' SPI wrappers.
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
doc/src/sgml/plperl.sgml | 21 ++++++++++++++++-----
doc/src/sgml/plpython.sgml | 13 +++++++++++--
doc/src/sgml/pltcl.sgml | 8 +++++---
3 files changed, 32 insertions(+), 10 deletions(-)
diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml
index 01f9870773d..06d657008e6 100644
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
@@ -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 > $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>
diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index b92c8662bf2..0ca80fb1a15 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -937,7 +937,7 @@ $$ LANGUAGE plpythonu;
<variablelist>
<varlistentry>
- <term><literal>plpy.<function>execute</function>(<replaceable>query</replaceable> [, <replaceable>max-rows</replaceable>])</literal></term>
+ <term><literal>plpy.<function>execute</function>(<replaceable>query</replaceable> [, <replaceable>limit</replaceable>])</literal></term>
<listitem>
<para>
Calling <function>plpy.execute</function> with a query string and an
@@ -945,6 +945,15 @@ $$ LANGUAGE plpythonu;
be returned in a result object.
</para>
+ <para>
+ If <replaceable>limit</replaceable> is specified and is greater than
+ zero, then <function>plpy.execute</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>
The result object emulates a list or dictionary object. The result
object can be accessed by row number and column name. For example:
@@ -1035,7 +1044,7 @@ foo = rv[i]["my_column"]
<varlistentry>
<term><literal>plpy.<function>prepare</function>(<replaceable>query</replaceable> [, <replaceable>argtypes</replaceable>])</literal></term>
- <term><literal>plpy.<function>execute</function>(<replaceable>plan</replaceable> [, <replaceable>arguments</replaceable> [, <replaceable>max-rows</replaceable>]])</literal></term>
+ <term><literal>plpy.<function>execute</function>(<replaceable>plan</replaceable> [, <replaceable>arguments</replaceable> [, <replaceable>limit</replaceable>]])</literal></term>
<listitem>
<para>
<indexterm><primary>preparing a query</primary><secondary>in PL/Python</secondary></indexterm>
diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index a01236ce937..4e48ceaddb9 100644
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -341,9 +341,11 @@ $$ LANGUAGE pltcl;
</para>
<para>
The optional <literal>-count</literal> value tells
- <function>spi_exec</function> the maximum number of rows
- to process in the command. The effect of this is comparable to
- setting up a query as a cursor and then saying <literal>FETCH <replaceable>n</replaceable></literal>.
+ <function>spi_exec</function> to stop
+ once <replaceable>n</replaceable> rows have been retrieved,
+ much as if the query included a <literal>LIMIT</literal> clause.
+ If <replaceable>n</replaceable> is zero, the query is run to
+ completion, the same as when <literal>-count</literal> is omitted.
</para>
<para>
If the command is a <command>SELECT</command> statement, the values of the
[parent: ee24b5e792e0]