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 からストアド プロシージャを使用することも可能です。

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

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

関数の一覧

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

Sqlrutils の使用方法

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

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

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

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

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 からストアド プロシージャを実行する場合は使用しないでください。

関連項目

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