PL/Python 言語モジュールは自動的に plpy Python モジュールをインポートします。このモジュールの関数と定数は、plpy.foo のように作成した Python コードから使用することができます。 現在 plpy では、plpy.debug("msg")、plpy.log("msg")、plpy.info("msg")、plpy.notice("msg")、plpy.warning("msg")、plpy.error("msg")、および plpy.fatal("msg") 関数を実装しています。 これらは、C のコードからの elog(LEVEL, "msg") の呼び出しとほぼ同じです。 plpy.error および plpy.fatal は、実際に Python の例外を発生させます。これが catch されない場合、PL/Python モジュールは、その関数ハンドラが Python インタプリタから返る際に elog(ERROR, msg) を呼び出します。 Python インタプリタからの long jump は、おそらくあまり好ましくありません。raise plpy.ERROR("msg") および raise plpy.FATAL("msg") は、それぞれ plpy.error および plpy.fatal の呼び出しと同じです。
更に、plpy モジュールは execute および prepare という2つの関数を用意しています。 plpy.execute を、問い合わせ文字列および省略可能な制限引数を付けて呼び出すと、問い合わせが実行され、結果オブジェクトとして問い合わせ結果が返ります。この結果オブジェクトはリストもしくは辞書オブジェクトを模擬します。 結果オブジェクトは、行番号やフィールド名によってアクセスすることができます。 結果オブジェクトには、問い合わせ結果の行数を返す nrows()、SPI_exec が返す変数である、statusというメソッドが追加されています。 結果オブジェクトは、変更することができます。
以下に例を示します。
rv = plpy.execute("SELECT * FROM my_table", 5)これは、my_table から 5 行までを返します。 my_table に my_field 列が存在する場合、その列には以下のようにアクセスできます。
foo = rv[i]["my_field"]
2 番目の関数 plpy.prepare は、問い合わせ内にバインド変数がある場合、問い合わせ文字列および引数型のリストとともに呼び出されます。たとえば、以下のようにします。
plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", [ "text" ])text は、$1 として渡す変数の型です。 文を準備した後、それを実行するために関数 plpy.execute を使用します。
rv = plpy.execute(plan, [ "name" ], 5)
制限引数は plpy.execute を呼び出す時に省略することができます。
現行版では、PL/Python 関数の実行中、データベースエラーが発生すると、サーバによってその関数は即座に終了させられます。Python の try ... catch 構文を使用しても、エラー条件を trap することは不可能です。例えば、plpy.execute() 呼び出しに渡された SQL 文に構文エラーがあった場合、この関数は終了します。この動作は、今後変更する予定です。
PL/Python モジュールを使用して準備した計画は自動的に保存されます。これが何を意味するのかについては SPI の文書 (Chapter 17) を参照して下さい。
これを複数呼び出しにおいて効果的に使用するためには、永続的な格納用辞書である SD または GD (Section 22.1 参照) のいずれかを使用する必要があります。たとえば、以下のようにします。
CREATE FUNCTION usesavedplan ( ) RETURNS TRIGGER AS '
if SD.has_key("plan"):
plan = SD["plan"]
else:
plan = plpy.prepare("SELECT 1")
SD["plan"] = plan
# rest of function
' LANGUAGE 'plpython';