Démarrage rapide : Créer et exécuter des scripts R simples avec SQL Server Machine Learning ServicesQuickstart: Create and run simple R scripts with SQL Server Machine Learning Services

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

Dans ce démarrage rapide, vous allez créer et exécuter un ensemble de scripts R simples en utilisant SQL Server Machine Learning Services.In this quickstart, you'll create and run a set of simple R scripts using SQL Server Machine Learning Services. Vous allez découvrir comment encapsuler un script R bien formé dans la procédure stockée sp_execute_external_script et comment exécuter ce script dans une instance SQL Server.You'll learn how to wrap a well-formed R script in the stored procedure sp_execute_external_script and execute the script in a SQL Server instance.

Conditions préalables requisesPrerequisites

  • Ce démarrage rapide nécessite un accès à une instance de SQL Server sur laquelle SQL Server Machine Learning Services est installé avec le langage R.This quickstart requires access to an instance of SQL Server with SQL Server Machine Learning Services with the R language installed.

    Votre instance SQL Server peut se trouver sur une machine virtuelle Azure ou être locale.Your SQL Server instance can be in an Azure virtual machine or on-premises. Sachez simplement que la fonctionnalité de script externe est désactivée par défaut. Avant de commencer, vous serez donc peut-être amené à activer les scripts externes et vérifier que le service SQL Server Launchpad est en cours d’exécution.Just be aware that the external scripting feature is disabled by default, so you might need to enable external scripting and verify that SQL Server Launchpad service is running before you start.

  • Vous aurez aussi besoin d’un outil pour exécuter les requêtes SQL qui contiennent des scripts R.You also need a tool for running SQL queries that contain R scripts. Vous pouvez exécuter ces scripts à partir de n’importe quel outil de requête ou de gestion de base de données, pourvu qu’il puisse se connecter à une instance SQL Server et exécuter une requête T-SQL ou une procédure stockée.You can run these scripts using any database management or query tool, as long as it can connect to a SQL Server instance, and run a T-SQL query or stored procedure. Ce démarrage rapide utilise SQL Server Management Studio (SSMS).This quickstart uses SQL Server Management Studio (SSMS).

Exécuter un script simpleRun a simple script

Pour exécuter un script R, vous devez le transmettre sous forme d’argument à la procédure stockée système, sp_execute_external_script.To run an R script, you'll pass it as an argument to the system stored procedure, sp_execute_external_script. Cette procédure stockée système démarre le runtime R dans le contexte de SQL Server, transmet les données à R, gère les sessions utilisateur R de manière sécurisée et retourne les résultats au client.This system stored procedure starts the R runtime in the context of SQL Server, passes data to R, manages R user sessions securely, and returns any results to the client.

Dans les étapes suivantes, vous allez exécuter cet exemple de script R dans votre instance SQL Server :In the following steps, you'll run this example R script in your SQL Server instance:

a <- 1
b <- 2
c <- a/b
d <- a*b
print(c(c, d))
  1. Ouvrez SQL Server Management Studio et connectez-vous à votre instance SQL Server.Open SQL Server Management Studio and connect to your SQL Server instance.

  2. Transmettez le script R complet à la procédure stockée sp_execute_external_script.Pass the complete R script to the sp_execute_external_script stored procedure.

    Le script est transmis via l’argument @script.The script is passed through the @script argument. Tout ce qui se trouve dans l’argument @script doit être du code R valide.Everything inside the @script argument must be valid R code.

    EXECUTE sp_execute_external_script @language = N'R'
        , @script = N'
    a <- 1
    b <- 2
    c <- a/b
    d <- a*b
    print(c(c, d))
    '
    
  3. Le résultat correct est calculé et la fonction R print retourne le résultat dans la fenêtre Messages.The correct result is calculated and the R print function returns the result to the Messages window.

    Voici comment il se présente.It should look something like this.

    RésultatsResults

    STDOUT message(s) from external script:
    0.5 2
    

Exécuter un script Hello WorldRun a Hello World script

Un exemple type de script est celui qui génère simplement la chaîne « Hello World ».A typical example script is one that just outputs the string "Hello World". Exécutez la commande suivante :Run the following command.

EXECUTE sp_execute_external_script @language = N'R'
    , @script = N'OutputDataSet<-InputDataSet'
    , @input_data_1 = N'SELECT 1 AS hello'
WITH RESULT SETS(([Hello World] INT));
GO

Les entrées de la procédure stockée sp_execute_external_script sont les suivantes :Inputs to the sp_execute_external_script stored procedure include:

@language définit l’extension de langage à appeler, dans le cas présent, Rdefines the language extension to call, in this case, R
@script définit les commandes transmises au runtime R.defines the commands passed to the R runtime. Votre script R entier doit être placé dans cet argument en tant que texte Unicode.Your entire R script must be enclosed in this argument, as Unicode text. Vous pouvez aussi ajouter le texte à une variable de type nvarchar, puis appeler cette variableYou could also add the text to a variable of type nvarchar and then call the variable
@input_data_1 données retournées par la requête, transmises au runtime R, qui retourne les données à SQL Server sous forme de trame de donnéesdata returned by the query, passed to the R runtime, which returns the data to SQL Server as a data frame
WITH RESULT SETSWITH RESULT SETS la clause définit le schéma de la table de données retournée pour SQL Server, ajoutant « Hello World » comme nom de colonne, int pour le type de donnéesclause defines the schema of the returned data table for SQL Server, adding "Hello World" as the column name, int for the data type

La commande génère le texte suivant :The command outputs the following text:

Hello WorldHello World
11

Utiliser des entrées et des sortiesUse inputs and outputs

Par défaut, sp_execute_external_script accepte un seul jeu de données en entrée, que vous fournissez généralement sous forme de requête SQL valide.By default, sp_execute_external_script accepts a single dataset as input, which typically you supply in the form of a valid SQL query. Il retourne ensuite une seule trame de données R en sortie.It then returns a single R data frame as output.

Pour le moment, utilisons les variables d’entrée et de sortie par défaut de sp_execute_external_script : InputDataSet et OutputDataSet.For now, let's use the default input and output variables of sp_execute_external_script: InputDataSet and OutputDataSet.

  1. Créez une petite table de données de test.Create a small table of test data.

    CREATE TABLE RTestData (col1 INT NOT NULL)
    
    INSERT INTO RTestData
    VALUES (1);
    
    INSERT INTO RTestData
    VALUES (10);
    
    INSERT INTO RTestData
    VALUES (100);
    GO
    
  2. Utilisez l’instruction SELECT pour interroger la table.Use the SELECT statement to query the table.

    SELECT *
    FROM RTestData
    

    RésultatsResults

    Contenu de la table RTestData

  3. Exécutez le script R suivant.Run the following R script. Il récupère les données de la table en utilisant l’instruction SELECT, les transmet via le runtime R et retourne les données sous forme de trame de données.It retrieves the data from the table using the SELECT statement, passes it through the R runtime, and returns the data as a data frame. La clause WITH RESULT SETS définit le schéma de la table de données retournée pour SQL Server, ajoutant le nom de colonne NewColName.The WITH RESULT SETS clause defines the schema of the returned data table for SQL, adding the column name NewColName.

    EXECUTE sp_execute_external_script @language = N'R'
        , @script = N'OutputDataSet <- InputDataSet;'
        , @input_data_1 = N'SELECT * FROM RTestData;'
    WITH RESULT SETS(([NewColName] INT NOT NULL));
    

    RésultatsResults

    Sortie du script R qui retourne des données d’une table

  4. À présent, changeons le nom des variables d’entrée et de sortie.Now let's change the names of the input and output variables. Les variables d’entrée et de sortie se nomment par défaut InputDataSet et OutputDataSet ; ce script remplace ces noms par SQL_in et SQL_out :The default input and output variable names are InputDataSet and OutputDataSet, this script changes the names to SQL_in and SQL_out:

    EXECUTE sp_execute_external_script @language = N'R'
        , @script = N' SQL_out <- SQL_in;'
        , @input_data_1 = N' SELECT 12 as Col;'
        , @input_data_1_name = N'SQL_in'
        , @output_data_1_name = N'SQL_out'
    WITH RESULT SETS(([NewColName] INT NOT NULL));
    

    Notez que R respecte la casse.Note that R is case-sensitive. Les variables d’entrée et de sortie utilisées dans le script R (SQL_out, SQL_in) doivent correspondre aux noms définis avec @input_data_1_name et @output_data_1_name, y compris la casse.The input and output variables used in the R script (SQL_out, SQL_in) need to match the names defined with @input_data_1_name and @output_data_1_name, including case.

    Conseil

    Vous ne pouvez passer qu’un seul dataset d’entrée comme paramètre, et vous ne pouvez retourner qu’un seul dataset.Only one input dataset can be passed as a parameter, and you can return only one dataset. Toutefois, vous pouvez appeler d’autres datasets à partir de votre code R et retourner des sorties d’autres types en plus du dataset.However, you can call other datasets from inside your R code and you can return outputs of other types in addition to the dataset. Vous pouvez aussi ajouter le mot clé OUTPUT à n’importe quel paramètre pour qu’il soit retourné avec les résultats.You can also add the OUTPUT keyword to any parameter to have it returned with the results.

  5. Vous pouvez aussi générer des valeurs en utilisant simplement le script R sans données d’entrée (@input_data_1 est vide).You also can generate values just using the R script with no input data (@input_data_1 is set to blank).

    Le script suivant génère le texte « hello » et « world ».The following script outputs the text "hello" and "world".

    EXECUTE sp_execute_external_script @language = N'R'
        , @script = N'
    mytextvariable <- c("hello", " ", "world");
    OutputDataSet <- as.data.frame(mytextvariable);
    '
        , @input_data_1 = N''
    WITH RESULT SETS(([Col1] CHAR(20) NOT NULL));
    

    RésultatsResults

    Résultats de la requête en utilisant @script comme entrée

Vérifier la version de RCheck R version

Si vous voulez connaître la version de R qui est installée dans votre instance SQL Server, exécutez le script suivant.If you would like to see which version of R is installed in your SQL Server instance, run the following script.

EXECUTE sp_execute_external_script @language = N'R'
    , @script = N'print(version)';
GO

La fonction R print retourne la version dans la fenêtre Messages.The R print function returns the version to the Messages window. Dans l’exemple de sortie ci-dessous, vous pouvez voir que la version installée de R est dans ce cas la version 3.4.4.In the example output below, you can see that in this case, R version 3.4.4 is installed.

RésultatsResults

STDOUT message(s) from external script:
                   _
platform       x86_64-w64-mingw32
arch           x86_64
os             mingw32
system         x86_64, mingw32
status
major          3
minor          4.4
year           2018
month          03
day            15
svn rev        74408
language       R
version.string R version 3.4.4 (2018-03-15)
nickname       Someone to Lean On

Lister les packages RList R packages

Microsoft fournit un certain nombre de packages R préinstallés avec SQL Server Machine Learning Services.Microsoft provides a number of R packages pre-installed with SQL Server Machine Learning Services.

Pour afficher la liste des packages R installés, dont la version, les dépendances, la licence et le chemin de la bibliothèque, exécutez le script suivant.To see a list of which R packages are installed, including version, dependencies, license, and library path information, run the following script.

EXEC sp_execute_external_script @language = N'R'
    , @script = N'
OutputDataSet <- data.frame(installed.packages()[,c("Package", "Version", "Depends", "License", "LibPath")]);'
WITH result sets((
            Package NVARCHAR(255)
            , Version NVARCHAR(100)
            , Depends NVARCHAR(4000)
            , License NVARCHAR(1000)
            , LibPath NVARCHAR(2000)
            ));

La sortie provient de installed.packages() dans R et est retournée sous forme de jeu de résultats.The output is from installed.packages() in R and is returned as a result set.

RésultatsResults

Packages installés dans R

Étapes suivantesNext steps

Pour savoir comment utiliser des structures de données quand R est utilisé dans SQL Server Machine Learning Services, suivez ce démarrage rapide :To learn how to use data structures when using R in SQL Server Machine Learning Services, follow this quickstart:

Pour plus d’informations sur l’utilisation de R dans SQL Server Machine Learning Services, consultez les articles suivants :For more information on using R in SQL Server Machine Learning Services, see the following articles: