共用方式為


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

適用於: 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 函式所建立的物件來傳入選擇性輸入和輸出參數: setInputDatasetInputParametersetOutputParameter

  • 選擇性地使用 filePath 提供要建立之 .sql 檔案的路徑和名稱。 您可以在 SQL Server 執行個體上執行這個檔案,以使用 T-SQL 產生預存程序。

  • 若要定義儲存預存程序所有的伺服器和資料庫,請使用 dbNameconnectionString引數。

  • 若要取得用來建立特定 StoredProcedure 物件的 InputDataInputParameter 物件清單,請呼叫 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 建立預存程序