Calling <function>plpy.execute</function> with a query string and an optional row limit argument causes that query to be run and the result to be returned in a result object. plpy.executeを、問い合わせ文字列および省略可能な行数制限引数を付けて呼び出すと、問い合わせが実行され、結果オブジェクトとして問い合わせ結果が返ります。

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. limitが指定され、ゼロより大きい場合、plpy.executeは、問い合わせにLIMIT句が含まれているかのように、最大limit行を取得します。 limitを省略するか、ゼロとして指定すると、行制限はありません。

The result object emulates a list or dictionary object. The result object can be accessed by row number and column name. For example: 結果オブジェクトはリストもしくは辞書オブジェクトをエミュレートします。 結果オブジェクトは、行番号や列名によってアクセスすることができます。 例を示します。

rv = plpy.execute("SELECT * FROM my_table", 5)

returns up to 5 rows from <literal>my_table</literal>. If <literal>my_table</literal> has a column <literal>my_column</literal>, it would be accessed as: これは、my_tableから5行までを返します。 my_tableにmy_column列が存在する場合、その列には以下のようにアクセスできます。

foo = rv[i]["my_column"]

The number of rows returned can be obtained using the built-in <function>len</function> function. 戻った行数はビルトインlen関数を使用して取得できます。

The result object has these additional methods: 結果オブジェクトには以下のメソッドが追加されています。

The result object can be modified. 結果オブジェクトは変更できます。

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>. plpy.executeを呼び出すことにより、結果セット全体がメモリ内に読み込まれることに注意してください。 結果セットが比較的小さいことが確実な場合だけ、この関数を使用してください。 大規模な結果を取り込む場合の過度のメモリ使用に関する危険を回避したい場合は、plpy.executeではなくplpy.cursorを使用してください。

<indexterm><primary>preparing a query</primary><secondary>in PL/Python</secondary></indexterm> <function>plpy.prepare</function> 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: plpy.prepareは問い合わせの実行計画を準備します。 問い合わせ内にパラメータ参照がある場合、問い合わせ文字列および引数型のリストとともに呼び出されます。 例を示します。

plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", ["text"])

<literal>text</literal> is the type of the variable you will be passing for <literal>$1</literal>. The second argument is optional if you don't want to pass any parameters to the query. textは$1として渡される変数の型です。 問い合わせにパラメータを渡さない場合、2番目の引数は省略可能です。

After preparing a statement, you use a variant of the function <function>plpy.execute</function> to run it: 文を準備した後、それを実行するために関数plpy.executeの亜種を使用します。

rv = plpy.execute(plan, ["name"], 5)

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. 実行計画を（問い合わせ文字列ではなく）最初の引数として渡してください。 問い合わせに代入する値のリストを、2番目の引数として渡してください。 問い合わせにパラメータがない場合、2番目の引数は省略可能です。 3番目の引数は、前に述べた省略可能な行数制限引数です。

Alternatively, you can call the <function>execute</function> method on the plan object: 代わりに、計画オブジェクトのexecuteメソッドを呼び出すことができます。

rv = plan.execute(["name"], 5)

Query parameters and result row fields are converted between PostgreSQL and Python data types as described in <xref linkend="plpython-data"/>. 問い合わせパラメータおよび結果行のフィールドは46.2で示した通り、PostgreSQLとPythonのデータ型の間で変換されます。

When you prepare a plan using the PL/Python module it is automatically saved. Read the SPI documentation (<xref linkend="spi"/>) 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 <literal>SD</literal> or <literal>GD</literal> (see <xref linkend="plpython-sharing"/>). For example: PL/Pythonモジュールを使用して準備した計画は自動的に保存されます。 これが何を意味するのかについてはSPIの文書（第47章）を参照してください。 これを複数呼び出しにおいて効果的に使用するためには、永続的な格納用辞書であるSDまたはGD（46.3を参照）のいずれかを使用する必要があります。 例を示します。

CREATE FUNCTION usesavedplan() RETURNS trigger AS $$
    if "plan" in SD:
        plan = SD["plan"]
    else:
        plan = plpy.prepare("SELECT 1")
        SD["plan"] = plan
    # rest of function
$$ LANGUAGE plpython3u;

The <literal>plpy.cursor</literal> function accepts the same arguments as <literal>plpy.execute</literal> (except for the row limit) and returns a cursor object, which allows you to process large result sets in smaller chunks. As with <literal>plpy.execute</literal>, either a query string or a plan object along with a list of arguments can be used, or the <function>cursor</function> function can be called as a method of the plan object. plpy.cursor関数はplpy.executeと同じ引数を受け取り（行数制限引数を除いた）カーソルオブジェクトとして返します。 これにより大規模な結果セットをより小さな塊の中で処理することができます。 plpy.executeの場合と同様、問い合わせ文字列または引数リスト付きの計画オブジェクトを使用できますし、計画オブジェクトのメソッドとしてcursor関数を呼ぶことができます。

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 batch of rows, never larger than the parameter value. Once all rows are exhausted, <literal>fetch</literal> starts returning an empty result object. Cursor objects also provide an <ulink url="https://docs.python.org/library/stdtypes.html#iterator-types">iterator interface</ulink>, yielding one row at a time until all rows are exhausted. Data fetched that way is not returned as result objects, but rather as dictionaries, each dictionary corresponding to a single result row. カーソルオブジェクトは、整数パラメータを受付け、結果オブジェクトを返すfetchメソッドを提供します。 fetchを呼び出す度に、返されるオブジェクトには次の一群の行が含まれます。 この行数はパラメータ値より多くなることはありません。 全ての行が出し尽くされると、fetchは空の結果オブジェクトを返すようになります。 カーソルオブジェクトはまた、すべての行を出し尽くすまで一度に１行を生成するイテレータインタフェースを提供します。 この方法で取り出されたデータは結果オブジェクトとしては返されず、１つの辞書が単一の結果行に対応する辞書群として返されます。

An example of two ways of processing data from a large table is: 大きなテーブルのデータを処理する、2つの方法の例を示します。

CREATE FUNCTION count_odd_iterator() RETURNS integer AS $$
odd = 0
for row in plpy.cursor("select num from largetable"):
    if row['num'] % 2:
         odd += 1
return odd
$$ LANGUAGE plpython3u;

CREATE FUNCTION count_odd_fetch(batch_size integer) RETURNS integer AS $$
odd = 0
cursor = plpy.cursor("select num from largetable")
while True:
    rows = cursor.fetch(batch_size)
    if not rows:
        break
    for row in rows:
        if row['num'] % 2:
            odd += 1
return odd
$$ LANGUAGE plpython3u;

CREATE FUNCTION count_odd_prepared() RETURNS integer AS $$
odd = 0
plan = plpy.prepare("select num from largetable where num % $1 <> 0", ["integer"])

rows = list(plpy.cursor(plan, [2]))  # or: = list(plan.cursor([2]))

rows = list(plpy.cursor(plan, [2]))  # または = list(plan.cursor([2]))

return len(rows)
$$ LANGUAGE plpython3u;

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. カーソルは自動的に処分されます。 しかし、カーソルが保有していた資源を明示的に解放したい場合は、closeメソッドを使用してください。 閉じた後、カーソルからこれ以上取り込むことはできません。