1. ユーザーズ・ガイド
  2. Embedded Python Execution
  3. Autonomous DatabaseでのEmbedded Python ExecutionのSQL API
  4. Embedded Python Executionファンクション(Autonomous Database)
  5. pyqGroupEvalファンクション(Autonomous Database)

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

ファンクションpyqGroupEvalは、Oracle Autonomous Databaseで使用すると、データを1つ以上の列でグループ化し、各グループに対してユーザー定義Python関数を実行します。

ユーザー定義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環境の名前。

例

この例では、指定されたデータ・セット内のデータの各パーティションに対し、指定されたPythonスクリプトを実行するpyqGroupEvalファンクションをコールします。

INP_NAM引数は、Python関数に渡すIRIS表内のデータを指定します。

PAR_LST引数は、特殊な制御引数oml_graphics_flagを使用してスクリプトでレンダリングされたイメージを取得することを指定します。

OUT_FMT引数は、Python関数によって生成されたイメージが格納されたBLOBが含まれる表を返すことを指定します。

GRP_COL引数は、指定されたデータを'Species'列でグループ化することを指定します。

SCR_NAMEパラメータは、pyqTableEvalファンクション(Autonomous Database)で作成される'test_seaborn_inp'スクリプトを指定します。

ENV_NAMEパラメータは、pyqEvalファンクション(Autonomous Database)で作成されるConda環境である'seaborn'を指定します。 

select *
  from table(pyqGroupEval(
        inp_nam =>  'IRIS',
        par_lst => '{"oml_graphics_flag":true}',
        out_fmt => 'PNG',
        grp_col => 'Species',
        ord_col => NULL,
        scr_name => 'test_seaborn_inp',
        scr_owner => NULL,
        env_name => 'seaborn'
));

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

NAME
--------------------------------------------------------------------------------
        ID
----------
VALUE
--------------------------------------------------------------------------------
TITLE
--------------------------------------------------------------------------------
IMAGE
--------------------------------------------------------------------------------
GROUP_setosa
         1
"hello world"

NAME
--------------------------------------------------------------------------------
        ID
----------
VALUE
--------------------------------------------------------------------------------
TITLE
--------------------------------------------------------------------------------
IMAGE
--------------------------------------------------------------------------------
Iris plot
89504E470D0A1A0A0000000D4948445200000280000001E0080600000035D1DCE400000039744558
74536F667477617265004D6174706C6F746C69622076657273696F6E332E332E332C206874747073

NAME
--------------------------------------------------------------------------------
        ID
----------
VALUE
--------------------------------------------------------------------------------
TITLE
--------------------------------------------------------------------------------
IMAGE
--------------------------------------------------------------------------------
3A2F2F6D6174706C6F746C69622E6F72672FC897B79C000000097048597300000F6100000F6101A8
3FA76900006AC649444154789CEDDD797854E5DD3EF0FBCC9EC92CD9F7B02624EC088A804B444005
AAD2AAB5D4166DD5F7ADDAB75A972AD60D375C706B2D2E588BED5B6A5FFD556AA91B555114549045

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

GROUP_versicolor
         1

NAME
--------------------------------------------------------------------------------
        ID
----------
VALUE
--------------------------------------------------------------------------------
TITLE
--------------------------------------------------------------------------------
IMAGE
--------------------------------------------------------------------------------
"hello world"
Iris plot
89504E470D0A1A0A0000000D4948445200000280000001E0080600000035D1DCE400000039744558

NAME
--------------------------------------------------------------------------------
        ID
----------
VALUE
--------------------------------------------------------------------------------
TITLE
--------------------------------------------------------------------------------
IMAGE
--------------------------------------------------------------------------------
74536F667477617265004D6174706C6F746C69622076657273696F6E332E332E332C206874747073
3A2F2F6D6174706C6F746C69622E6F72672FC897B79C000000097048597300000F6100000F6101A8
3FA76900009E9149444154789CECDD77785CE5993FFCEF2973CE548D7AB124F76E6C03A69966AAC1

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

GROUP_virginica

NAME
--------------------------------------------------------------------------------
        ID
----------
VALUE
--------------------------------------------------------------------------------
TITLE
--------------------------------------------------------------------------------
IMAGE
--------------------------------------------------------------------------------
         1
"hello world"
Iris plot

NAME
--------------------------------------------------------------------------------
        ID
----------
VALUE
--------------------------------------------------------------------------------
TITLE
--------------------------------------------------------------------------------
IMAGE
--------------------------------------------------------------------------------
89504E470D0A1A0A0000000D4948445200000280000001E0080600000035D1DCE400000039744558
74536F667477617265004D6174706C6F746C69622076657273696F6E332E332E332C206874747073
3A2F2F6D6174706C6F746C69622E6F72672FC897B79C000000097048597300000F6100000F6101A8

NAME
--------------------------------------------------------------------------------
        ID
----------
VALUE
--------------------------------------------------------------------------------
TITLE
--------------------------------------------------------------------------------
IMAGE
--------------------------------------------------------------------------------
3FA7690000838E49444154789CEDDD797854E5D906F07BF6996496EC7B2010F64D14C1065450C105
8A625B6B2D0A56ED82B8B756B12AA245D4AAD5B61FA8B8606BA9AD56DC91E2120465DFF73D044242

例

この例では、「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

親トピック: Embedded Python Executionファンクション(Autonomous Database)