11.7.5 出力形式(Autonomous Database)
OUT_FMTパラメータは、表ファンクションpyqEval、pyqGroupEval、pyqIndexEval、pyqRowEval、pyqTableEvalおよびpyqJobResultによって返される出力の形式を制御します。
出力形式は次のとおりです。
JSON
OUT_FMTがJSONに設定されている場合、表ファンクションは、JSON文字列であるCLOBが含まれる表を返します。
次の例では、pyqEvalファンクションに関する項で作成された'pyqFun1'でpyqEvalファンクションを呼び出します。
SQL> select *
from table(pyqEval(
par_lst => '{"oml_service_level":"MEDIUM"}',
out_fmt => 'JSON',
scr_name => 'pyqFun1'));
NAME
----------------------------------------------------------------------
VALUE
----------------------------------------------------------------------
[{"FLOAT":0,"ID":0,"NAME":"demo_0"},{"FLOAT":0.1,"ID":1,"NAME":"demo_1
"},{"FLOAT":0.2,"ID":2,"NAME":"demo_2"},{"FLOAT":0.3,"ID":3,"NAME":"de
mo_3"},{"FLOAT":0.4,"ID":4,"NAME":"demo_4"},{"FLOAT":0.5,"ID":5,"NAME"
:"demo_5"},{"FLOAT":0.6,"ID":6,"NAME":"demo_6"},{"FLOAT":0.7,"ID":7,"N
AME":"demo_7"},{"FLOAT":0.8,"ID":8,"NAME":"demo_8"},{"FLOAT":0.9,"ID":
9,"NAME":"demo_9"}]
1 row selected.リレーショナル
列名が列タイプにマップされるJSON文字列でOUT_FMTが指定されている場合、表ファンクションはそれを表の列に再形成してレスポンスを返します。
たとえば、{"NAME":"varchar2(7)", "DIFF":"number"}でOUT_FMTが指定されている場合、出力にはVARCHAR2(7)型のNAME列およびNUMBER型のDIFF列が含まれています。次の例では、表GRADEおよびスクリプト'computeGradeDiff' (「非同期ジョブ(Autonomous Database)」で作成)を使用し、computeGradeDiff関数を呼び出します。
SQL> select *
from table(pyqTableEval(
inp_nam => 'GRADE',
par_lst => '{"oml_input_type":"pandas.DataFrame"}',
out_fmt => '{"NAME":"varchar2(7)","DIFF":"number"}',
scr_name => 'computeGradeDiff'));NAME DIFF
------- ----------
Abbott 3
Branfor -5
Crandel 10
Denniso 13
Edgar 9
Faust 5
Greeley -9
Hart 4
Isley 2
Jasper 8
10 rows selected.XML
XMLでOUT_FMTが指定されている場合、表ファンクションは固定列が含まれる表でレスポンスを返します。出力は、2つの列で構成されています。NAME列には、行の名前が示されます。pyqEval、pyqTableEvalおよびpyqRowEvalファンクションが返す場合、NAME列値はNULLです。pyqGroupEval、pyqIndexEvalの場合、NAME列値はグループ/索引名です。VALUE列には、XML文字列が示されます。
XMLには構造化データとイメージの両方が含まれる可能性があり、最初に構造化または半構造化のPythonオブジェクトが含まれ、続いてPython関数によって生成されたイメージが含まれます。イメージはPNG表示のbase 64エンコーディングとして返されます。XML文字列にイメージを含めるには、特殊な制御引数oml_graphics_flagをtrueに設定する必要があります。
次のコードでは、Python関数gen_two_imagesが定義され、plotTwoImagesという名前でスクリプト・リポジトリに格納されます。この関数は、赤色と青色のランダムなドットで2つのサブプロットをレンダリングし、入力データの列数を返します。
begin
sys.pyqScriptCreate('plotTwoImages','def gen_two_images (dat):
import numpy as np
import matplotlib.pyplot as plt
np.random.seed(22)
fig = plt.figure(1);
fig2 = plt.figure(2);
ax = fig.add_subplot(111);
ax.set_title("Random red dots")
ax2 = fig2.add_subplot(111);
ax2.set_title("Random blue dots")
ax.plot(range(100), np.random.normal(size=100), marker = "o",
color = "red", markersize = 2)
ax2.plot(range(100,0,-1), marker = "o", color = "blue", markersize = 2)
return dat.shape[1]
',FALSE,TRUE);
end;
/次の例は、構造化データとイメージの両方が結果に含まれるpyqRowEvalファンクション・コールのXML出力を示しています。
SQL> select *
from table(pyqRowEval(
inp_nam => 'GRADE',
par_lst => '{"oml_graphics_flag":true}',
out_fmt => 'XML',
row_num => 5,
scr_name => 'plotTwoImages'
));NAME
--------------------------------------------------------------------------------
VALUE
----------------------------------------------------------------------
1
<root><Py-data><int>7</int></Py-data><images><image><img src="data:ima
ge/pngbase64"><![CDATA[iVBORw0KGgoAAAANSUhEUgAAAoAAAAHgCAYAAAA10dzkAAA
ABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAPYQAAD2EBqD+naQAAADh0RVh0U29mdHdhcmUAb
WF0cGxvdGxpYiB2ZXJzaW9uMy4xLjIsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy8li6FKAAA
gAElEQVR4nOydeZwcVb32n549k0xCSMhGEohhEZFNUAEBE0UUIYOACG4gFxWvgGzqldf3s
lz1xYuKLBe3i7LcNyhctoxsviCJoAQFNAKCCLITQyCQbZJMZqb
2
<root><Py-data><int>7</int></Py-data><images><image><img src="data:ima
ge/pngbase64"><![CDATA[iVBORw0KGgoAAAANSUhEUgAAAoAAAAHgCAYAAAA10dzkAAA
ABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAPYQAAD2EBqD+naQAAADh0RVh0U29mdHdhcmUAb
WF0cGxvdGxpYiB2ZXJzaW9uMy4xLjIsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy8li6FKAAA
gAElEQVR4nOydeZwcVb32n549k0xCSMhGEohhEZFNUAEBE0UUIYOACG4gFxWvgGzqldf3s
lz1xYuKLBe3i7LcNyhctoxsviCJoAQFNAKCCLITQyCQbZJMZqb
2 rows selectedPNG
PNGでOUT_FMTが指定されている場合、表ファンクションは固定列(イメージ・バイト列を含む)が含まれる表でレスポンスを返します。SQL APIをコールする場合、実行されたスクリプトでレンダリングされたイメージをWebサーバーが取得できるように、特殊な制御引数oml_graphics_flagをtrueに設定する必要があります。
PNG出力は、次の4つの列で構成されています。NAME列には、行の名前が示されます。pyqEvalおよびpyqTableEvalファンクションが返す場合、NAME列値はNULLです。pyqRowEval、pyqGroupEval、pyqIndexEvalの場合、NAME列値はチャンク/グループ/索引名です。ID列には、イメージのIDが示されます。VALUE列には、実行されたスクリプトの戻り値が示されます。TITLE列には、レンダリングされたPNGイメージのタイトルが示されます。IMAGE列は、実行されたスクリプトによってレンダリングされたPNGイメージのバイトが含まれるBLOB列です。
次の例は、pyqRowEvalファンクション・コールのPNG出力を示しています。
SQL> column name format a7
column valueformat a5
column title format a16
column image format a15
select *
from table(pyqRowEval(
inp_nam => 'GRADE',
par_lst => '{"oml_graphics_flag":true}',
out_fmt => 'PNG',row_num => 5,
scr_name => 'plotTwoImages',
scr_owner =>NULL
));NAME ID VALUE TITLE IMAGE
-------- --------- ----- ---------------- ---------------
CHUNK_1 1 7 Random red dots 6956424F5277304
B47676F41414141
4E5355684555674
141416F41414141
486743415941414
1413130647A6B41
41414142484E435
356514943416749
6641686B6941414
141416C7753466C
7A41414150
CHUNK_1 2 7 Random blue dots 6956424F5277304
B47676F41414141
4E5355684555674
141416F41414141
486743415941414
1413130647A6B41
41414142484E435
356514943416749
6641686B6941414
141416C7753466C
7A41414150
CHUNK_2 1 7 Random red dots 6956424F5277304
B47676F41414141
4E5355684555674
141416F41414141
486743415941414
1413130647A6B41
41414142484E435
356514943416749
6641686B6941414
141416C7753466C
7A41414150
CHUNK_2 2 7 Random blue dots 6956424F5277304
B47676F41414141
4E5355684555674
141416F41414141
486743415941414
1413130647A6B41
41414142484E435
356514943416749
6641686B6941414
141416C7753466C
7A41414150
4 rows selected.非同期モード出力
非同期ジョブを実行するためにoml_async_flagをtrueに設定する場合は、次に示すように、XML以外の結果を返すジョブに対してはOUT_FMTをNULLに設定するか、XML結果を返すジョブに対してはXMLに設定します。
「oml_async_flag引数」も参照してください。
非同期モード: XML以外の出力
非同期ジョブを発行する際、JSON、PNGおよびリレーショナル出力の場合は、ジョブの発行時にOUT_FMTをNULLに設定します。ジョブ結果をフェッチする際は、pyqJobResultコールでOUT_FMTを指定します。
次の例は、非同期pyqIndexEvalファンクション・コールからJSON出力を取得する方法を示しています。
SQL> select *
from table(pyqGroupEval(
inp_nam => 'GRADE',
par_lst => '{"oml_async_flag":true, "oml_graphics_flag":true}',
out_fmt => NULL,
grp_col => 'GENDER',
ord_col => NULL,
scr_name => 'inp_twoimgs',
scr_owner => NULL
));NAME
--------------------------------------------------------------------
VALUE
--------------------------------------------------------------------
https://<host name>/oml/tenants/<tenant name>/databases/<database
name>/api/py-scripts/v1/jobs/<job id>
1 row selected.SQL> select * from pyqJobStatus(
job_id => '<job id>');NAME
--------------------------------------------------------------------
VALUE
--------------------------------------------------------------------
https://<host name>/oml/tenants/<tenant name>/databases/<database
name>/api/py-scripts/v1/jobs/<job id>/result
1 row selected.SQL> column name format a7
column value format a5
column title format a16
column image format a15
select * from pyqJobResult(
job_id => '<job id>',
out_fmt => 'PNG'
);NAME ID VALUE TITLE IMAGE
------- ---------- ----- ---------------- ---------------
GROUP_F 1 7 Random red dots 6956424F5277304
B47676F41414141
4E5355684555674
141416F41414141
486743415941414
1413130647A6B41
41414142484E435
356514943416749
6641686B6941414
141416C7753466C
7A4141415059514
141443245427144
2B6E61514141414
468305256683055
32396D644864686
36D554162574630
634778766447787
0596942325A584A
7A615739754D793
4784C6A49734947
GROUP_F 2 7 Random blue dots 6956424F5277304
B47676F41414141
4E5355684555674
141416F41414141
486743415941414
1413130647A6B41
41414142484E435
356514943416749
6641686B6941414
141416C7753466C
7A4141415059514
141443245427144
2B6E61514141414
468305256683055
32396D644864686
36D554162574630
634778766447787
0596942325A584A
7A615739754D793
4784C6A49734947
GROUP_M 1 7 Random red dots 6956424F5277304
B47676F41414141
4E5355684555674
141416F41414141
486743415941414
1413130647A6B41
41414142484E435
356514943416749
6641686B6941414
141416C7753466C
7A4141415059514
141443245427144
2B6E61514141414
468305256683855
32396D644864686
36D554162574630
634778766447787
0596942325A584A
7A615739754D793
4784C6A49734947
GROUP_M 2 7 Random blue dots 6956424F5277304
B47676F41414141
4E5355684555674
141416F41414141
486743415941414
1413130647A6B41
41414142484E435
356514943416749
6641686B6941414
141416C7753466C
7A4141415059514
141443245427144
2B6E61514141414
468305256683055
32396D644864686
36D554162574630
634778766447787
0596942325A584A
7A615739754D793
4784C6A49734947
4 rows selected非同期モード: XML出力
非同期ジョブからXML出力が想定される場合は、ジョブの発行時とジョブ結果のフェッチ時に、OUT_FMTをXMLに設定する必要があります。
次の例は、非同期pyqIndexEvalファンクション・コールからXML出力を取得する方法を示しています。
SQL> select *
from table(pyqIndexEval(
par_lst => '{"oml_async_flag":true}',
out_fmt => 'XML',
times_num => 3,
scr_name => 'idx_ret_df',
scr_owner => NULL
));NAME
--------------------------------------------------------------------------------
VALUE
--------------------------------------------------------------------------------
https://<host name>/oml/tenants/<tenant name>/databases/<database
name>/api/py-scripts/v1/jobs/<job id>
1 row selected.SQL> select * from pyqJobStatus(
job_id => '<job id>'
); 2
NAME
--------------------------------------------------------------------------------
VALUE
--------------------------------------------------------------------------------
https://<host name>/oml/tenants/<tenant name>/databases/<database
name>/api/py-scripts/v1/jobs/<job id>/result
1 row selected.SQL> select * from pyqJobResult(
job_id => '<job id>',
out_fmt => 'XML'
); 2 3 4
NAME
--------------------------------------------------------------------------------
VALUE
--------------------------------------------------------------------------------
1
<root><pandas_dataFrame><ROW-
pandas_dataFrame><ID>1</ID><RES>a</RES></ROW-pandas
_dataFrame></pandas_dataFrame></root>
2
<root><pandas_dataFrame><ROW-
pandas_dataFrame><ID>2</ID><RES>b</RES></ROW-pandas
_dataFrame></pandas_dataFrame></ro
3
<root><pandas_dataFrame><ROW-
pandas_dataFrame><ID>3</ID><RES>c</RES></ROW-pandas
_dataFrame></pandas_dataFrame></root>
3 rows selected