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

Improve PL/Python database access function documentation

Browse Source 
Organize the function descriptions as a list instead of running text,
for easier access.
This commit is contained in:
Peter Eisentraut
2012-03-26 21:15:16 +03:00
parent dcb33b1c64
commit 206bec11bd
1 changed files with 159 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

215
doc/src/sgml/plpython.sgml
View File

@ -877,34 +877,23 @@ $$ LANGUAGE plpythonu;
<title>Database Access Functions</title> <title>Database Access Functions</title>
<para> <para>
The <literal>plpy</literal> module provides two The <literal>plpy</literal> module provides several functions to execute
functions called <function>execute</function> and database commands:
<function>prepare</function>. Calling </para>
<function>plpy.execute</function> with a query string and an
optional limit argument causes that query to be run and the result <variablelist>
to be returned in a result object. The result object emulates a <varlistentry>
list or dictionary object. The result object can be accessed by <term><literal>plpy.<function>execute</function>(<replaceable>query</replaceable> [, <replaceable>max-rows</replaceable>])</literal></term>
row number and column name. It has these additional methods: <listitem>
<function>nrows</function> which returns the number of rows <para>
returned by the query, <function>status</function> which is the Calling <function>plpy.execute</function> with a query string and an
<function>SPI_execute()</function> return value, optional row limit argument causes that query to be run and the result to
<function>colnames</function> which is the list of column names, be returned in a result object.
<function>coltypes</function> which is the list of column type OIDs,
and <function>coltypmods</function> which is the list of type-specific type
modifiers for the columns. The result object can be modified.
</para> </para>
<para> <para>
Note that calling <literal>plpy.execute</literal> will cause the entire The result object emulates a list or dictionary object. The result
result set to be read into memory. Only use that function when you are sure object can be accessed by row number and column name. For example:
that the result set will be relatively small. If you don't want to risk
excessive memory usage when fetching large results,
use <literal>plpy.cursor</literal> rather
than <literal>plpy.execute</literal>.
</para>
<para>
For example:
<programlisting> <programlisting>
rv = plpy.execute("SELECT * FROM my_table", 5) rv = plpy.execute("SELECT * FROM my_table", 5)
</programlisting> </programlisting>
@ -916,45 +905,102 @@ foo = rv[i]["my_column"]
</programlisting> </programlisting>
</para> </para>
<para>
The result object has these additional methods:
<variablelist>
<varlistentry>
<term><literal><function>nrows</function>()</literal></term>
<listitem>
<para>
Returns the number of rows returned or processed by the query.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal><function>status</function>()</literal></term>
<listitem>
<para>
The <function>SPI_execute()</function> return value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal><function>colnames</function>()</literal></term>
<term><literal><function>coltypes</function>()</literal></term>
<term><literal><function>coltypmods</function>()</literal></term>
<listitem>
<para>
Return a list of column names, list of column type OIDs, and list of
type-specific type modifiers for the columns, respectively.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The result object can be modified.
</para>
<para>
Note that calling <literal>plpy.execute</literal> will cause the entire
result set to be read into memory. Only use that function when you are
sure that the result set will be relatively small. If you don't want to
risk excessive memory usage when fetching large results,
use <literal>plpy.cursor</literal> rather
than <literal>plpy.execute</literal>.
</para>
</listitem>
</varlistentry>
<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>
<listitem>
<para> <para>
<indexterm><primary>preparing a query</><secondary>in PL/Python</></indexterm> <indexterm><primary>preparing a query</><secondary>in PL/Python</></indexterm>
The second function, <function>plpy.prepare</function>, prepares <function>plpy.prepare</function> prepares the execution plan for a
the execution plan for a query. It is called with a query string query. It is called with a query string and a list of parameter types,
and a list of parameter types, if you have parameter references in if you have parameter references in the query. For example:
the query. For example:
<programlisting> <programlisting>
plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", ["text"]) plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", ["text"])
</programlisting> </programlisting>
<literal>text</literal> is the type of the variable you will be <literal>text</literal> is the type of the variable you will be passing
passing for <literal>$1</literal>. After preparing a statement, you for <literal>$1</literal>. The second argument is optional if you don't
use the function <function>plpy.execute</function> to run it: want to pass any parameters to the query.
</para>
<para>
After preparing a statement, you use a variant of the
function <function>plpy.execute</function> to run it:
<programlisting> <programlisting>
rv = plpy.execute(plan, ["name"], 5) rv = plpy.execute(plan, ["name"], 5)
</programlisting> </programlisting>
The third argument is the limit and is optional. Pass the plan as the first argument (instead of the query string), and a
list of values to substitute into the query as the second argument. The
second argument is optional if the query does not expect any parameters.
The third argument is the optional row limit as before.
</para> </para>
<para> <para>
Query parameters and result row fields are converted between Query parameters and result row fields are converted between PostgreSQL
PostgreSQL and Python data types as described and Python data types as described in <xref linkend="plpython-data">.
in <xref linkend="plpython-data">. The exception is that composite The exception is that composite types are currently not supported: They
types are currently not supported: They will be rejected as query will be rejected as query parameters and are converted to strings when
parameters and are converted to strings when appearing in a query appearing in a query result. As a workaround for the latter problem, the
result. As a workaround for the latter problem, the query can query can sometimes be rewritten so that the composite type result
sometimes be rewritten so that the composite type result appears as appears as a result row rather than as a field of the result row.
a result row rather than as a field of the result row. Alternatively, the resulting string could be parsed apart by hand, but
Alternatively, the resulting string could be parsed apart by hand, this approach is not recommended because it is not future-proof.
but this approach is not recommended because it is not
future-proof.
</para> </para>
<para> <para>
When you prepare a plan using the PL/Python module it is When you prepare a plan using the PL/Python module it is automatically
automatically saved. Read the SPI documentation (<xref saved. Read the SPI documentation (<xref linkend="spi">) for a
linkend="spi">) for a description of what this means. description of what this means. In order to make effective use of this
In order to make effective use of this across function calls across function calls one needs to use one of the persistent storage
one needs to use one of the persistent storage dictionaries dictionaries <literal>SD</literal> or <literal>GD</literal> (see
<literal>SD</literal> or <literal>GD</literal> (see
<xref linkend="plpython-sharing">). For example: <xref linkend="plpython-sharing">). For example:
<programlisting> <programlisting>
CREATE FUNCTION usesavedplan() RETURNS trigger AS $$ CREATE FUNCTION usesavedplan() RETURNS trigger AS $$
@ -963,46 +1009,35 @@ CREATE FUNCTION usesavedplan() RETURNS trigger AS $$
$$ LANGUAGE plpythonu; $$ LANGUAGE plpythonu;
</programlisting> </programlisting>
</para> </para>
</listitem>
</varlistentry>
</sect2> <varlistentry>
<term><literal>plpy.<function>cursor</function>(<replaceable>query</replaceable>)</literal></term>
<sect2> <term><literal>plpy.<function>cursor</function>(<replaceable>plan</replaceable> [, <replaceable>arguments</replaceable>])</literal></term>
<title>Accessing Data with Cursors</title> <listitem>
<para> <para>
The <literal>plpy.cursor</literal> function accepts the same arguments The <literal>plpy.cursor</literal> function accepts the same arguments
as <literal>plpy.execute</literal> (except for <literal>limit</literal>) as <literal>plpy.execute</literal> (except for the row limit) and returns
and returns a cursor object, which allows you to process large result sets a cursor object, which allows you to process large result sets in smaller
in smaller chunks. As with <literal>plpy.execute</literal>, either a query chunks. As with <literal>plpy.execute</literal>, either a query string
string or a plan object along with a list of arguments can be used. The or a plan object along with a list of arguments can be used.
cursor object provides a <literal>fetch</literal> method that accepts an </para>
integer parameter and returns a result object. Each time you
<para>
The cursor object provides a <literal>fetch</literal> method that accepts
an integer parameter and returns a result object. Each time you
call <literal>fetch</literal>, the returned object will contain the next call <literal>fetch</literal>, the returned object will contain the next
batch of rows, never larger than the parameter value. Once all rows are batch of rows, never larger than the parameter value. Once all rows are
exhausted, <literal>fetch</literal> starts returning an empty result exhausted, <literal>fetch</literal> starts returning an empty result
object. Cursor objects also provide an object. Cursor objects also provide an
<ulink url="http://docs.python.org/library/stdtypes.html#iterator-types">iterator <ulink url="http://docs.python.org/library/stdtypes.html#iterator-types">iterator
interface</ulink>, yielding one row at a time until all rows are exhausted. interface</ulink>, yielding one row at a time until all rows are
Data fetched that way is not returned as result objects, but rather as exhausted. Data fetched that way is not returned as result objects, but
dictionaries, each dictionary corresponding to a single result row. rather as dictionaries, each dictionary corresponding to a single result
row.
</para> </para>
<para>
Cursors are automatically disposed of. But if you want to explicitly
release all resources held by a cursor, use the <literal>close</literal>
method. Once closed, a cursor cannot be fetched from anymore.
</para>
<tip>
<para>
Do not confuse objects created by <literal>plpy.cursor</literal> with
DB-API cursors as defined by
the <ulink url="http://www.python.org/dev/peps/pep-0249/">Python Database
API specification</ulink>. They don't have anything in common except for
the name.
</para>
</tip>
<para> <para>
An example of two ways of processing data from a large table is: An example of two ways of processing data from a large table is:
<programlisting> <programlisting>
@ -1036,6 +1071,26 @@ return len(rows)
$$ LANGUAGE plpythonu; $$ LANGUAGE plpythonu;
</programlisting> </programlisting>
</para> </para>
<para>
Cursors are automatically disposed of. But if you want to explicitly
release all resources held by a cursor, use the <literal>close</literal>
method. Once closed, a cursor cannot be fetched from anymore.
</para>
<tip>
<para>
Do not confuse objects created by <literal>plpy.cursor</literal> with
DB-API cursors as defined by
the <ulink url="http://www.python.org/dev/peps/pep-0249/">Python
Database API specification</ulink>. They don't have anything in common
except for the name.
</para>
</tip>
</listitem>
</varlistentry>
</variablelist>
</sect2> </sect2>
<sect2 id="plpython-trapping"> <sect2 id="plpython-trapping">