sqlrutils (bibliothèque R dans SQL Server)sqlrutils (R library in SQL Server)

S’APPLIQUE À : ouiSQL Server nonAzure SQL Database nonAzure Synapse Analytics (SQL DW) nonParallel Data Warehouse APPLIES TO: yesSQL Server noAzure SQL Database noAzure Synapse Analytics (SQL DW) noParallel Data Warehouse

Le package sqlrutils fournit un mécanisme permettant aux utilisateurs de R de placer leurs scripts R dans une procédure stockée T-SQL, d’inscrire cette procédure auprès d’une base de données, et d’exécuter la procédure stockée à partir d’un environnement de développement R.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.

En convertissant votre code R pour qu’il s’exécute dans une seule procédure stockée, vous pouvez utiliser plus efficacement SQL Server R Services, qui exige que le script R soit incorporé en tant que paramètre dans sp_execute_external_script.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. Le package sqlrutils vous permet de créer ce script R incorporé et de définir correctement les paramètres connexes.The sqlrutils package helps you build this embedded R script and set related parameters appropriately.

Le package sqlrutils effectue ces tâches :The sqlrutils package performs these tasks:

  • Il enregistre le script T-SQL généré sous forme de chaîne à l’intérieur d’une structure de données R.Saves the generated T-SQL script as a string inside an R data structure
  • Si vous le souhaitez, il génère un fichier .sql pour le script T-SQL, que vous pouvez modifier ou exécuter pour créer une procédure stockée.Optionally, generates a .sql file for the T-SQL script, which you can edit or run to create a stored procedure
  • Il inscrit la procédure stockée créée auprès de l’instance de SQL Server à partir de votre environnement de développement R.Registers the newly created stored procedure with the SQL Server instance from your R development environment

Vous pouvez également exécuter la procédure stockée à partir d’un environnement R, en transmettant des paramètres bien formés et en traitant les résultats.You can also execute the stored procedure from an R environment, by passing well-formed parameters and processing the results. Vous pouvez aussi utiliser la procédure stockée à partir de SQL Server pour prendre en charge des scénarios d’intégration de base de données courants comme ETL, l’apprentissage de modèle et les notations volumineuses.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.

Notes

Si vous envisagez d’exécuter la procédure stockée à partir d’un environnement R en appelant la fonction executeStoredProcedure , vous devez utiliser un fournisseur ODBC 3.8, tel que le pilote ODBC 13 pour 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.

Documentation de référence complèteFull reference documentation

La bibliothèque sqlrutils est distribuée dans plusieurs produits Microsoft, mais l’utilisation est la même que vous obteniez la bibliothèque dans SQL Server ou un autre produit.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. Étant donné que les fonctions sont les mêmes, la documentation de chaque fonction sqlrutils est publiée au même endroit sous la référence R pour Microsoft Machine Learning Server.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. Si des comportements spécifiques à un produit existent, les différences seront signalées dans la page d’aide de la fonction.Should any product-specific behaviors exist, discrepancies will be noted in the function help page.

Liste des fonctionsFunctions list

La section suivante fournit une vue d’ensemble des fonctions que vous pouvez appeler à partir du package sqlrutils pour développer une procédure stockée contenant du code R incorporé.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. Pour plus d’informations sur les paramètres de chaque méthode ou fonction, consultez l’aide de R pour le package : help(package="sqlrutils")For details of the parameters for each method or function, see the R help for the package: help(package="sqlrutils")

FonctionFunction DescriptionDescription
executeStoredProcedureexecuteStoredProcedure Exécutez une procédure stockée SQL.Execute a SQL stored procedure.
getInputParametersgetInputParameters Obtenez la liste des paramètres d’entrée vers la procédure stockée.Get a list of input parameters to the stored procedure.
InputDataInputData Définit la source de données dans SQL Server qui sera utilisée dans la trame de données R.Defines the source of data in SQL Server that will be used in the R data frame. Vous spécifiez le nom de la trame de données dans laquelle stocker les données d’entrée, et une requête pour obtenir les données ou une valeur par défaut.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. Seules les requêtes SELECT simples sont prises en charge.Only simple SELECT queries are supported.
InputParameterInputParameter Définit un seul paramètre d’entrée qui est incorporé dans le script T-SQL.Defines a single input parameter that will be embedded in the T-SQL script. Vous devez fournir le nom du paramètre et son type de données R.You must provide the name of the parameter and its R data type.
OutputDataOutputData Génère un objet de données intermédiaire qui est nécessaire si votre fonction R retourne une liste contenant une trame de données.Generates an intermediate data object that is needed if your R function returns a list that contains a data.frame. L’objet OutputData est utilisé pour stocker le nom d’une trame de données unique obtenue à partir de la liste.The OutputData object is used to store the name of a single data.frame obtained from the list.
OutputParameterOutputParameter Génère un objet de données intermédiaire qui est nécessaire si votre fonction R retourne une liste.Generates an intermediate data object that is needed if your R function returns a list. L’objet OutputParameter stocke le nom et le type de données d’un seul membre de la liste, en supposant que ce membre n’est pas une trame de données.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 Inscrivez la procédure stockée auprès d’une base de données.Register the stored procedure with a database.
setInputDataQuerysetInputDataQuery Attribuez une requête à un paramètre de données d’entrée de la procédure stockée.Assign a query to an input data parameter of the stored procedure.
setInputParameterValuesetInputParameterValue Attribuez une valeur à un paramètre d’entrée de la procédure stockée.Assign a value to an input parameter of the stored procedure.
StoredProcedureStoredProcedure Un objet de procédure stockée.A stored procedure object.

Utilisation de sqlrutilsHow to use sqlrutils

Les fonctions de la bibliothèque sqlrutils doivent s’exécuter sur un ordinateur disposant de SQL Server Machine Learning avec R. Si vous travaillez sur une station de travail cliente, définissez un contexte de calcul distant pour déplacer l’exécution vers SQL Server.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. Le workflow pour l’utilisation de ce package comprend les étapes suivantes :The workflow for using this package includes the following steps:

  • Définir des paramètres de procédure stockée (entrées, sorties ou les deux)Define stored procedure parameters (inputs, outputs, or both)
  • Générer et inscrire la procédure stockéeGenerate and register the stored procedure
  • Exécuter la procédure stockéeExecute the stored procedure

Dans une session R, chargez sqlrutils à partir de la ligne de commande en tapant library(sqlrutils).In an R session, load sqlrutils from the command line by typing library(sqlrutils).

Notes

Vous pouvez charger cette bibliothèque sur un ordinateur qui ne dispose pas de SQL Server (par exemple, sur une instance de client R) à condition de remplacer le contexte de calcul par SQL Server et d’exécuter le code dans ce contexte de calcul.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.

Définir des entrées et des paramètres de procédure stockéeDefine stored procedure parameters and inputs

StoredProcedure est le constructeur principal utilisé pour générer la procédure stockée.StoredProcedure is the main constructor used to build the stored procedure. Ce constructeur génère un objet de procédure stockée SQL Server et crée éventuellement un fichier texte contenant une requête qui peut servir à générer la procédure stockée à l’aide d’une commande T-SQL.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.

Si vous le souhaitez, la fonction StoredProcedure peut également inscrire la procédure stockée auprès de l’instance et de la base de données spécifiées.Optionally, the StoredProcedure function can also register the stored procedure with the specified instance and database.

  • Utilisez l’argument func pour spécifier une fonction R valide.Use the func argument to specify a valid R function. Toutes les variables utilisées par la fonction doivent être définies à l’intérieur de la fonction ou être fournies en tant que paramètres d’entrée.All the variables that the function uses must be defined either inside the function or be provided as input parameters. Ces paramètres peuvent inclure au plus une trame de données.These parameters can include a maximum of one data frame.

  • La fonction R doit retourner une trame de données, une liste nommée ou la valeur NULL.The R function must return either a data frame, a named list, or a NULL. Si la fonction retourne une liste, celle-ci peut contenir au plus une trame de données.If the function returns a list, the list can contain a maximum of one data.frame.

  • Utilisez l’argument spName pour spécifier le nom de la procédure stockée que vous souhaitez créer.Use the argument spName to specify the name of the stored procedure you want to create.

  • Vous pouvez transmettre des paramètres d’entrée et de sortie facultatifs, en utilisant les objets créés par ces fonctions d’assistance : setInputData, setInputParameteret setOutputParameter.You can pass in optional input and output parameters, using the objects created by these helper functions: setInputData, setInputParameter, and setOutputParameter.

  • Vous pouvez également utiliser filePath pour spécifier le chemin et le nom d’un fichier .sql à créer.Optionally, use filePath to provide the path and name of a .sql file to create. Vous pouvez exécuter ce fichier sur l’instance de SQL Server pour générer la procédure stockée à l’aide de T-SQL.You can run this file on the SQL Server instance to generate the stored procedure using T-SQL.

  • Pour définir le serveur et la base de données où sera enregistrée la procédure stockée, utilisez les arguments dbName et connectionString.To define the server and database where the stored procedure will be saved, use the arguments dbName and connectionString.

  • Pour obtenir une liste des objets InputData et InputParameter qui ont été utilisés pour créer un objet StoredProcedure spécifique, appelez getInputParameters.To get a list of the InputData and InputParameter objects that were used to create a specific StoredProcedure object, call getInputParameters.

  • Pour inscrire la procédure stockée auprès de la base de données spécifiée, utilisez registerStoredProcedure.To register the stored procedure with the specified database, use registerStoredProcedure.

Aucune donnée ou valeur n’est généralement associé à l’objet de procédure stockée, sauf si une valeur par défaut a été spécifiée.The stored procedure object typically does not have any data or values associated with it, unless a default value was specified. Les données ne sont récupérées qu’une fois que la procédure stockée est exécutée.Data is not retrieved until the stored procedure is executed.

Spécifier les entrées et exécuterSpecify inputs and execute

  • Utilisez setInputDataQuery pour assigner une requête à un objet InputParameter .Use setInputDataQuery to assign a query to an InputParameter object. Par exemple, si vous avez créé un objet de procédure stockée dans R, vous pouvez utiliser setInputDataQuery pour passer des arguments à la fonction StoredProcedure afin d’exécuter la procédure stockée avec les entrées souhaitées.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.

  • Utilisez setInputValue pour assigner des valeurs spécifiques à un paramètre stocké comme objet InputParameter .Use setInputValue to assign specific values to a parameter stored as an InputParameter object. Vous passez ensuite l’objet de paramètre et son affectation de valeur à la fonction StoredProcedure pour exécuter la procédure stockée avec les valeurs définies.You then pass the parameter object and its value assignment to the StoredProcedure function to execute the stored procedure with the set values.

  • Utilisez executeStoredProcedure pour exécuter une procédure stockée définie comme objet StoredProcedure .Use executeStoredProcedure to execute a stored procedure defined as an StoredProcedure object. Appelez cette fonction uniquement quand vous exécutez une procédure stockée à partir de code R.Call this function only when executing a stored procedure from R code. Ne l’utilisez pas quand vous exécutez la procédure stockée à partir de SQL Server à l’aide de T-SQL.Do not use it when running the stored procedure from SQL Server using T-SQL.

Notes

La fonction executeStoredProcedure nécessite un fournisseur ODBC 3.8, tel que le pilote ODBC 13 pour SQL Server.The executeStoredProcedure function requires an ODBC 3.8 provider, such as ODBC Driver 13 for SQL Server.

Voir aussiSee also

Guide pratique pour créer une procédure stockée à l’aide de sqlrutilsHow to create a stored procedure using sqlrutils