PostgreSQL

+
returns up to 5 rows from `+my_table+`. If `+my_table+` has a column `+my_column+`, it would be accessed as:
+

  +
  The number of rows returned can be obtained using the built-in `+len+` function.
  +
  The result object has these additional methods:
  +
  [.term]#`+nrows+``+()+`#;;
    Returns the number of rows processed by the command. Note that this is not necessarily the same as the number of rows returned. For example, an `+UPDATE+` command will set this value but won't return any rows (unless `+RETURNING+` is used).
  [.term]#`+status+``+()+`#;;
    The `+SPI_execute()+` return value.
  [.term]#`+colnames+``+()+` +
  #[.term]#`+coltypes+``+()+` +
  #[.term]#`+coltypmods+``+()+`#;;
    Return a list of column names, list of column type OIDs, and list of type-specific type modifiers for the columns, respectively.
    +
    These methods raise an exception when called on a result object from a command that did not produce a result set, e.g., `+UPDATE+` without `+RETURNING+`, or `+DROP TABLE+`. But it is OK to use these methods on a result set containing zero rows.
  [.term]#`+__str__+``+()+`#;;
    The standard `+__str__+` method is defined so that it is possible for example to debug query execution results using `+plpy.debug(rv)+`.
  +
  The result object can be modified.
  +
  Note that calling `+plpy.execute+` 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 `+plpy.cursor+` rather than `+plpy.execute+`.
[.term]#`+plpy.+``+prepare+``+(+`_`+query+`_`+ [, +`_`+argtypes+`_`+])+` +
#[.term]#`+plpy.+``+execute+``+(+`_`+plan+`_`+ [, +`_`+arguments+`_`+ [, +`_`+limit+`_`+]])+`#::
   `+plpy.prepare+` prepares the execution plan for a query. It is called with a query string and a list of parameter types, if you have parameter references in the query. For example:
  +

+
`+text+` is the type of the variable you will be passing for `+$1+`. The second argument is optional if you don't want to pass any parameters to the query.
+
After preparing a statement, you use a variant of the function `+plpy.execute+` to run it:
+

+
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.
+
Alternatively, you can call the `+execute+` method on the plan object:
+

+
Query parameters and result row fields are converted between PostgreSQL and Python data types as described in link:plpython-data.html[Section 46.3].
+
When you prepare a plan using the PL/Python module it is automatically saved. Read the SPI documentation (link:spi.html[Chapter 47]) for a description of what this means. In order to make effective use of this across function calls one needs to use one of the persistent storage dictionaries `+SD+` or `+GD+` (see link:plpython-sharing.html[Section 46.4]). For example:
+

+
Cursors are automatically disposed of. But if you want to explicitly release all resources held by a cursor, use the `+close+` method. Once closed, a cursor cannot be fetched from anymore.
+
[TIP]
====
==== Tip

Do not confuse objects created by `+plpy.cursor+` with DB-API cursors as defined by the https://www.python.org/dev/peps/pep-0249/[Python Database API specification]. They don't have anything in common except for the name.
====