Plug-in R (préversion)

Article
07/04/2024

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

Nom	Type	Requise	Description
output_schema	`string`	✔️	Littéral `type` qui définit le schéma de sortie des données tabulaires, retourné par le code R. Le format est : `typeof(`ColumnName`:` ColumnType[, ...]`)`. Par exemple : `typeof(col1:string, col2:long)`. Pour étendre le schéma d’entrée, utilisez la syntaxe suivante : `typeof(*, col1:string, col2:long)`.
script	`string`	✔️	Script R valide à exécuter.
script_parameters	`dynamic`		Un conteneur de propriétés de paires nom et valeur à passer au script R en tant que dictionnaire réservé `kargs` . Pour plus d’informations, consultez variables R réservées.
`hint.distribution`	`string`		Conseil pour que l’exécution du plug-in soit distribuée sur plusieurs nœuds de cluster. La valeur par défaut est `single`. `single` signifie qu’une seule instance du script s’exécute sur l’ensemble des données de requête. `per_node` signifie que si la requête avant le bloc R est distribuée, une instance du script s’exécute sur chaque nœud sur les données qu’il contient.
external_artifacts	`dynamic`		Un conteneur de propriétés de paires nom et URL pour les artefacts accessibles à partir du stockage cloud. Ils peuvent être mis à la disposition du script à utiliser au moment de l’exécution. Les URL référencées dans ce conteneur de propriétés doivent être incluses dans la stratégie de légende du cluster et dans un emplacement disponible publiquement ou contenir les informations d’identification nécessaires, comme expliqué dans les chaîne de connexion de stockage. Les artefacts sont mis à la disposition du script pour qu’il consomme à partir d’un répertoire temporaire local. `.\Temp` Les noms fournis dans le conteneur de propriétés sont utilisés comme noms de fichiers locaux. Consultez l'exemple. Pour plus d’informations, consultez Installer des packages pour le plug-in R.

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

Démonstration sine.

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

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.
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.

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.
Lancer le RGui x64
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 ».
Ajoutez le chemin du dossier nouvellement créé aux chemins d’accès lib :
```
> .libPaths("C://brglm2")
```
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"
```
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 ».
Vérifiez que de nouveaux dossiers ont été ajoutés à « C :\brglm2 » :
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)
Charger libs.zip dans le conteneur d’objets blob défini ci-dessus
Appelez le r plug-in.
- Spécifiez le external_artifacts paramètre avec un conteneur de propriétés de nom et référencez le 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 ***'))

x	ver
1	1.8.2

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.

Cette fonctionnalité n’est pas prise en charge.

Partager via