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

11.7.2.3 pyqTableEvalファンクション(Autonomous Database)

ファンクションpyqTableEvalは、Oracle Autonomous Databaseで使用すると、Oracle Database表のデータに対してユーザー定義Python関数を実行します。

INP_NAMパラメータで指定された表名からユーザー定義Python関数にデータを渡します。PAR_LSTパラメータを使用して、ユーザー定義Python関数に引数を渡します。

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

構文

FUNCTION PYQSYS.pyqTableEval(
   INP_NAM    VARCHAR2,
   PAR_LST    VARCHAR2,
   OUT_FMT    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)。

SCR_NAME

OML4Pyスクリプト・リポジトリ内のユーザー定義Python関数の名前。

SCR_OWNER

登録済Pythonスクリプトの所有者。デフォルト値はNULLです。NULLの場合、ユーザーのスクリプト・リポジトリでPythonスクリプトを検索します。

ENV_NAME

指定されたユーザー定義Python関数の実行時に使用されるconda環境の名前。

例

Python関数fit_modelを定義し、myLinearRegressionModelという名前でプライベート関数としてスクリプト・リポジトリに格納し、その名前で格納されている既存のユーザー定義Python関数を上書きします。

fit_model関数は、回帰モデルを入力データdatに適合させ、適合モデルをmodelName引数で指定されたオブジェクトとしてdatastoreName引数で指定されたデータストアに保存します。fit_model関数は、適合モデルを文字列形式で返します。

デフォルトでは、Pythonオブジェクトは、指定されたdatastoreNameで新しいデータストアに保存されます。オブジェクトを既存のデータストアに保存するには、oml.ds.save呼出しでoverwriteまたはappend引数をTrueに設定します。 

BEGIN
    sys.pyqScriptCreate('myLinearRegressionModel',
        'def fit_model(dat, modelName, datastoreName):
            import oml
            from sklearn import linear_model
            regr = linear_model.LinearRegression()
            regr.fit(dat.loc[:, ["Sepal_Length", "Sepal_Width", \
                                "Petal_Length"]],
                    dat.loc[:,["Petal_Width"]])
            oml.ds.save(objs={modelName:regr}, name=datastoreName,
                         overwrite=True)
            return str(regr)',
        FALSE, TRUE); -- V_GLOBAL, V_OVERWRITE
END;
/

次のコードを使用して、'test_seaborn_inp'スクリプトを作成します。

begin  sys.pyqScriptCreate('test_seaborn_inp',  
         'def fun_tab(dat):
          import seaborn as sns
          import matplotlib.pyplot as plt
          sns.lineplot(x="Sepal_Length", y="Sepal_Width", data=dat)
          plt.title("Iris plot")
          plt.show()
          return "hello world"
          ',FALSE,TRUE); -- V_GLOBAL, V_OVERWRITE
end;
/

この例では、指定されたデータ・セットに対して指定されたPython関数を実行するpyqTableEvalファンクションをコールします。

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

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

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

SCR_NAMEパラメータは、呼び出すユーザー定義Python関数のスクリプト・リポジトリ内での名前である、'test_seaborn_inp'スクリプトを指定します。

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

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

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

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

         1
"hello world"

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

NAME
--------------------------------------------------------------------------------
        ID
----------
VALUE
--------------------------------------------------------------------------------
TITLE
--------------------------------------------------------------------------------
IMAGE
--------------------------------------------------------------------------------
3A2F2F6D6174706C6F746C69622E6F72672FC897B79C000000097048597300000F6100000F6101A8
3FA7690000B9BC49444154789CECDD797CDC759D3FF0D7F79A2B9399DC499BA44DEF527A41B9CA61
3945C042576559500AABAC2BE2AE8ABA520459442CBA80E0FA0304517057B60A0B28972C22E5A6F4

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

この例では、pyqEvalファンクション(Autonomous Database)に示した例で作成されたIRIS表を使用します。pyqTableEvalファンクションを呼び出すSELECT文を実行します。pyqTableEvalファンクションのINP_NAMパラメータでは、Python関数に渡すデータとしてIRIS表を指定します。PAR_LSTパラメータでは、Python関数に渡すモデルおよびデータストアの名前を指定します。OUT_FMTパラメータはXML形式で値を返すことを指定し、SCR_NAMEパラメータはスクリプト・リポジトリのmyLinearRegressionModel関数を、呼び出すPython関数として指定します。XML出力はCLOBです。set long [length]をコールすると、詳細出力を取得できます。 

SELECT * 
FROM table(pyqTableEval( 
    inp_nam => 'IRIS', 
    par_lst => '{"modelName":"linregr", 
                 "datastoreName":"pymodel"}', 
out_fmt => 'XML', 
scr_name => 'myLinearRegressionModel'));

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

NAME
--------------------------------------------------------------------------------
VALUE
--------------------------------------------------------------------------------
<root><str>LinearRegression()</str></root>
1 row selected.

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