Skip to content

Commit 206bec1

Browse files
peterepetere
committed
Improve PL/Python database access function documentation
Organize the function descriptions as a list instead of running text, for easier access.
1 parent dcb33b1 commit 206bec1

File tree

1 file changed

+159
-104
lines changed

1 file changed

+159
-104
lines changed

‎doc/src/sgml/plpython.sgml‎

Lines changed: 159 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -877,134 +877,169 @@ $$ LANGUAGE plpythonu;
877877
<title>Database Access Functions</title>
878878

879879
<para>
880-
The <literal>plpy</literal> module provides two
881-
functions called <function>execute</function> and
882-
<function>prepare</function>. Calling
883-
<function>plpy.execute</function> with a query string and an
884-
optional limit argument causes that query to be run and the result
885-
to be returned in a result object. The result object emulates a
886-
list or dictionary object. The result object can be accessed by
887-
row number and column name. It has these additional methods:
888-
<function>nrows</function> which returns the number of rows
889-
returned by the query, <function>status</function> which is the
890-
<function>SPI_execute()</function> return value,
891-
<function>colnames</function> which is the list of column names,
892-
<function>coltypes</function> which is the list of column type OIDs,
893-
and <function>coltypmods</function> which is the list of type-specific type
894-
modifiers for the columns. The result object can be modified.
880+
The <literal>plpy</literal> module provides several functions to execute
881+
database commands:
895882
</para>
896883

897-
<para>
898-
Note that calling <literal>plpy.execute</literal> will cause the entire
899-
result set to be read into memory. Only use that function when you are sure
900-
that the result set will be relatively small. If you don't want to risk
901-
excessive memory usage when fetching large results,
902-
use <literal>plpy.cursor</literal> rather
903-
than <literal>plpy.execute</literal>.
904-
</para>
884+
<variablelist>
885+
<varlistentry>
886+
<term><literal>plpy.<function>execute</function>(<replaceable>query</replaceable> [, <replaceable>max-rows</replaceable>])</literal></term>
887+
<listitem>
888+
<para>
889+
Calling <function>plpy.execute</function> with a query string and an
890+
optional row limit argument causes that query to be run and the result to
891+
be returned in a result object.
892+
</para>
905893

906-
<para>
907-
For example:
894+
<para>
895+
The result object emulates a list or dictionary object. The result
896+
object can be accessed by row number and column name. For example:
908897
<programlisting>
909898
rv = plpy.execute("SELECT * FROM my_table", 5)
910899
</programlisting>
911-
returns up to 5 rows from <literal>my_table</literal>. If
912-
<literal>my_table</literal> has a column
913-
<literal>my_column</literal>, it would be accessed as:
900+
returns up to 5 rows from <literal>my_table</literal>. If
901+
<literal>my_table</literal> has a column
902+
<literal>my_column</literal>, it would be accessed as:
914903
<programlisting>
915904
foo = rv[i]["my_column"]
916905
</programlisting>
917-
</para>
906+
</para>
918907

919-
<para>
920-
<indexterm><primary>preparing a query</><secondary>in PL/Python</></indexterm>
921-
The second function, <function>plpy.prepare</function>, prepares
922-
the execution plan for a query. It is called with a query string
923-
and a list of parameter types, if you have parameter references in
924-
the query. For example:
908+
<para>
909+
The result object has these additional methods:
910+
<variablelist>
911+
<varlistentry>
912+
<term><literal><function>nrows</function>()</literal></term>
913+
<listitem>
914+
<para>
915+
Returns the number of rows returned or processed by the query.
916+
</para>
917+
</listitem>
918+
</varlistentry>
919+
920+
<varlistentry>
921+
<term><literal><function>status</function>()</literal></term>
922+
<listitem>
923+
<para>
924+
The <function>SPI_execute()</function> return value.
925+
</para>
926+
</listitem>
927+
</varlistentry>
928+
929+
<varlistentry>
930+
<term><literal><function>colnames</function>()</literal></term>
931+
<term><literal><function>coltypes</function>()</literal></term>
932+
<term><literal><function>coltypmods</function>()</literal></term>
933+
<listitem>
934+
<para>
935+
Return a list of column names, list of column type OIDs, and list of
936+
type-specific type modifiers for the columns, respectively.
937+
</para>
938+
</listitem>
939+
</varlistentry>
940+
</variablelist>
941+
</para>
942+
943+
<para>
944+
The result object can be modified.
945+
</para>
946+
947+
<para>
948+
Note that calling <literal>plpy.execute</literal> will cause the entire
949+
result set to be read into memory. Only use that function when you are
950+
sure that the result set will be relatively small. If you don't want to
951+
risk excessive memory usage when fetching large results,
952+
use <literal>plpy.cursor</literal> rather
953+
than <literal>plpy.execute</literal>.
954+
</para>
955+
</listitem>
956+
</varlistentry>
957+
958+
<varlistentry>
959+
<term><literal>plpy.<function>prepare</function>(<replaceable>query</replaceable> [, <replaceable>argtypes</replaceable>])</literal></term>
960+
<term><literal>plpy.<function>execute</function>(<replaceable>plan</replaceable> [, <replaceable>arguments</replaceable> [, <replaceable>max-rows</replaceable>]])</literal></term>
961+
<listitem>
962+
<para>
963+
<indexterm><primary>preparing a query</><secondary>in PL/Python</></indexterm>
964+
<function>plpy.prepare</function> prepares the execution plan for a
965+
query. It is called with a query string and a list of parameter types,
966+
if you have parameter references in the query. For example:
925967
<programlisting>
926-
plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", [ "text" ])
968+
plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", ["text"])
927969
</programlisting>
928-
<literal>text</literal> is the type of the variable you will be
929-
passing for <literal>$1</literal>. After preparing a statement, you
930-
use the function <function>plpy.execute</function> to run it:
970+
<literal>text</literal> is the type of the variable you will be passing
971+
for <literal>$1</literal>. The second argument is optional if you don't
972+
want to pass any parameters to the query.
973+
</para>
974+
<para>
975+
After preparing a statement, you use a variant of the
976+
function <function>plpy.execute</function> to run it:
931977
<programlisting>
932-
rv = plpy.execute(plan, [ "name" ], 5)
978+
rv = plpy.execute(plan, ["name"], 5)
933979
</programlisting>
934-
The third argument is the limit and is optional.
935-
</para>
980+
Pass the plan as the first argument (instead of the query string), and a
981+
list of values to substitute into the query as the second argument. The
982+
second argument is optional if the query does not expect any parameters.
983+
The third argument is the optional row limit as before.
984+
</para>
936985

937-
<para>
938-
Query parameters and result row fields are converted between
939-
PostgreSQL and Python data types as described
940-
in <xref linkend="plpython-data">. The exception is that composite
941-
types are currently not supported: They will be rejected as query
942-
parameters and are converted to strings when appearing in a query
943-
result. As a workaround for the latter problem, the query can
944-
sometimes be rewritten so that the composite type result appears as
945-
a result row rather than as a field of the result row.
946-
Alternatively, the resulting string could be parsed apart by hand,
947-
but this approach is not recommended because it is not
948-
future-proof.
949-
</para>
986+
<para>
987+
Query parameters and result row fields are converted between PostgreSQL
988+
and Python data types as described in <xref linkend="plpython-data">.
989+
The exception is that composite types are currently not supported: They
990+
will be rejected as query parameters and are converted to strings when
991+
appearing in a query result. As a workaround for the latter problem, the
992+
query can sometimes be rewritten so that the composite type result
993+
appears as a result row rather than as a field of the result row.
994+
Alternatively, the resulting string could be parsed apart by hand, but
995+
this approach is not recommended because it is not future-proof.
996+
</para>
950997

951-
<para>
952-
When you prepare a plan using the PL/Python module it is
953-
automatically saved. Read the SPI documentation (<xref
954-
linkend="spi">) for a description of what this means.
955-
In order to make effective use of this across function calls
956-
one needs to use one of the persistent storage dictionaries
957-
<literal>SD</literal> or <literal>GD</literal> (see
958-
<xref linkend="plpython-sharing">). For example:
998+
<para>
999+
When you prepare a plan using the PL/Python module it is automatically
1000+
saved. Read the SPI documentation (<xref linkend="spi">) for a
1001+
description of what this means. In order to make effective use of this
1002+
across function calls one needs to use one of the persistent storage
1003+
dictionaries <literal>SD</literal> or <literal>GD</literal> (see
1004+
<xref linkend="plpython-sharing">). For example:
9591005
<programlisting>
9601006
CREATE FUNCTION usesavedplan() RETURNS trigger AS $$
9611007
plan = SD.setdefault("plan", plpy.prepare("SELECT 1"))
9621008
# rest of function
9631009
$$ LANGUAGE plpythonu;
9641010
</programlisting>
965-
</para>
966-
967-
</sect2>
968-
969-
<sect2>
970-
<title>Accessing Data with Cursors</title>
971-
972-
<para>
973-
The <literal>plpy.cursor</literal> function accepts the same arguments
974-
as <literal>plpy.execute</literal> (except for <literal>limit</literal>)
975-
and returns a cursor object, which allows you to process large result sets
976-
in smaller chunks. As with <literal>plpy.execute</literal>, either a query
977-
string or a plan object along with a list of arguments can be used. The
978-
cursor object provides a <literal>fetch</literal> method that accepts an
979-
integer parameter and returns a result object. Each time you
980-
call <literal>fetch</literal>, the returned object will contain the next
981-
batch of rows, never larger than the parameter value. Once all rows are
982-
exhausted, <literal>fetch</literal> starts returning an empty result
983-
object. Cursor objects also provide an
984-
<ulink url="http://docs.python.org/library/stdtypes.html#iterator-types">iterator
985-
interface</ulink>, yielding one row at a time until all rows are exhausted.
986-
Data fetched that way is not returned as result objects, but rather as
987-
dictionaries, each dictionary corresponding to a single result row.
988-
</para>
1011+
</para>
1012+
</listitem>
1013+
</varlistentry>
9891014

990-
<para>
991-
Cursors are automatically disposed of. But if you want to explicitly
992-
release all resources held by a cursor, use the <literal>close</literal>
993-
method. Once closed, a cursor cannot be fetched from anymore.
994-
</para>
1015+
<varlistentry>
1016+
<term><literal>plpy.<function>cursor</function>(<replaceable>query</replaceable>)</literal></term>
1017+
<term><literal>plpy.<function>cursor</function>(<replaceable>plan</replaceable> [, <replaceable>arguments</replaceable>])</literal></term>
1018+
<listitem>
1019+
<para>
1020+
The <literal>plpy.cursor</literal> function accepts the same arguments
1021+
as <literal>plpy.execute</literal> (except for the row limit) and returns
1022+
a cursor object, which allows you to process large result sets in smaller
1023+
chunks. As with <literal>plpy.execute</literal>, either a query string
1024+
or a plan object along with a list of arguments can be used.
1025+
</para>
9951026

996-
<tip>
997-
<para>
998-
Do not confuse objects created by <literal>plpy.cursor</literal> with
999-
DB-API cursors as defined by
1000-
the <ulink url="http://www.python.org/dev/peps/pep-0249/">Python Database
1001-
API specification</ulink>. They don't have anything in common except for
1002-
the name.
1003-
</para>
1004-
</tip>
1027+
<para>
1028+
The cursor object provides a <literal>fetch</literal> method that accepts
1029+
an integer parameter and returns a result object. Each time you
1030+
call <literal>fetch</literal>, the returned object will contain the next
1031+
batch of rows, never larger than the parameter value. Once all rows are
1032+
exhausted, <literal>fetch</literal> starts returning an empty result
1033+
object. Cursor objects also provide an
1034+
<ulink url="http://docs.python.org/library/stdtypes.html#iterator-types">iterator
1035+
interface</ulink>, yielding one row at a time until all rows are
1036+
exhausted. Data fetched that way is not returned as result objects, but
1037+
rather as dictionaries, each dictionary corresponding to a single result
1038+
row.
1039+
</para>
10051040

1006-
<para>
1007-
An example of two ways of processing data from a large table is:
1041+
<para>
1042+
An example of two ways of processing data from a large table is:
10081043
<programlisting>
10091044
CREATE FUNCTION count_odd_iterator() RETURNS integer AS $$
10101045
odd = 0
@@ -1035,7 +1070,27 @@ rows = list(plpy.cursor(plan, [2]))
10351070
return len(rows)
10361071
$$ LANGUAGE plpythonu;
10371072
</programlisting>
1038-
</para>
1073+
</para>
1074+
1075+
<para>
1076+
Cursors are automatically disposed of. But if you want to explicitly
1077+
release all resources held by a cursor, use the <literal>close</literal>
1078+
method. Once closed, a cursor cannot be fetched from anymore.
1079+
</para>
1080+
1081+
<tip>
1082+
<para>
1083+
Do not confuse objects created by <literal>plpy.cursor</literal> with
1084+
DB-API cursors as defined by
1085+
the <ulink url="http://www.python.org/dev/peps/pep-0249/">Python
1086+
Database API specification</ulink>. They don't have anything in common
1087+
except for the name.
1088+
</para>
1089+
</tip>
1090+
</listitem>
1091+
</varlistentry>
1092+
</variablelist>
1093+
10391094
</sect2>
10401095

10411096
<sect2 id="plpython-trapping">

0 commit comments

Comments
 (0)