pyqGroupEvalファンクション(Autonomous Database)

ファンクション pyqGroupEvalは、SCR_NAMEパラメータで指定されたユーザー定義Python関数を実行します。INP_NAMパラメータを使用して、ユーザー定義Python関数にデータを渡します。PAR_LSTパラメータは、スクリプトでレンダリングされたイメージを取得するための特別な制御引数oml_graphics_flagを指定し、oml_parallel_flagおよびoml_service_levelフラグはMEDIUMサービス・レベルを使用したパラレル処理を有効にします。関連項目: 特殊な制御引数(Autonomous Database)。GRP_COLパラメータを使用して、1つ以上のグループ化列を指定します。

ユーザー定義Python関数は、boolean、dict、float、int、list、str、tupleまたはpandas.DataFrameオブジェクトを返すことができます。OUT_FMTパラメータを使用して、返される値の形式を定義します。

構文

FUNCTION PYQSYS.pyqGroupEval(
    INP_NAM    VARCHAR2,
    PAR_LST    VARCHAR2,
    OUT_FMT    VARCHAR2,
    GRP_COL    VARCHAR2,
    ORD_COL    VARCHAR2,
    SCR_NAME   VARCHAR2,
    SCR_OWNER  VARCHAR2 DEFAULT NULL,
    ENV_NAME   VARCHAR2 DEFAULT NULL
    )
    RETURN SYS.AnyDataSet

パラメータ

パラメータ	説明
`INP_NAM`	`SCR_NAME`パラメータで指定されたPython関数に渡すデータを指定する表またはビューの名前。別のユーザーが所有する表またはビューを使用する場合は、`<owner name>.<table/view name>`という形式を使用します。指定された表またはビューに対する読取りアクセス権が必要です。
`PAR_LST`	`SCR_NAME`パラメータで指定されたユーザー定義Python関数に渡す追加パラメータが含まれるJSON文字列。`oml_`で始まる特殊な制御引数は、`SCR_NAME`で指定された関数に渡されるのではなく、関数の呼出し前後の動作を制御します。たとえば、入力データ型を`pandas.DataFrame`として指定するには、次を使用します。 `'{"oml_input_type":"pandas.DataFrame"}'` 関連項目: 特殊な制御引数(Autonomous Database)。
`OUT_FMT`	ファンクションによって返される出力の形式。次のいずれかになります。ファンクションによって返された表の列名およびデータ型を指定するJSON文字列。イメージ・データは破棄されます。Python関数は、`pandas.DataFrame`、`numpy.ndarray`、`tuple`または`tuple`のリストを返す必要があります。文字列`'JSON'`。返される表にJSON文字列であるCLOBが含まれることを指定します。文字列`'XML'`。返される表にXML文字列であるCLOBが含まれることを指定します。XMLには構造化データとイメージの両方が含まれる可能性があり、最初に構造化または半構造化のPythonオブジェクトが含まれ、続いてPython関数によって生成されたイメージが含まれます。文字列`'PNG'`。返される表に、Python関数によって生成されたイメージを格納するBLOBが含まれることを指定します。イメージはPNG表示のbase 64エンコーディングとして返されます。関連項目: 出力形式(Autonomous Database)。
`GRP_COL`	データのパーティション化に使用するグループ化列の名前。複数の列を区切るには、カンマを使用します。たとえば、`GENDER`および`YEAR`でグループ化する場合: `"GENDER,YEAR"`
`ORD_COL`	入力データを順序付けるためのカンマ区切りの列名。たとえば、`GENDER`で順序付けるには、次のようにします。 `"GENDER"` 指定した場合、入力データはまず`ORD_COL`列で順序付けされた後、`GRP_COL`列でグループ化されます。
`SCR_NAME`	OML4Pyスクリプト・リポジトリ内のユーザー定義Python関数の名前。
`SCR_OWNER`	登録済Pythonスクリプトの所有者。デフォルト値は`NULL`です。`NULL`の場合、ユーザーのスクリプト・リポジトリでPythonスクリプトを検索します。
`ENV_NAME`	指定されたユーザー定義Python関数の実行時に使用されるconda環境の名前。

例

この例では、「pyqEvalファンクション(Autonomous Database)」に示した例で作成されたIRIS表を使用します。

Python関数group_countを定義し、mygroupcountという名前でスクリプト・リポジトリに格納します。この関数は、データdatの各グループに対して生成されたpandas.DataFrameを返します。また、この関数は、各グループの花弁の長さの値を使用して、萼片の長さをプロットします。

BEGIN
    sys.pyqScriptCreate('mygroupcount',
        'def group_count(dat):
        import pandas as pd
        import matplotlib.pyplot as plt
        plt.plot(dat[["Sepal_Length"]], dat[["Petal_Length"]], ".")
        plt.xlabel("Sepal Length")
        plt.ylabel("Petal Length")
        plt.title("{}".format(dat["Species"][0]))
        return pd.DataFrame([(dat["Species"][0], dat.shape[0])],\
        columns = ["Species", "CNT"]) ',
        FALSE, TRUE); -- V_GLOBAL, V_OVERWRITE
END;
/

pyqGroupEvalファンクションを呼び出す問合せを発行します。このファンクションのINP_NAM引数では、関数に渡すIRIS表内のデータを指定します。

PAR_LST引数では、特殊な制御引数oml_input_typeを指定します。

OUT_FMT引数では、pyqGroupEvalによって返される表の列名およびデータ型が含まれるJSON文字列を指定します。

GRP_COLパラメータでは、グループ化する列を指定します。

SCR_NAMEパラメータでは、mygroupcountという名前でスクリプト・リポジトリに格納されているユーザー定義Python関数を指定します。

SELECT *
    FROM table(
        pyqGroupEval(
            inp_nam => 'IRIS',
            par_lst => '{"oml_input_type":"pandas.DataFrame"}',
            out_fmt => '{"Species":"varchar2(10)", "CNT":"number"}',
            grp_col => 'Species',
            ord_col => NULL,
            scr_name => 'mygroupcount'));

出力は次のようになります。

Species CNT
---------- ----------
virginica 50
setosa 50
versicolor 50
3 rows selected.

IRISデータを使用して同じスクリプトを実行し、XML出力を返します。PAR_LST引数には、スクリプトでレンダリングされたイメージを取得するための特別な制御引数oml_graphics_flagを指定します。構造化データとイメージの両方がXML出力に含まれています。XML出力はCLOBです。set long [length]をコールすると、詳細出力を取得できます。

set long 300
SELECT *
    FROM table(
        pyqGroupEval(
            inp_nam => 'IRIS',
            par_lst => '{"oml_input_type":"pandas.DataFrame", "oml_graphics_flag":true, "oml_parallel_flag":true", "oml_service_level":"MEDIUM"}',
            out_fmt => 'XML',
            grp_col => 'Species',
            ord_col => NULL,
            scr_name => 'mygroupcount'));

出力は次のようになります。

NAME VALUE
virginica <root><Py-data><pandas_dataFrame><ROW-pandas_dataFrame><Species>virginica</Species><CNT>50</CNT></ROW-pandas_dataFrame></pandas_dataFrame></Py-data><images><image><img src="data:image/pngbase64"><![CDATA[iVBORw0KGgoAAAANSUhEUgAAAoAAAAHgCAYAAAA10dzkAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjMu
setosa <root><Py-data><pandas_dataFrame><ROW-pandas_dataFrame><Species>setosa</Species><CNT>50</CNT></ROW-pandas_dataFrame></pandas_dataFrame></Py-data><images><image><img src="data:image/pngbase64"><![CDATA[iVBORw0KGgoAAAANSUhEUgAAAoAAAAHgCAYAAAA10dzkAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjMuMyw
versicolor <root><Py-data><pandas_dataFrame><ROW-pandas_dataFrame><Species>versicolor</Species><CNT>50</CNT></ROW-pandas_dataFrame></pandas_dataFrame></Py-data><images><image><img src="data:image/pngbase64"><![CDATA[iVBORw0KGgoAAAANSUhEUgAAAoAAAAHgCAYAAAA10dzkAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjM

IRISデータを使用して同じスクリプトを実行し、PNG出力を取得します。PAR_LST引数には、イメージを取得するための特別な制御引数oml_graphics_flagを指定します。

column name format a7
column value format a15
column title format a16
column image format a15
SELECT *
    FROM table(
        pyqGroupEval(
            inp_nam => 'IRIS',
            par_lst => '{"oml_input_type":"pandas.DataFrame", "oml_graphics_flag":true}',
            out_fmt => 'PNG',
            grp_col => 'Species',
            ord_col => NULL,
            scr_name => 'mygroupcount'));

出力は次のようになります。

NAME            ID VALUE           TITLE            IMAGE
------- ---------- --------------- ---------------- ---------------
GROUP_s          1 [{"Species":"se setosa           89504E470D0A1A0
etosa              tosa","CNT":50}                  A0000000D494844
                   ]                                520000028000000
                                                    1E0080600000035
                                                    D1DCE4000000397
                                                    4455874536F6674
                                                    77617265004D617
                                                    4706C6F746C6962
                                                    2076657273696F6
                                                    E332E332E332C20
                                                    6874747073

NAME            ID VALUE           TITLE            IMAGE
------- ---------- --------------- ---------------- ---------------

GROUP_v          1 [{"Species":"ve versicolor       89504E470D0A1A0
ersicol            rsicolor","CNT"                  A0000000D494844
or                 :50}]                            520000028000000
                                                    1E0080600000035
                                                    D1DCE4000000397
                                                    4455874536F6674
                                                    77617265004D617
                                                    4706C6F746C6962
                                                    2076657273696F6
                                                    E332E332E332C20

NAME            ID VALUE           TITLE            IMAGE
------- ---------- --------------- ---------------- ---------------
                                                    6874747073

GROUP_v          1 [{"Species":"vi virginica        89504E470D0A1A0
irginic            rginica","CNT":                  A0000000D494844
a                  50}]                             520000028000000
                                                    1E0080600000035
                                                    D1DCE4000000397
                                                    4455874536F6674
                                                    77617265004D617
                                                    4706C6F746C6962
                                                    2076657273696F6