AnalyticDB:AnalyticDB for PostgreSQL V7.0のPL/Python関数

使用上の注意

• デフォルトでは、PL/Pythonはplpython3uをサポートします。 このトピックでは、plpython3uを使用してPL/Pythonの使用方法を説明します。

• plpython3uは信頼できないと見なされるため、高リスク操作の実行にはplpython3uを使用しないことを推奨します。 AnalyticDB for PostgreSQLは、plpython3uに制限を課します。 plpython3uを使用するには、

  チケットを起票してください。

• PL/Pythonトリガーはサポートされていません。

• 更新は、... との現在の場所は... 更新可能なカーソルを実装するために、ステートメントを実行できない場合。

制限事項

AnalyticDB for PostgreSQL V7.0のみがPL/Pythonをサポートしています。

構文

CREATE FUNCTIONステートメントの標準宣言を使用して、ユーザー定義関数 (UDF) を作成できます。 詳細については、「CREATE FUNCTION」をご参照ください。

CREATE FUNCTION function_name ()
  RETURNS return_type
AS $$
  # PL/Python function_body
$$ LANGUAGE plpython3u STRICT;

Parameters

• function_name: UDFの名前。 This parameter is required.

• return_type: 戻り値のデータ型。 This parameter is required.

• function_body: UDFの本体。 This parameter is required. UDFを呼び出すと、function_bodyパラメーターがargs[] 要素の形式でUDFに渡され、名前付きパラメーターが通常の変数としてPythonスクリプトに渡されます。 RETURNS句で指定したデータ型の結果が返されます。

• STRICT: 入力引数がnullの場合、function_bodyパラメーターで指定されたコードを実行する代わりに、UDFは自動的にnullを返します。 これにより、不要な計算がなくなり、コードが簡素化されます。 このパラメーターはオプションです。

  次の例では、2つのSQL文が同じ効果を持ち、2つの値の大きい方を返すUDFを作成します。 入力引数がnullの場合は、nullが返されます。 ただし、STRICTパラメーターを含む左側のSQL文はより単純です。

  CREATE FUNCTION py_int_max (a integer, b integer) RETURNS integer AS $$ RETURN MAX(a,b) $$ LANGUAGE plpython3u STRICT;

  CREATE FUNCTION py_int_max (a integer, b integer) RETURNS integer AS $$ if (a IS None) OR (b IS None): RETURN None if a > b: RETURN a RETURN b $$ LANGUAGE plpython3u;

データ型マッピング

基本データ型

次の表に、AnalyticDB for PostgreSQLとPythonの間のデータ型マッピングを示します。 詳細については、「データ値」をご参照ください。

配列とリスト

plpython3u関数に渡されたSQL配列値は、自動的にPythonリストに変換されます。 plpython3u関数から返されたPythonリストは、自動的にSQL配列値に変換されます。

1次元配列

plpython3u関数のほとんどの場合、ブラケット ([]) を使用して1次元配列を指定できます。

次の例では、整数の1次元配列を返すplpython3u関数が作成され、呼び出されます。

CREATE FUNCTION create_py_int_array()
  RETURNS int[]
AS $$
  RETURN [1, 2, 3, 4]
$$ LANGUAGE plpython3u;

関数を呼び出します。Invoke the function.

SELECT create_py_int_array();

次の応答が返されます。

create_py_int_array
---------------------
{1,2,3,4}
(1 row) 

多次元配列

plpython3u関数では、多次元配列はリストのリストと見なされます。 多次元配列は、ネストされたPythonリストとしてplpython3u関数に渡されます。 plpython3u関数が多次元配列を返す場合、各レベルの内部リストは同じサイズでなければなりません。

次の例では、plpython3u関数が作成され、呼び出されます。 この関数は、整数の多次元配列を入力として受け取り、多次元配列を返します。

CREATE FUNCTION create_multidim_py_array(x int4[]) 
  RETURNS int4[]
AS $$
  plpy.info(x, type(x))
  RETURN x
$$ LANGUAGE plpython3u;

関数を呼び出します。Invoke the function.

SELECT * FROM create_multidim_py_array(ARRAY[[1,2,3], [4,5,6]]);

次の応答が返されます。

 create_multidim_py_array 
--------------------------
 {{1,2,3},{4,5,6}}
(1 row) 

複合タイプ

コンポジット型の引数をPythonマッピングとしてplpython3u関数に渡すことができます。 マッピングの要素名は、複合型の属性名である。 属性の値がnullの場合、属性のマッピング値はNoneです。 コンポジット型の結果は、シーケンス型 (タプルまたはリスト) として返すことができます。 複合型の配列が返される場合、配列はタプルとして指定する必要があります。 データ型があいまいになるため、複合型の配列をリストとして返すことはできません。

次の例では、composite型とcomposite型配列を返すplpython3u関数が作成されています。

CREATE TYPE type_record AS (
  FIRST text,
  SECOND int4
);

CREATE FUNCTION composite_type_as_list()
  RETURNS type_record[]
AS $$              
  RETURN [[('first', 1), ('second', 1)], [('first', 2), ('second', 2)]];
$$ LANGUAGE plpython3u;

関数を呼び出します。Invoke the function.

SELECT * FROM composite_type_as_list();

次の応答が返されます。

                               composite_type_as_list                           
------------------------------------------------------------------------------------
 {{"(first,1)","(second,1)"},{"(first,2)","(second,2)"}}
(1 row) 

plpython3uが配列と複合型を処理する方法の詳細については、「配列、リスト」をご参照ください。

セット返却関数

plpython3u関数は、シーケンス型 (タプル、リスト、またはセット) に基づいて、スカラーまたは複合型のセットを返すことができます。

次の例では、複合型と、複合型セットを返すplpython3u関数が作成されます。

-- Create a composite type.
CREATE TYPE greeting AS (
  how text,
  who text
);

CREATE FUNCTION greet (how text)
  RETURNS SETOF greeting
AS $$
  # RETURN tuple containing lists AS composite types
  # ALL other combinations work also
  RETURN ( {"how": how, "who": "World"}, {"how": how, "who": "ADB PG"} )
$$ LANGUAGE plpython3u;

関数を呼び出します。Invoke the function.

SELECT greet('hello');

次の応答が返されます。

       greet
-------------------
 (hello,World)
 (hello,ADB PG)
(2 rows)

の準備と実行SQLクエリ

plpython3u言語では、plpyモジュールは、SQLクエリを実行するためのplpy.exe cute() およびplpy.prepare() 関数を提供します。 また、plpython3u言語は、plpy.subtransaction() 関数を使用して、明示的なサブトランザクションのplpy.exe cute() 呼び出しを管理します。 plpy.subtransaction() 関数の詳細については、「Explicit Subtransactions」をご参照ください。

plpy.exeかわいい ()

plpy.exe cute() 関数は、SQLクエリを実行するために使用できます。 plpy.exe cute() 関数は、SQL文 (必須) と返される行の最大数 (オプション) の2つのパラメーターをサポートします。 plpy.exe cute() 関数は、Python結果オブジェクトを返します。 結果オブジェクトは、リストまたは辞書としてアクセスできます。 行番号と列名を使用して、結果オブジェクトの行にアクセスできます。 行番号は0から始まります。

たとえば、plpy.exe cute() 関数を呼び出してmy_tableテーブルを照会し、最大5行のデータを返すことができます。 返された結果はrvオブジェクトに格納されます。

rv = plpy.exe cute("SELECT * FROM my_table", 5) 。

my_tableテーブルにmy_column列が含まれている場合は、my_col_data = rv[i]["my_column"] のコードを使用して、rvオブジェクトの行にアクセスできます。

結果オブジェクトは、nrows() やstatus() などの追加メソッドをサポートします。 詳細については、「データベースアクセス」をご参照ください。

plpy.prepare()

plpy.prepare() 関数は、クエリの実行プランを準備するために使用できます。 plpy.prepare() 関数を呼び出すときは、クエリ文字列を指定する必要があります。 クエリ文字列にパラメーター参照が含まれている場合は、パラメータータイプのリストを指定する必要があります。

次のplpy.prepare() 関数を呼び出して、planという名前の実行プランを作成します。

# The text parameter specifies the data type of the $1 variable. 
plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", ["text"]) 

次のplpy.exe cute() 関数を呼び出して、実行プランを実行します。

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

DO匿名コードブロック

次のDOステートメントを実行して、匿名コードブロックを実行できます。

CREATE TEMP TABLE temp_tbl AS VALUES (2) DISTRIBUTED RANDOMLY;
DO $$
  row = plpy.execute("SELECT * FROM temp_tbl", 1)
  attr = row[0]["column1"]
  plpy.notice("attr is %s" % attr)
$$ LANGUAGE plpython3u;

Pythonエラーとメッセージの処理

Pythonモジュールplpyは、エラーとメッセージを管理するために、plpy.de bug() 、plpy.log() 、plpy.notice() 、plpy.warning() 、plpy.error() 、およびplpy.fatal() 関数をplpy.infoします。

plpy.error() およびplpy.fatal() 関数は、Python例外を発生させます。 例外がキャッチされない場合、例外は呼び出し元のクエリに伝播し、現在のトランザクションまたはサブトランザクションがキャンセルされます。 raise plpy.error(msg) およびraise plpy.fatal(msg) 関数は、それぞれplpy.error() およびplpy.fatal() と同等です。 他のメッセージ機能は、異なる優先レベルのメッセージのみを生成する。

Pythonの依存関係の管理

Pythonの依存関係は、コーディネーターとコンピュートノードのローカルSSDに保存されます。 Alibaba CloudイメージWebサイトに他の依存関係をインストールする場合は、