sqlrutils (R-Bibliothek in SQL Server)sqlrutils (R library in SQL Server)

Gilt für: JaSQL Server NeinAzure SQL-Datenbank NeinAzure Synapse Analytics (SQL DW) NeinParallel Data Warehouse APPLIES TO: yesSQL Server noAzure SQL Database noAzure Synapse Analytics (SQL DW) noParallel Data Warehouse

Das sqlrutils -Paket bietet einen Mechanismus, mit dem R-Benutzer ihre R-Skripts in eine gespeicherte T-SQL-Prozedur einbinden, diese gespeicherte Prozedur für eine Datenbank registrieren und die gespeicherte Prozedur aus einer R-Entwicklungsumgebung ausführen können.The sqlrutils package provides a mechanism for R users to put their R scripts into a T-SQL stored procedure, register that stored procedure with a database, and run the stored procedure from an R development environment.

Durch Konvertieren Ihres R-Codes, sodass er in einer einzelnen gespeicherten Prozedur ausgeführt wird, können Sie SQL Server R Services effektiver nutzen, wozu es erforderlich ist, dass das R-Skript als Parameter für sp_execute_external_scripteingebettet wird.By converting your R code to run within a single stored procedure, you can make more effective use of SQL Server R Services, which requires that R script be embedded as a parameter to sp_execute_external_script. Das sqlrutils -Paket unterstützt Sie dabei, dieses eingebettete R-Skript zu erstellen und zugehörige Parameter entsprechend festzulegen.The sqlrutils package helps you build this embedded R script and set related parameters appropriately.

Das sqlrutils -Paket führt die folgenden Aufgaben aus:The sqlrutils package performs these tasks:

  • Es speichert das generierte T-SQL-Skript als Zeichenfolge in einer R-Datenstruktur.Saves the generated T-SQL script as a string inside an R data structure
  • Es generiert optional eine SQL-Datei für das T-SQL-Skript, die Sie bearbeiten oder ausführen können, um eine gespeicherte Prozedur zu erstellen.Optionally, generates a .sql file for the T-SQL script, which you can edit or run to create a stored procedure
  • Es registriert die neu erstellte gespeicherte Prozedur für die SQL Server-Instanz aus Ihrer R-Entwicklungsumgebung.Registers the newly created stored procedure with the SQL Server instance from your R development environment

Sie können die gespeicherte Prozedur auch aus einer R-Umgebung ausführen, indem Sie wohlgeformte Parameter übergeben und die Ergebnisse verarbeiten.You can also execute the stored procedure from an R environment, by passing well-formed parameters and processing the results. Oder Sie können die gespeicherte Prozedur aus SQL Server verwenden, um allgemeine Datenbankintegrationsszenarios wie ETL, Modelltraining und Massenbewertung zu unterstützen.Or, you can use the stored procedure from SQL Server to support common database integration scenarios such as ETL, model training, and high-volume scoring.

Hinweis

Wenn Sie beabsichtigen, die gespeicherte Prozedur aus einer R-Umgebung auszuführen, indem Sie die executeStoredProcedure -Funktion aufrufen, müssen Sie einen ODBC 3.8-Anbieter verwenden, z.B. ODBC Driver 13 for SQL Server.If you intend to run the stored procedure from an R environment by calling the executeStoredProcedure function, you must use an ODBC 3.8 provider, such as ODBC Driver 13 for SQL Server.

Vollständige ReferenzdokumentationFull reference documentation

Die sqlrutils-Bibliothek wird in mehreren Microsoft-Produkten bereitgestellt. Die Verwendung ist jedoch immer identisch, unabhängig davon, ob Sie die Bibliothek in SQL Server oder einem anderen Produkt abrufen.The sqlrutils library is distributed in multiple Microsoft products, but usage is the same whether you get the library in SQL Server or another product. Aus diesem Grund wird die Dokumentation für einzelne sqlrutils-Funktionen nur an einer Stelle in der R-Referenz für Microsoft Machine Learning Server veröffentlicht.Because the functions are the same, documentation for individual sqlrutils functions is published to just one location under the R reference for Microsoft Machine Learning Server. Abweichungen durch produktspezifisches Verhalten finden Sie ggf. auf der Hilfeseite der Funktion.Should any product-specific behaviors exist, discrepancies will be noted in the function help page.

FunktionslisteFunctions list

Der folgende Abschnitt bietet eine Übersicht über die Funktionen, die Sie aus dem sqlrutils-Paket aufrufen können, um eine gespeicherte Prozedur mit eingebettetem R-Code zu entwickeln.The following section provides an overview of the functions that you can call from the sqlrutils package to develop a stored procedure containing embedded R code. Weitere Informationen über die Parameter für jede Methode oder Funktion finden Sie in der R-Hilfe für das Paket: help(package="sqlrutils")For details of the parameters for each method or function, see the R help for the package: help(package="sqlrutils")

FunktionFunction BESCHREIBUNGDescription
executeStoredProcedureexecuteStoredProcedure Führt eine gespeicherte Prozedur aus.Execute a SQL stored procedure.
getInputParametersgetInputParameters Ruft eine Liste der Eingabeparameter in der gespeicherten Prozedur ab.Get a list of input parameters to the stored procedure.
InputDataInputData Definiert die Datenquelle in SQL Server, die in dem R-Datenrahmen verwendet wird.Defines the source of data in SQL Server that will be used in the R data frame. Sie geben den Namen des Datenrahmens (data.frame), in dem die Eingabedaten gespeichert werden sollen, und eine Abfrage, mit der die Daten abgerufen werden, oder einen Standardwert an.You specify the name of the data.frame in which to store the input data, and a query to get the data, or a default value. Es werden nur einfache SELECT-Abfragen unterstützt.Only simple SELECT queries are supported.
InputParameterInputParameter Definiert einen einzelnen Eingabeparameter, der in das T-SQL-Skript eingebettet wird.Defines a single input parameter that will be embedded in the T-SQL script. Sie müssen den Namen des Parameters und dessen R-Datentyp angeben.You must provide the name of the parameter and its R data type.
OutputDataOutputData Generiert ein Zwischendatenobjekt, das erforderlich ist, wenn Ihre R-Funktion eine Liste zurückgibt, die einen Datenrahmen (data.frame) enthält.Generates an intermediate data object that is needed if your R function returns a list that contains a data.frame. Das OutputData -Objekt wird verwendet, um den Namen eines einzelnen „data.frame“ zu speichern, das aus der Liste abgerufen wurde.The OutputData object is used to store the name of a single data.frame obtained from the list.
OutputParameterOutputParameter Generiert ein Zwischendatenobjekt, das erforderlich ist, wenn Ihre R-Funktion eine Liste zurückgibt.Generates an intermediate data object that is needed if your R function returns a list. Im OutputParameter -Objekt werden der Name und der Datentyp eines einzelnen Elements der Liste gespeichert, wobei vorausgesetzt wird, dass das Element kein Datenrahmen ist.The OutputParameter object stores the name and data type of a single member of the list, assuming that member is not a data frame.
registerStoredProcedureregisterStoredProcedure Registriert die gespeicherte Prozedur bei einer Datenbank.Register the stored procedure with a database.
setInputDataQuerysetInputDataQuery Weist einem Eingabedatenparameter der gespeicherten Prozedur eine Abfrage zu.Assign a query to an input data parameter of the stored procedure.
setInputParameterValuesetInputParameterValue Weist einem Eingabeparameter der gespeicherten Prozedur einen Wert zu.Assign a value to an input parameter of the stored procedure.
StoredProcedureStoredProcedure Ein gespeichertes Prozedurobjekt.A stored procedure object.

Verwenden von sqlrutilsHow to use sqlrutils

Die sqlrutils-Bibliotheksfunktionen müssen auf einem Computer mit SQL Server Machine Learning mit R ausgeführt werden. Wenn Sie auf einem Clientcomputer arbeiten, legen Sie einen Remotecomputekontext fest, um die Ausführung auf die SQL Server-Instanz zu verschieben.The sqlrutils library functions must run on a computer having SQL Server Machine Learning with R. If you are working on a client workstation, set a remote compute context to shift execution to SQL Server. Der Workflow für die Verwendung dieses Pakets umfasst die folgenden Schritte:The workflow for using this package includes the following steps:

  • Definieren der Parameter (Eingaben, Ausgaben oder beides) einer gespeicherten ProzedurDefine stored procedure parameters (inputs, outputs, or both)
  • Generieren und Registrieren der gespeicherten ProzedurGenerate and register the stored procedure
  • Ausführen der gespeicherten ProzedurExecute the stored procedure

Laden Sie in einer R-Sitzung sqlrutils über die Befehlszeile, indem Sie library(sqlrutils) eingeben.In an R session, load sqlrutils from the command line by typing library(sqlrutils).

Hinweis

Sie können diese Bibliothek auf einen Computer ohne SQL Server laden (z. B. auf einer R-Clientinstanz), wenn Sie den Computekontext in SQL Server ändern und den Code in diesem Computekontext ausführen.You can load this library on computer that does not have SQL Server (for example, on an R Client instance) if you change the compute context to SQL Server and execute the code in that compute context.

Definieren der Parameter und Eingaben einer gespeicherten ProzedurDefine stored procedure parameters and inputs

StoredProcedure ist der Hauptkonstruktor, der zum Erstellen der gespeicherten Prozedur verwendet wird.StoredProcedure is the main constructor used to build the stored procedure. Dieser Konstruktor generiert eine gespeicherte Prozedur als SQL Server-Objekt und erstellt optional eine Textdatei, die eine Abfrage enthält, die dazu verwendet werden kann, die gespeicherte Prozedur mit einem T-SQL-Befehl zu generieren.This constructor generates a SQL Server Stored Procedure object, and optionally creates a text file containing a query that can be used to generate the stored procedure using a T-SQL command.

Außerdem kann die StoredProcedure -Funktion dazu verwendet werden, die gespeicherte Prozedur für die angegebene Instanz und Datenbank zu registrieren.Optionally, the StoredProcedure function can also register the stored procedure with the specified instance and database.

  • Verwenden Sie das func Argument, um eine gültige R-Funktion anzugeben.Use the func argument to specify a valid R function. Alle Variablen, die in der Funktion verwendet werden, müssen entweder innerhalb der Funktion definiert sein oder als Eingabeparameter bereitgestellt werden.All the variables that the function uses must be defined either inside the function or be provided as input parameters. Diese Parameter können maximal einen Datenrahmen enthalten.These parameters can include a maximum of one data frame.

  • Die R-Funktion muss entweder einen Datenrahmen, eine benannte Liste oder NULL zurückgeben.The R function must return either a data frame, a named list, or a NULL. Gibt die Funktion eine Liste zurück, darf die Liste maximal einen Datenrahmen (data.frame) enthalten.If the function returns a list, the list can contain a maximum of one data.frame.

  • Verwenden Sie das Argument spName , um den Namen der zu erstellenden gespeicherten Prozedur anzugeben.Use the argument spName to specify the name of the stored procedure you want to create.

  • Sie können optionale Eingabe- und Ausgabeparameter mithilfe der Objekte übergeben, die mit diesen Hilfsfunktionen erstellt wurden: setInputData, setInputParameterund setOutputParameter.You can pass in optional input and output parameters, using the objects created by these helper functions: setInputData, setInputParameter, and setOutputParameter.

  • Verwenden Sie optional filePath , um den Pfad und den Namen der zu erstellenden SQL-Datei bereitzustellen.Optionally, use filePath to provide the path and name of a .sql file to create. Sie können diese Datei für die SQL Server-Instanz ausführen, um die gespeicherte Prozedur mit T-SQL zu generieren.You can run this file on the SQL Server instance to generate the stored procedure using T-SQL.

  • Um den Server und die Datenbank festzulegen, in der die gespeicherte Prozedur gespeichert werden soll, verwenden Sie die Argumente dbName und connectionString.To define the server and database where the stored procedure will be saved, use the arguments dbName and connectionString.

  • Wenn Sie eine Liste des InputData - und des InputParameter -Objekts abrufen möchten, die zum Erstellen eines bestimmten StoredProcedure -Objekts verwendet wurden, rufen Sie getInputParametersauf.To get a list of the InputData and InputParameter objects that were used to create a specific StoredProcedure object, call getInputParameters.

  • Um die gespeicherte Prozedur für die angegebene Datenbank zu registrieren, verwenden Sie registerStoredProcedure.To register the stored procedure with the specified database, use registerStoredProcedure.

Dem Objekt für die gespeicherte Prozedur sind üblicherweise weder Daten noch Werte zugeordnet, es sei denn, es wurde ein Standardwert angegeben.The stored procedure object typically does not have any data or values associated with it, unless a default value was specified. Daten werden erst abgerufen, wenn die gespeicherte Prozedur ausgeführt wird.Data is not retrieved until the stored procedure is executed.

Angeben von Eingaben und AusführenSpecify inputs and execute

  • Verwenden Sie setInputDataQuery , um einem InputParameter -Objekt eine Abfrage zuzuweisen.Use setInputDataQuery to assign a query to an InputParameter object. Wenn Sie beispielsweise ein Objekt für die gespeicherte Prozedur in R erstellt haben, können Sie setInputDataQuery verwenden, um Argumente an die StoredProcedure -Funktion zu übergeben, damit die gespeicherte Prozedur mit den gewünschten Eingaben ausgeführt wird.For example, if you have created a stored procedure object in R, you can use setInputDataQuery to pass arguments to the StoredProcedure function in order to execute the stored procedure with the desired inputs.

  • Verwenden Sie setInputValue , wenn Sie einem Parameter, der als ein InputParameter -Objekt gespeichert ist, bestimmte Werte zuweisen möchten.Use setInputValue to assign specific values to a parameter stored as an InputParameter object. Sie können dann das Parameterobjekt und dessen Wertzuweisung an die StoredProcedure -Funktion übergeben, um die gespeicherte Prozedur mit den festgelegten Werten auszuführen.You then pass the parameter object and its value assignment to the StoredProcedure function to execute the stored procedure with the set values.

  • Verwenden Sie executeStoredProcedure , wenn Sie eine gespeicherte Prozedur ausführen möchten, die als ein StoredProcedure -Objekt definiert ist.Use executeStoredProcedure to execute a stored procedure defined as an StoredProcedure object. Rufen Sie diese Funktion nur auf, wenn Sie eine gespeicherte Prozedur aus R-Code ausführen.Call this function only when executing a stored procedure from R code. Verwenden Sie diese Funktion nicht, wenn Sie die gespeicherte Prozedur aus SQL Server mithilfe von T-SQL ausführen.Do not use it when running the stored procedure from SQL Server using T-SQL.

Hinweis

Die executeStoredProcedure -Funktion erfordert einen ODBC 3.8-Anbieter, z.B. ODBC Driver 13 for SQL Server.The executeStoredProcedure function requires an ODBC 3.8 provider, such as ODBC Driver 13 for SQL Server.

Weitere InformationenSee also

Erstellen einer gespeicherten Prozedur mithilfe von sqlrutilsHow to create a stored procedure using sqlrutils