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

diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml
index 6c81ee8fbe1d72093e99d3c620397c0205fe639a..25b1077ad73823657325cce36e6b2ded90e156bd 100644 (file)
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
@@ -441,7 +441,7 @@ use strict;
    
     
      
-      spi_exec_query(query [, max-rows])
+      spi_exec_query(query [, limit])
       
        spi_exec_query
        in PL/Perl
@@ -449,9 +449,17 @@ use strict;
      
      
       
-       spi_exec_query executes an SQL command and
-returns the entire row set as a reference to an array of hash
-references.  You should only use this command when you know
+       spi_exec_query executes an SQL command and
+returns the entire row set as a reference to an array of hash references.
+If limit is specified and is greater than zero,
+then spi_exec_query retrieves at
+most limit rows, much as if the query included
+a LIMIT clause.  Omitting limit
+or specifying it as zero results in no row limit.
+      
+
+      
+You should only use this command when you know
 that the result set will be relatively small.  Here is an
 example of a query (SELECT 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 spi_exec_query, or in spi_query_prepared which returns a cursor
     exactly as spi_query does, which can be later passed to spi_fetchrow.
     The optional second parameter to spi_exec_prepared is a hash reference of attributes;
-    the only attribute currently supported is limit, which sets the maximum number of rows returned by a query.
+    the only attribute currently supported is limit, which
+    sets the maximum number of rows returned from the query.
+    Omitting limit or specifying it as zero results in no
+    row limit.
     
 
     

diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index e190c90f4538c97088625bbaf6ca5ef9e5c700d0..e05e607aba080e266b82903e592afa3ebf0cedaf 100644 (file)
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -789,7 +789,7 @@ $$ LANGUAGE plpython3u;
 
   
    
-    plpy.execute(query [, max-rows])
+    plpy.execute(query [, limit])
     
      
       Calling plpy.execute with a query string and an
@@ -797,6 +797,15 @@ $$ LANGUAGE plpython3u;
       be returned in a result object.
      
 
+     
+      If limit is specified and is greater than
+      zero, then plpy.execute retrieves at
+      most limit rows, much as if the query
+      included a LIMIT
+      clause.  Omitting limit or specifying it as
+      zero results in no row limit.
+     
+
      
       The result object emulates a list or dictionary object.  The result
       object can be accessed by row number and column name.  For example:
@@ -887,7 +896,7 @@ foo = rv[i]["my_column"]
 
    
     plpy.prepare(query [, argtypes])
-    plpy.execute(plan [, arguments [, max-rows]])
+    plpy.execute(plan [, arguments [, limit]])
     
      
       preparing a queryin PL/Python

diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index bf56ba6b1c60c3d9cc154ca76e1fe2c65c806ad3..b31f2c1330f5e11324e69de14031919f537811af 100644 (file)
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -341,9 +341,11 @@ $$ LANGUAGE pltcl;
        
        
         The optional -count value tells
-        spi_exec 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 FETCH n.
+        spi_exec to stop
+        once n rows have been retrieved,
+        much as if the query included a LIMIT clause.
+        If n is zero, the query is run to
+        completion, the same as when -count is omitted.
        
        
         If the command is a SELECT statement, the values of the