Dela via

R-plugin-program (förhandsversion)

  • Artikel

R-plugin-programmet kör en användardefinierad funktion (UDF) med ett R-skript.

Skriptet hämtar tabelldata som indata och genererar tabellutdata. Plugin-programmets körning finns i en sandbox-miljö på klustrets noder. Sandbox-miljön ger en isolerad och säker miljö.

Syntax

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

Läs mer om syntaxkonventioner.

Parametrar

Namn Typ Obligatorisk Beskrivning
output_schema string ✔️ En type literal som definierar utdataschemat för tabelldata som returneras av R-koden. Formatet är: typeof(ColumnName:ColumnType[, ...]). Till exempel: typeof(col1:string, col2:long). Om du vill utöka indataschemat använder du följande syntax: typeof(*, col1:string, col2:long).
Skript string ✔️ Det giltiga R-skriptet som ska köras.
script_parameters dynamic En egenskapsuppsättning med namn- och värdepar som ska skickas till R-skriptet som reserverad kargs ordlista. Mer information finns i Reserverade R-variabler.
hint.distribution string Tips för att plugin-programmets körning ska distribueras över flera klusternoder. Standardvärdet är single. single innebär att en enda instans av skriptet körs över hela frågedata. per_node innebär att om frågan innan R-blocket distribueras körs en instans av skriptet på varje nod över de data som den innehåller.
external_artifacts dynamic En egenskapsuppsättning med namn- och URL-par för artefakter som är tillgängliga från molnlagring. De kan göras tillgängliga för skriptet som ska användas vid körning. URL:er som refereras i den här egenskapsuppsättningen måste inkluderas i klustrets pratbubblans princip och på en offentligt tillgänglig plats, eller innehålla nödvändiga autentiseringsuppgifter, enligt beskrivningen i anslutningssträngar för lagring. Artefakterna görs tillgängliga för skriptet att använda från en lokal tillfällig katalog, .\Temp. Namnen som anges i egenskapspåsen används som lokala filnamn. Se Exempel. Mer information finns i Installera paket för R-plugin-programmet.

Reserverade R-variabler

Följande variabler är reserverade för interaktion mellan Kusto-frågespråk och R-koden:

  • df: Tabelldata för indata (värdena T ovan) som en R DataFrame.
  • kargs: Värdet för argumentet script_parameters som en R-ordlista.
  • result: En R DataFrame som skapats av R-skriptet. Värdet blir tabelldata som skickas till alla Kusto-frågeoperatorer som följer plugin-programmet.

Aktivera plugin-programmet

R-sandbox-avbildning

Exempel

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

Sinusdemo.

Prestandatips

  • Minska plugin-programmets indatauppsättning till den minsta mängd som krävs (kolumner/rader).

  • Använd filter på källdatauppsättningen med hjälp av Kusto-frågespråk, när det är möjligt.

  • Om du vill göra en beräkning på en delmängd av källkolumnerna projicerar du bara dessa kolumner innan du anropar plugin-programmet.

  • Använd hint.distribution = per_node när logiken i skriptet kan distribueras.

  • Du kan också använda partitionsoperatorn för partitionering av indatamängden.

  • När det är möjligt använder du Kusto-frågespråk för att implementera logiken i ditt R-skript.

    Exempel:

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

Användningstips

  • Så här undviker du konflikter mellan Kusto-strängavgränsare och R-strängavgränsare:

    • Använd enkla citattecken (') för Kusto-strängliteraler i Kusto-frågor.
    • Använd dubbla citattecken (") för R-strängliteraler i R-skript.

  • Använd den externa dataoperatorn för att hämta innehållet i ett skript som du har lagrat på en extern plats, till exempel Azure Blob Storage eller en offentlig GitHub-lagringsplats.

    Exempel:

    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

Installera paket för R-plugin-programmet

Följ dessa steg för steg-instruktioner för att installera paket som inte ingår i plugin-programmets basavbildning.

Förutsättningar

  1. Skapa en blobcontainer som värd för paketen, helst på samma plats som klustret. Anta till exempel att klustret finns i USA, https://artifactswestus.blob.core.windows.net/rvästra.

  2. Ändra klustrets pratbubblans princip för att tillåta åtkomst till den platsen.

    • Den här ändringen kräver Behörigheter för AllDatabasesAdmin .

    • Om du till exempel vill aktivera åtkomst till en blob som finns i https://artifactswestus.blob.core.windows.net/rkör du följande kommando:

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

Installera paket

Exempelfragmenten nedan förutsätter lokal R-dator i Windows-miljön.

  1. Kontrollera att du använder rätt R-version – den aktuella R Sandbox-versionen är 3.4.4:

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

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

    Om det behövs kan du ladda ned det härifrån.

  2. Starta x64 RGui

  3. Skapa en ny tom mapp som ska fyllas i med alla relevanta paket som du vill installera. I det här exemplet installerar vi brglm2-paketet, så skapar "C:\brglm2".

  4. Lägg till den nyligen skapade mappsökvägen till lib-sökvägar:

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

  5. Kontrollera att den nya mappen nu är den första sökvägen i .libPaths():

    > .libPaths()

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

  6. När den här installationen är klar läggs alla paket som vi installerar till i den nya mappen. Nu ska vi installera det begärda paketet och dess beroenden:

    > install.packages("brglm2")

    Om frågan "Vill du installera från källor de paket som behöver kompilering?" dyker upp svarar du "Y".

  7. Kontrollera att nya mappar har lagts till i "C:\brglm2":

    Skärmbild av bibliotekskataloginnehåll.

  8. Markera alla objekt i mappen och zippa dem till t.ex. libs.zip (zippa inte den överordnade mappen). Du bör få en arkivstruktur som den här:

    libs.zip:

    • brglm2 (mapp)
    • enrichwith (mapp)
    • numDeriv (mapp)

  9. Ladda upp libs.zip till blobcontainern som angavs ovan

  10. Anropa plugin-programmet r .

    • Ange parametern external_artifacts med en egenskapsuppsättning med namn och referens till zip-filen (blobens URL, inklusive en SAS-token).
    • I din infogade r-kod importerar zipfile du från sandboxutils och anropar dess install() metod med namnet på zip-filen.

Exempel

Installera brglm2-paketet:

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

Kontrollera att arkivets namn (första värdet i paketparet) har suffixet *.zip för att förhindra kollisioner när mappar packas upp vars namn är identiskt med arkivnamnet.

Den här funktionen stöds inte.