sqlrutils (SQL Server 機器學習服務中的 R 套件)

發行項
05/04/2023

適用於： SQL Server 2016 (13.x) 和更新版本

sqlrutils 是來自 Microsoft 的 R 套件，其提供一種機制，讓 R 使用者將其 R 指令碼放入 T-SQL 預存程序、註冊具有資料庫的這個預存程序，以及從 R 開發環境執行預存程序。該套件包含在 SQL Server 機器學習服務與 SQL Server 2016 R Services 中。

轉換 R 程式碼以在單一預存程序內執行，即可更有效地使用 SQL Server R Services，而這需要將 R 指令碼內嵌為 sp_execute_external_script的參數。 sqlrutils 套件可協助您建置此內嵌 R 指令碼，並適當地設定相關參數。

sqlrutils 套件可執行這些工作︰

將產生的 T-SQL 指令碼儲存為 R 資料結構內的字串
選擇性地產生 T-SQL 指令碼的 .sql 檔案，可對其進行編輯或執行以建立預存程序
從 R 開發環境中註冊具有 SQL Server 執行個體的新建立預存程序

傳遞格式正確的參數，並處理結果，也可以從 R 環境執行預存程序。或者，您可以使用來自 SQL Server 的預存程序支援一般資料庫整合案例 (例如 ETL、模型訓練和高容量評分)。

注意

如果您想要呼叫 executeStoredProcedure 函式以從 R 環境執行預存程序，則必須使用 ODBC 3.8 提供者 (例如適用於 SQL Server 的 ODBC Driver 13)。

完整參考文件

sqlrutils 套件分散在多個 Microsoft 產品中，但不論是在 SQL Server 或其他產品中取得該套件，其使用方式都相同。若有任何產品特定行為存在，函式說明頁面中將會註明不一致之處。

函式清單

下節概述您可從 sqlrutils 套件呼叫的函式，用以開發包含內嵌 R 程式碼的預存程序。如需每個方法或函式的參數詳細資訊，請參閱套件的 R 說明：help(package="sqlrutils")

函式	說明
executeStoredProcedure	執行 SQL 預存程序。
getInputParameters	取得預存程序的輸入參數清單。
InputData	定義 SQL Server 中將用於 R 資料框架的資料來源。您可以指定用來儲存輸入資料的 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 機器學習服務 (包含 R) 的電腦上執行。如果您是在用戶端工作站上工作，請設定遠端計算內容，以將執行轉移至 SQL Server。使用此套件的工作流程包含下列步驟：

定義預存程序參數 (輸入、輸出或這兩者)
產生並註冊預存程序
執行預存程序

在 R 工作階段中，從命令列鍵入 library(sqlrutils)，以載入 sqlrutils。

注意

如果將計算內容變更為 SQL Server 並執行該計算內容中的程式碼，則可在沒有 SQL Server 的電腦上載入此套件 (例如，在 R Client 執行個體上)。

定義預存程序參數和輸入

StoredProcedure 是用來建置預存程序的主要建構函式。這個建構函式會產生「SQL Server 預存程序」物件，並選擇性地建立文字檔，其中包含可用來產生使用 T-SQL 命令之預存程序的查詢。

選擇性， StoredProcedure 函式也可以註冊具有所指定執行個體和資料庫的預存程序。

使用 func 引數來指定有效的 R 函式。函式所使用的所有變數都必須定義在函式內部，或提供為輸入參數。這些參數最多可以包含一個資料框架。
R 函式必須傳回資料框架、具名清單或 NULL。如果函式傳回清單，則清單最多可以包含一個 data.frame。
使用引數 spName 指定您要建立之預存程序的名稱。
您可以使用這些 helper 函式所建立的物件來傳入選擇性輸入和輸出參數： setInputData、 setInputParameter和 setOutputParameter。
選擇性地使用 filePath 提供要建立之 .sql 檔案的路徑和名稱。您可以在 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 函式需要 ODBC 3.8 提供者 (例如適用於 SQL Server 的 ODBC Driver 13)。

另請參閱

如何使用 sqlrutils 建立預存程序

共用方式為