6.3 埋込みRの実行用のSQLインタフェース

Oracle R Enterpriseの埋込みRの実行用のSQLインタフェースでは、本番データベースのアプリケーションでR関数を実行できます。SQLインタフェースには、次のアクションのためのプロシージャがあります。

Oracle R EnterpriseのRスクリプト・リポジトリに対するスクリプトの追加および削除
所有者による他のユーザーに対するスクリプトへの読取りアクセス権の付与または取消し
埋込みRセッションでのRスクリプトの実行
Oracle R Enterpriseデータストアの削除

データ・ディクショナリ・ビューは、スクリプトおよびデータストアに関する情報を提供します。

このSQLインタフェースについては、次のトピックで説明しています。

6.3.1 Oracle R EnterpriseのSQL表関数について

Oracle R Enterpriseでは、埋込みRの実行用のRインタフェース関数のほとんどに相当するSQL表関数が提供されています。SELECT FROM TABLE文を実行し、いずれかの表関数を指定すると、指定されたRスクリプトが呼び出されます。このスクリプトは、Oracle Databaseサーバー上の1つ以上のRエンジンで実行されます。

埋込みRの実行用のSQL表関数は次のとおりです。

rqEval
rqGroupEval
rqRowEval
rqTableEval

表6-1に、Rインタフェース関数およびそれに相当するSQL関数を示します。

rqGroupEval関数の場合、Oracle R EnterpriseはSQLでのグループ適用機能の汎用実装を提供します。入力カーソルの後続を取得する表関数を記述する必要があります。

次の各トピックでは、SQL表関数の一般的な側面について説明します。

これらの関数の詳細および使用例は、各関数の参照ページを参照してください。

関連トピック

6.3.1.1 SQL表関数のパラメータ

SQL表関数の中には、共通のパラメータを持つものもあれば、その関数に固有のパラメータを持つものもあります。SQL表関数のパラメータは次のとおりです。

表6-2 SQL表関数のパラメータ

パラメータ	説明
`INP_CUR`	`EXP_NAM`で指定されているR関数への入力となるデータを指定するカーソル。`rqEval`を除くすべてのSQL表関数の最初の引数は、R関数の入力データを指定するカーソルです。
`PAR_CUR`	R関数に渡す引数を指定するカーソル。パラメータ・カーソルは、単一行のスカラー値で構成されます。引数には文字列または数値を指定できます。カーソル内には複数の引数を指定できます。R関数への引数では大/小文字が区別されるため、列名などの名前は二重引用符で囲む必要があります。カーソル内には、Oracle R Enterprise制御引数やシリアライズされたRオブジェクト(Oracle R Enterpriseデータストア内にある予測モデルなど)の名前をスカラー値として指定することもできます。 R関数への引数も制御引数も渡さない場合は、このパラメータ・カーソルの値を`NULL`にできます。
`OUT_QRY`	出力表の定義。この引数の値は、`NULL`か、`EXP_NAM`で指定されているR関数により返されたR `data.frame`の構造を定義する文字列にすることができます。文字列は、`SELECT`文、'XML'または'PNG'にできます。
`GRP_COL`	`rqGroupEval`関数の場合、グループ化列の名前。
`ROW_NUM`	`rqRowEval`関数の場合、R関数の各呼出しに渡す行数。
`EXP_NAM`	Oracle R EnterpriseのRスクリプト・リポジトリ内のスクリプトの名前。

関連トピック

6.3.1.2 SQL表関数の戻り値

Oracle R EnterpriseのSQL表関数は、表を返します。表の構造と内容は、SQL表関数に渡されたR関数の結果と、OUT_QRYパラメータによって決定されます。R関数はdata.frameオブジェクト、他のRオブジェクトおよびグラフィックを返すことができます。R関数の結果を表す表の構造は、次のいずれかのOUT_QRY値によって指定されます。

NULL: データ・オブジェクトとイメージ・オブジェクトの両方を含む可能性のあるシリアライズ・オブジェクトを持つ表が返されます。
SELECT文で指定された表シグネチャ: 定義された構造の表が返されます。R関数の結果はdata.frameとなる必要があります。イメージは返されません。
文字列'XML': XML文字列での構造化データとグラフ・イメージの両方を含む可能性のあるCLOBを持つ表が返されます。イメージでないRオブジェクト(data.frameやmodelオブジェクトなど)が最初に提供され、次にbase 64でエンコードされたイメージのPNG表示が続きます。
文字列'PNG': PNG形式のグラフ・イメージを含むBLOBを持つ表が返されます。表には、列名name、idおよびimageが含まれます。

6.3.1.3 埋込みRの実行でのOracle R Enterpriseへの接続

埋込みRの実行中にOracle Databaseサーバー上のOracle R Enterpriseへの接続を確立するには、パラメータ・カーソル内に制御引数ore.connectを指定できます。これを行うと、埋込みR関数を呼び出したユーザーの資格証明を使用して接続が確立されます。また、自動的にOREパッケージがロードされます。オブジェクトをOracle R EnterpriseのRオブジェクト・データストアに保存する場合や、データソースからオブジェクトをロードする場合は、Oracle R Enterpriseへの接続を確立する必要があります。また、これにより、Oracle R Enterpriseの透過層を明示的に使用できます。

6.3.2 SQLでのスクリプトの管理

このトピックでは、Rスクリプトを作成および管理するためのPL/SQLプロシージャとOracle Databaseデータ・ディクショナリ・ビューを紹介します。

埋込みRの実行用のSQL APIの関数は、Oracle R EnterpriseのRスクリプト・リポジトリに格納されている名前付きのスクリプトを引数として必要とします。PL/SQLプロシージャsys.rqScriptCreateおよびsys.rqScriptDropは、スクリプトを作成および削除します。スクリプトを作成する場合やOracle R EnterpriseのRスクリプト・リポジトリから削除する場合は、RQADMINロールが必要です。

sys.rqScriptCreate関数を使用する場合、スクリプトの名前と、1つのR関数定義を含むR関数スクリプトを指定する必要があります。関数sys.rqScriptCreateおよびsys.rqScriptDropのコールは、BEGIN-END PL/SQLブロックでラップする必要があります。Rスクリプト・リポジトリには、R関数がキャラクタ・ラージ・オブジェクト(CLOB)として格納されるため、関数定義を一重引用符で囲んで文字列として指定する必要があります。

スクリプトの所有者は、rqGrantプロシージャを使用してスクリプトへの読取りアクセス権を別のユーザーに付与したり、rqRevokeプロシージャを使用して権限を取り消すことができます。別のユーザーによってアクセス権を付与されたスクリプトを使用するには、次のように、スクリプトの名前の前に所有者の名前とピリオドを付加して、所有者を指定する必要があります。

select * from table(rqEval(NULL, 'select 1 x from dual', 'owner_name.script_name'));

パブリック・スクリプトやユーザーが所有しているスクリプトには、所有者の接頭辞は必要ありません。

次の各表は、Oracle R EnterpriseのRスクリプト・リポジトリ内のスクリプトを管理するためのPL/SQLプロシージャと、スクリプトに関する情報を格納するデータ・ディクショナリ・ビューのリストです。

表6-3 スクリプトを管理するためのPL/SQLプロシージャ

PL/SQLプロシージャ	説明
`rqGrant`	データストアまたはスクリプトへの読取りアクセス権を付与します。
`rqRevoke`	データストアまたはスクリプトへの読取りアクセス権を取り消します。
`sys.rqScriptCreate`	指定されたR関数を、指定された名前でOracle R EnterpriseのRスクリプト・リポジトリに追加します。
`sys.rqScriptDrop`	指定されたR関数をOracle R EnterpriseのRスクリプト・リポジトリから削除します。

表6-4 スクリプトのデータ・ディクショナリ・ビュー

データ・ディクショナリ・ビュー	説明
`ALL_RQ_SCRIPTS`	現行のユーザーが使用可能な、Oracle R EnterpriseのRスクリプト・リポジトリ内のスクリプトを示します。
`USER_RQ_SCRIPTS`	現行のユーザーが所有している、Oracle R EnterpriseのRスクリプト・リポジトリ内のスクリプトを示します。
`USER_RQ_SCRIPT_PRIVS`	現行のユーザーが読取りアクセス権を付与したOracle R EnterpriseのRスクリプト・リポジトリ内のスクリプトおよびアクセス権が付与されたユーザーを示します。
`SYS.RQ_SCRIPTS`	Oracle R EnterpriseのRスクリプト・リポジトリ内のシステム・スクリプトを示します。

関連トピック

6.3.2.1 SQL APIによるスクリプトの作成

この例では、sys.rqScriptCreateプロシージャを使用して、Oracle R EnterpriseのRスクリプト・リポジトリ内にスクリプトを作成します。

この例では、myRandomRedDots2という名前のユーザー定義関数を作成します。このユーザー定義関数は2つの引数を受け入れ、2つの列を持ち指定の数のランダム標準値を表示するdata.frameオブジェクトを返します。sys.rqScriptCreate関数は、ユーザー定義関数をOracle R Enterpriseのスクリプト・リポジトリに格納します。

-- Create a script named myRandomRedDots2 and add it to the R script repository.
-- Specify that the script is private and to overwrite a script with the same name.
BEGIN
  sys.rqScriptCreate('myRandomRedDots2',
    'function(divisor = 100, numDots = 100) {
       id <- 1:10
       plot(1:numDots, rnorm(numDots), pch = 21, bg = "red", cex = 2 )
       data.frame(id = id, val = id / divisor)}',
       v_global => FALSE,
       v_overwrite => TRUE);
END;
/

-- Grant read privilege access to Scott.
BEGIN
  rqGrant('myRandomRedDots2', 'rqscript', 'SCOTT');
END;
 /

-- View the users granted read access to myRandomRedDots2.
select * from USER_RQ_SCRIPT_PRIVS;

NAME                GRANTEE
----------------    -------
myRandomRedDots       SCOTT

-- Revoke the read privilege access from Scott.
BEGIN
  rqRevoke('myRandomRedDots2', 'rqscript', 'SCOTT');
END;
 /

-- Remove the script from the R script repository.
BEGIN
  sys.rqScriptDrop('myRandomRedDots2');
 END; 
 /

6.3.3 SQLでのデータストアの管理

Oracle R Enterpriseには、SQLでデータストアの基本的な管理を行うためのPL/SQLプロシージャおよびOracle Databaseデータ・ディクショナリ・ビューが用意されています。次の各表は、これらのプロシージャおよびビューのリストです。

表6-5 データストアを管理するためのPL/SQLプロシージャ

PL/SQLプロシージャ	説明
`rqGrant`	データストアまたはスクリプトへの読取りアクセス権を付与します。
`rqRevoke`	データストアまたはスクリプトへの読取りアクセス権を取り消します。
`rqDropDataStore`	データストアを削除します。

表6-6 データストアのデータ・ディクショナリ・ビュー

ビュー	説明
`ALL_RQ_DATASTORES`	データストアが付与可能かどうかを含め、現行のユーザーが使用可能なデータストアを示します。
`RQUSER_DATASTORELIST`	Oracle Databaseスキーマ内のデータストアを示します。
`RQUSER_DATASTORECONTENTS`	Oracle Databaseスキーマ内のデータストア内のオブジェクトを示します。
`USER_RQ_DATASTORE_PRIVS`	データストア、および現行のユーザーが読取りアクセス権を付与したユーザーを示します。
`USER_RQ_DATASTORES`	データストアが付与可能かどうかを含め、現行のユーザーが所有しているデータストアを示します。

関連トピック