sqlrutils (SQL Server Machine Learning Services の R パッケージ)

  • [アーティクル]

適用対象: SQL Server 2016 (13.x) 以降のバージョン

sqlrutils は、Microsoft が提供する R パッケージであり、R ユーザーが R スクリプトを T-SQL ストアド プロシージャに配置し、そのストアド プロシージャをデータベースに登録し、R 開発環境からそのストアド プロシージャを実行するというメカニズムを備えています。 このパッケージは、SQL Server Machine Learning Services と SQL Server 2016 R Services に含まれています。

R コードを変換して 1 つのストアド プロシージャ内で実行されるようにすると、R スクリプトが sp_execute_external_scriptへのパラメーターとして埋め込まれる必要のある SQL Server R Services をより効率的に使用できるようになります。 sqlrutils パッケージを使用すると、この組み込みの R スクリプトを構築し、関連するパラメーターを適切に設定することができます。

sqlrutils パッケージは、次を行います。

  • 生成された T-SQL スクリプトを R データ構造内に文字列として保存する
  • ストアド プロシージャを作成するために編集または実行する .sql ファイルを、必要に応じて T-SQL スクリプト用に生成する
  • 新しく作成したストアド プロシージャを R 開発環境から SQL Server インスタンスに登録できる

整形されたパラメーターを渡し、結果を処理することによって、R 環境からストアド プロシージャを実行することも可能です。 または、ETL、モデルのトレーニング、大量のスコア付けなどの一般的なデータベースの統合シナリオをサポートするよう、SQL Server からストアド プロシージャを使用することも可能です。

注意

executeStoredProcedure 関数を呼び出し、R 環境からストアド プロシージャを実行する場合、SQL Server 用 ODBC ドライバー 13 など、ODBC 3.8 プロバイダーを使用する必要があります。

完全なリファレンス ドキュメント

sqlrutils パッケージは、複数の Microsoft 製品で配布されていますが、このパッケージを SQL Server または別の製品のどちらで取得しても、使用方法は同じです。 製品固有の動作が存在する場合、関数のヘルプ ページにその相違点が示されます。

関数の一覧

次のセクションでは、sqlrutils パッケージから呼び出すことができる関数の概要を説明します。この関数を使用すると、埋め込みの R コードを含むストアド プロシージャを作成できます。 各メソッドまたは関数のパラメーターの詳細については、パッケージの R のヘルプを参照してください。 help(package="sqlrutils")

機能 説明
executeStoredProcedure SQL ストアド プロシージャを実行します。
getInputParameters ストアド プロシージャへの入力パラメーターの一覧を取得します。
InputData R データ フレームで使用されるデータ ソースを SQL Server に定義します。 入力データを保存する data.frame 名、データまたは既定値を取得するクエリを指定します。 単純な SELECT クエリのみがサポートされています。
InputParameter T-SQL スクリプトに埋め込まれる単一の入力パラメーターを定義します。 パラメーター名とその R データ型を指定する必要があります。
OutputData R 関数で data.frame を含むリストが返される場合に必要な中間のデータ オブジェクトを生成します。 OutputData オブジェクトは、リストから取得された単一の data.frame の名前を格納するために使用されます。
OutputParameter R 関数でリストが返される場合に必要な中間のデータ オブジェクトを生成します。 OutputParameter オブジェクトは、メンバーがデータ フレームでは ない ことを想定し、リストの単一のメンバーの名前とデータ型を格納します。
registerStoredProcedure ストアド プロシージャをデータベースに登録します。
setInputDataQuery ストアド プロシージャの入力データ パラメーターにクエリを割り当てます。
setInputParameterValue ストアド プロシージャの入力パラメーターに値を割り当てます。
StoredProcedure ストアド プロシージャ オブジェクト。

Sqlrutils の使用方法

sqlrutils パッケージ関数は、SQL Server Machine Learning (R 付属) を備えているコンピューターで実行する必要があります。クライアント ワークステーションで作業している場合は、リモートのコンピューティング コンテキストを設定して、実行を SQL Server に切り替えます。 このパッケージを使用するためのワークフローには、次の手順が含まれます。

  • ストアド プロシージャのパラメーター (入力、出力、またはその両方) の定義
  • ストアド プロシージャの生成と登録
  • ストアド プロシージャを実行する

R セッションで、コマンドラインから「library(sqlrutils)」と入力して sqlrutils を読み込みます。

注意

コンピューティング コンテキストを SQL Server に変更し、そのコンピューティング コンテキストでコードを実行する場合、このパッケージは SQL Server がないコンピューター (たとえば R クライアント インスタンス) に読み込むことができます。

ストアド プロシージャのパラメーターと入力の定義

StoredProcedure はストアド プロシージャの構築に使用されるメインのコンストラクターです。 このコンストラクターは、 SQL Server ストアド プロシージャ オブジェクトを生成し、オプションで T-SQL コマンドを使用したストアド プロシージャの生成に使用できるクエリを含むテキスト ファイルを作成します。

StoredProcedure 関数では、オプションで、指定したインスタンスとデータベースを使用してストアド プロシージャを登録することもできます。

  • 有効な R 関数を指定するには、 func 引数を使用します。 この関数が使用するすべての変数は、関数内に定義するか、入力パラメーターとして渡される必要があります。 これらのパラメーターには、最大でデータ フレームを 1 つ含めることが可能です。

  • R 関数は、データ フレーム、名前付きのリスト、NULL 値のいずれかを返す必要があります。 関数がリストを返す場合、リストには最大で 1 つの data.frame のみ含めることができます。

  • 作成するストアド プロシージャの名前を指定するには、 spName 引数を使用します。

  • setInputData、 setInputParameterおよび setOutputParameterのヘルパー関数によって作成されるオブジェクトを使用することにより、オプションの入力および出力パラメーターに渡すことができます。

  • 作成する .sql ファイルに名前とパスを提供する場合、オプションで filePath を使用します。 このファイルを SQL Server インスタンスで実行すると、T-SQL を使用したストアド プロシージャを生成できます。

  • ストアド プロシージャの保存先のサーバーおよびデータベースを定義するには、dbName と connectionStringの引数を使用します。

  • 特定の StoredProcedure オブジェクトを作成するのに使用された InputData と InputParameter オブジェクトのリストを取得するには、 getInputParametersを呼び出します。

  • 指定したデータベースにストアド プロシージャを登録するには、 registerStoredProcedureを使用します。

ストアド プロシージャ オブジェクトには、既定値が指定されている場合を除き、通常データや値は関連付けられていません。 ストアド プロシージャが実行されるまで、データは取得されません。

入力を指定して実行する

  • setInputDataQuery を使用して、 InputParameter オブジェクトにクエリを割り当てます。 たとえば、R でストアド プロシージャ オブジェクトを作成した場合、必要な入力を使用してストアド プロシージャを実行するには、 setInputDataQuery を使用して StoredProcedure 関数に引数を渡します。

  • setInputValue InputParameter オブジェクトとして格納されているパラメーターに特定の値を割り当てるには、 を使用します。 次に、 StoredProcedure 関数にパラメーター オブジェクトとその値の割り当てを渡し、ストアド プロシージャを設定値で実行します。

  • executeStoredProcedure StoredProcedure オブジェクトとして定義されたストアド プロシージャを実行するには、 を使用します。 この関数は、R コードからこのストアド プロシージャを実行する場合のみ呼び出します。 T-SQL を使用して SQL Server からストアド プロシージャを実行する場合は使用しないでください。

注意

executeStoredProcedure 関数には、SQL Server 用の ODBC ドライバー 13 などの ODBC 3.8 プロバイダーが必要です。

関連項目

sqlrutils を使用してストアド プロシージャを作成する方法