Plug-in R (préversion)

Le plug-in R exécute une fonction définie par l’utilisateur (UDF) à l’aide d’un script R.

Le script obtient des données tabulaires comme entrée et produit une sortie tabulaire. Le runtime du plug-in est hébergé dans un bac à sable sur les nœuds du cluster. Le bac à sable fournit un environnement isolé et sécurisé.

Syntaxe

T | evaluate [hint.distribution = (singleper_node | )] r(script output_schema , [, script_parameters] [, external_artifacts])

En savoir plus sur les conventions de syntaxe.

Paramètres

Variables R réservées

Les variables suivantes sont réservées pour l’interaction entre Langage de requête Kusto et le code R :

• df: données tabulaires d’entrée (valeurs ci-dessus T ), sous forme de DataFrame R.
• kargs: valeur de l’argument script_parameters , en tant que dictionnaire R.
• result: Trame de données R créée par le script R. La valeur devient les données tabulaires qui sont envoyées à n’importe quel opérateur de requête Kusto qui suit le plug-in.

Activer le plug-in

• Cette option est désactivée par défaut.
• Activez ou désactivez le plug-in dans le Portail Azure sous l’onglet Configuration de votre cluster. Pour plus d’informations, consultez Gérer les extensions de langage dans votre cluster Azure Data Explorer (préversion)

Image de bac à sable R

• L’image de bac à sable R est basée sur R 3.4.4 pour Windows et inclut des packages du bundle R Essentials d’Anaconda.

Exemples

range x from 1 to 360 step 1
| evaluate r(
//
typeof(*, fx:double),               //  Output schema: append a new fx column to original table 
//
'result <- df\n'                    //  The R decorated script
'n <- nrow(df)\n'
'g <- kargs$gain\n'
'f <- kargs$cycles\n'
'result$fx <- g * sin(df$x / n * 2 * pi * f)'
//
, bag_pack('gain', 100, 'cycles', 4)    //  dictionary of parameters
)
| render linechart 

Astuces pour les performances

• Réduisez le jeu de données d’entrée du plug-in à la quantité minimale requise (colonnes/lignes).

• Utilisez des filtres sur le jeu de données source à l’aide du Langage de requête Kusto, le cas échéant.

• Pour effectuer un calcul sur un sous-ensemble des colonnes sources, projetez uniquement ces colonnes avant d’appeler le plug-in.

• Utilisez hint.distribution = per_node chaque fois que la logique de votre script est distribuable.

• Vous pouvez également utiliser l’opérateur de partition pour partitionner les données d’entrée et.

• Dans la mesure du possible, utilisez la Langage de requête Kusto pour implémenter la logique de votre script R.

  Par exemple :

  .show operations
  | where StartedOn > ago(1d) // Filtering out irrelevant records before invoking the plugin
  | project d_seconds = Duration / 1s // Projecting only a subset of the necessary columns
  | evaluate hint.distribution = per_node r( // Using per_node distribution, as the script's logic allows it
      typeof(*, d2:double),
      'result <- df\n'
      'result$d2 <- df$d_seconds\n' // Negative example: this logic should have been written using Kusto's query language
    )
  | summarize avg = avg(d2)
  

Conseils d’utilisation

• Pour éviter les conflits entre les délimiteurs de chaîne Kusto et les délimiteurs de chaîne R :

  • Utilisez des guillemets simples (') pour les littéraux de chaîne Kusto dans les requêtes Kusto.
  • Utilisez des guillemets doubles (") pour les littéraux de chaîne R dans les scripts R.

• Utilisez l’opérateur de données externe pour obtenir le contenu d’un script que vous avez stocké dans un emplacement externe, tel que le stockage Blob Azure ou un dépôt GitHub public.

  Par exemple :

  let script = 
      externaldata(script:string)
      [h'https://kustoscriptsamples.blob.core.windows.net/samples/R/sample_script.r']
      with(format = raw);
  range x from 1 to 360 step 1
  | evaluate r(
      typeof(*, fx:double),
      toscalar(script), 
      bag_pack('gain', 100, 'cycles', 4))
  | render linechart 
  

Installer des packages pour le plug-in R

Suivez ces instructions pas à pas pour installer les packages qui ne sont pas inclus dans l’image de base du plug-in.

Prérequis

1. Créez un conteneur d’objets blob pour héberger les packages, de préférence au même endroit que votre cluster. Par exemple, https://artifactswestus.blob.core.windows.net/ren supposant que votre cluster se trouve dans la région USA Ouest.

2. Modifiez la stratégie de légende du cluster pour autoriser l’accès à cet emplacement.

   • Cette modification nécessite des autorisations AllDatabasesAdmin .

   • Par exemple, pour activer l’accès à un objet blob situé dans https://artifactswestus.blob.core.windows.net/r, exécutez la commande suivante :

   .alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/r/","CanCall": true } ]'
   

Installer des packages

Les exemples de snips ci-dessous supposent que l’ordinateur R local sur l’environnement Windows.

1. Vérifiez que vous utilisez la version R appropriée : la version actuelle du bac à sable R est 3.4.4 :

   > R.Version()["version.string"]
   
   $version.string
   [1] "R version 3.4.4 (2018-03-15)"
   

   Si nécessaire, vous pouvez le télécharger à partir d’ici.

2. Lancer le RGui x64

3. Créez un dossier vide à remplir avec tous les packages appropriés que vous souhaitez installer. Dans cet exemple, nous installons le package brglm2, afin de créer « C :\brglm2 ».

4. Ajoutez le chemin du dossier nouvellement créé aux chemins d’accès lib :

   > .libPaths("C://brglm2")
   

5. Vérifiez que le nouveau dossier est maintenant le premier chemin d’accès dans .libPaths() :

   > .libPaths()
   
   [1] "C:/brglm2"    "C:/Program Files/R/R-3.4.4/library"
   
   

6. Une fois cette configuration terminée, tout package que nous installons sera ajouté à ce nouveau dossier. Installons le package demandé et ses dépendances :

   > install.packages("brglm2")
   

   Si la question « Voulez-vous installer à partir de sources auxquelles la compilation est nécessaire ? » s’affiche, répondez à « Y ».

7. Vérifiez que de nouveaux dossiers ont été ajoutés à « C :\brglm2 » :

   

8. Sélectionnez tous les éléments de ce dossier et compressez-les dans libs.zip (ne compressez pas le dossier parent). Vous devez obtenir une structure d’archive comme suit :

   libs.zip :

   • brglm2 (dossier)
   • enrichwith (dossier)
   • numDeriv (dossier)

9. Charger libs.zip dans le conteneur d’objets blob défini ci-dessus

10. Appelez le r plug-in.

    • Spécifiez le external_artifacts paramètre avec un conteneur de propriétés de nom et référence au fichier ZIP (URL de l’objet blob, y compris un jeton SAP).
    • Dans votre code r inline, importez à partir de sandboxutils et appelez zipfile sa install() méthode avec le nom du fichier ZIP.

Exemple

Installez le package brglm2 :

print x=1
| evaluate r(typeof(*, ver:string),
    'library(sandboxutils)\n'
    'zipfile.install("brglm2.zip")\n'
    'library("brglm2")\n'
    'result <- df\n'
    'result$ver <-packageVersion("brglm2")\n'
    ,external_artifacts=bag_pack(brglm2.zip', 'https://artifactswestus.blob.core.windows.net/r/libs.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))

Assurez-vous que le nom de l’archive (première valeur dans la paire pack) a le suffixe *.zip pour empêcher les collisions lors de la décompression des dossiers dont le nom est identique au nom d’archive.