Plug-in R (anteprima)

  • Articolo

Il plug-in R esegue una funzione definita dall'utente usando uno script R.

Lo script ottiene i dati tabulari come input e produce output tabulare. Il runtime del plug-in è ospitato in una sandbox nei nodi del cluster. La sandbox fornisce un ambiente isolato e sicuro.

Sintassi

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

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome Tipo Obbligatoria Descrizione
output_schema string ✔️ Valore type letterale che definisce lo schema di output dei dati tabulari restituiti dal codice R. Il formato è: typeof(ColumnName:ColumnType[, ...]). Ad esempio: typeof(col1:string, col2:long). Per estendere lo schema di input, usare la sintassi seguente: typeof(*, col1:string, col2:long).
script string ✔️ Script R valido da eseguire.
script_parameters dynamic Contenitore di proprietà di coppie nome e valore da passare allo script R come dizionario riservato kargs . Per altre informazioni, vedere Variabili R riservate.
hint.distribution string Suggerimento per l'esecuzione del plug-in da distribuire tra più nodi del cluster. Il valore predefinito è single. single significa che una singola istanza dello script verrà eseguita sull'intero dati della query. per_node significa che se la query prima della distribuzione del blocco R, un'istanza dello script verrà eseguita in ogni nodo sui dati contenuti.
external_artifacts dynamic Contenitore di proprietà di coppie nome e URL per gli artefatti accessibili dall'archiviazione cloud. Possono essere resi disponibili per l'uso dello script in fase di esecuzione. Gli URL a cui si fa riferimento in questo contenitore di proprietà devono essere inclusi nei criteri di callout del cluster e in una posizione disponibile pubblicamente o contengono le credenziali necessarie, come illustrato nelle stringhe di connessione di archiviazione. Gli artefatti vengono resi disponibili per l'utilizzo dello script da una directory temporanea locale, .\Temp. I nomi specificati nel contenitore delle proprietà vengono usati come nomi di file locali. Vedere l'esempio. Per altre informazioni, vedere Installare pacchetti per il plug-in R.

Variabili R riservate

Le variabili seguenti sono riservate per l'interazione tra Linguaggio di query Kusto e il codice R:

  • df: dati tabulari di input (i valori di T sopra), come dataframe R.
  • kargs: valore dell'argomento script_parameters , come dizionario R.
  • result: un dataframe R creato dallo script R. Il valore diventa i dati tabulari inviati a qualsiasi operatore di query Kusto che segue il plug-in.

Abilitare il plug-in

Immagine sandbox R

Esempio

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

Demo sine.

Suggerimenti per incrementare le prestazioni

  • Ridurre il set di dati di input del plug-in alla quantità minima richiesta (colonne/righe).

  • Usare i filtri nel set di dati di origine usando il Linguaggio di query Kusto, quando possibile.

  • Per eseguire un calcolo su un subset delle colonne di origine, proiettare solo le colonne prima di richiamare il plug-in.

  • Usare hint.distribution = per_node ogni volta che la logica nello script è distribuibile.

  • È anche possibile usare l'operatore di partizione per partizionare i dati di input et.

  • Quando possibile, usare il Linguaggio di query Kusto per implementare la logica dello script R.

    Ad esempio:

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

Suggerimenti per l'uso

  • Per evitare conflitti tra delimitatori di stringa Kusto e delimitatori di stringa R:

    • Usare i caratteri virgolette singole (') per i valori letterali stringa Kusto nelle query Kusto.
    • Usare i caratteri virgolette doppie (") per i valori letterali stringa R negli script R.

  • Usare l'operatore dati esterno per ottenere il contenuto di uno script archiviato in un percorso esterno, ad esempio l'archiviazione BLOB di Azure o un repository GitHub pubblico.

    Ad esempio:

    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

Installare i pacchetti per il plug-in R

Seguire queste istruzioni dettagliate per installare i pacchetti che non sono inclusi nell'immagine di base del plug-in.

Prerequisiti

  1. Creare un contenitore BLOB per ospitare i pacchetti, preferibilmente nella stessa posizione del cluster. Ad esempio, https://artifactswestus.blob.core.windows.net/r, presupponendo che il cluster si trova negli Stati Uniti occidentali.

  2. Modificare i criteri di callout del cluster per consentire l'accesso a tale posizione.

    • Questa modifica richiede autorizzazioni AllDatabasesAdmin .

    • Ad esempio, per abilitare l'accesso a un BLOB che si trova in https://artifactswestus.blob.core.windows.net/r, eseguire il comando seguente:

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

Installare i pacchetti

Gli snips di esempio riportati di seguito presuppongono il computer R locale nell'ambiente Windows.

  1. Verificare di usare la versione R appropriata: la versione corrente di R Sandbox è 3.4.4:

    > R.Version()["version.string"]

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

    Se necessario, è possibile scaricarlo da qui.

  2. Avviare RGui x64

  3. Creare una nuova cartella vuota da popolare con tutti i pacchetti pertinenti da installare. In questo esempio viene installato il pacchetto brglm2, quindi si crea "C:\brglm2".

  4. Aggiungere il percorso della cartella appena creato ai percorsi lib:

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

  5. Verificare che la nuova cartella sia ora il primo percorso in .libPaths():

    > .libPaths()

[1] "C:/brglm2"    "C:/Program Files/R/R-3.4.4/library"

  6. Al termine dell'installazione, qualsiasi pacchetto installato verrà aggiunto a questa nuova cartella. Installare il pacchetto richiesto e le relative dipendenze:

    > install.packages("brglm2")

    Nel caso in cui la domanda "Si vuole installare da origini i pacchetti che richiedono la compilazione?" viene visualizzata la risposta "Y".

  7. Verificare che le nuove cartelle siano state aggiunte a "C:\brglm2":

    Screenshot del contenuto della directory della libreria.

  8. Selezionare tutti gli elementi nella cartella e comprimerli, ad esempio libs.zip (non comprimere la cartella padre). Dovrebbe essere visualizzata una struttura di archiviazione simile alla seguente:

    libs.zip:

    • brglm2 (cartella)
    • enrichwith (cartella)
    • numDeriv (cartella)

  9. Caricare libs.zip nel contenitore BLOB impostato in precedenza

  10. Chiamare il plug-in r .

    • Specificare il external_artifacts parametro con un contenitore di proprietà di nome e riferimento al file ZIP (URL del BLOB, incluso un token di firma di accesso condiviso).
    • Nel codice r inline importare zipfilesandboxutils e chiamare il relativo install() metodo con il nome del file ZIP.

Esempio

Installare il pacchetto 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

Assicurarsi che il nome dell'archivio (primo valore nella coppia di pacchetti) abbia il suffisso *.zip per evitare conflitti durante il decomprimemento delle cartelle il cui nome è identico al nome dell'archivio.

Questa funzionalità non è supportata.