R-invoegtoepassing (preview)

Artikel
01/18/2024

De R-invoegtoepassing voert een door de gebruiker gedefinieerde functie (UDF) uit met behulp van een R-script.

Het script haalt gegevens in tabelvorm op als invoer en produceert uitvoer in tabelvorm. De runtime van de invoegtoepassing wordt gehost in een sandbox op de knooppunten van het cluster. De sandbox biedt een geïsoleerde en veilige omgeving.

Syntax

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

Meer informatie over syntaxisconventies.

Parameters

Naam	Type	Vereist	Beschrijving
output_schema	`string`	✔️	Een `type` letterlijke waarde die het uitvoerschema van de tabelgegevens definieert, geretourneerd door de R-code. De indeling is: `typeof(`ColumnName`:`ColumnType[, ...]`)`. Bijvoorbeeld: `typeof(col1:string, col2:long)`. Gebruik de volgende syntaxis om het invoerschema uit te breiden: `typeof(*, col1:string, col2:long)`.
script	`string`	✔️	Het geldige R-script dat moet worden uitgevoerd.
script_parameters	`dynamic`		Een eigenschappenverzameling met naam- en waardeparen die als gereserveerde woordenlijst moeten worden doorgegeven aan het R-script `kargs` . Zie Gereserveerde R-variabelen voor meer informatie.
`hint.distribution`	`string`		Hint voor de uitvoering van de invoegtoepassing die moet worden gedistribueerd over meerdere clusterknooppunten. De standaardwaarde is `single`. `single` betekent dat één exemplaar van het script wordt uitgevoerd voor de volledige querygegevens. `per_node` betekent dat als de query voordat het R-blok wordt gedistribueerd, een exemplaar van het script wordt uitgevoerd op elk knooppunt over de gegevens die het bevat.
external_artifacts	`dynamic`		Een eigenschappenverzameling met naam- en URL-paren voor artefacten die toegankelijk zijn vanuit cloudopslag. Ze kunnen beschikbaar worden gesteld voor het script om tijdens runtime te gebruiken. URL's waarnaar in deze eigenschappenverzameling wordt verwezen, moeten worden opgenomen in het bijschriftbeleid van het cluster en op een openbaar beschikbare locatie, of de benodigde referenties bevatten, zoals wordt uitgelegd in opslagverbindingsreeksen. De artefacten worden beschikbaar gesteld voor het script om te gebruiken vanuit een lokale tijdelijke map, `.\Temp`. De namen in de eigenschappenverzameling worden gebruikt als de lokale bestandsnamen. Zie Voorbeeld. Zie Pakketten voor de R-invoegtoepassing installeren voor meer informatie.

Gereserveerde R-variabelen

De volgende variabelen zijn gereserveerd voor interactie tussen Kusto-querytaal en de R-code:

df: De invoergegevens in tabelvorm (de waarden van T hierboven) als een R-dataframe.
kargs: De waarde van het argument script_parameters , als een R-woordenlijst.
result: Een R DataFrame dat is gemaakt door het R-script. De waarde wordt de tabelgegevens die worden verzonden naar een Kusto-queryoperator die de invoegtoepassing volgt.

De invoegtoepassing inschakelen

De invoegtoepassing is standaard uitgeschakeld.
Schakel de invoegtoepassing in of uit in de Azure Portal op het tabblad Configuratie van uw cluster. Zie Taalextensies beheren in uw Azure Data Explorer-cluster (preview) voor meer informatie

R-sandbox-installatiekopieën

De R-sandboxinstallatiekopie is gebaseerd op R 3.4.4 voor Windows en bevat pakketten uit de R Essentials-bundel van Anaconda.

Voorbeelden

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

Sine demo.

Tips voor prestaties

Verminder de invoergegevensset van de invoegtoepassing tot de minimaal vereiste hoeveelheid (kolommen/rijen).
Gebruik, indien mogelijk, filters voor de brongegevensset met behulp van de Kusto-querytaal.
Als u een berekening wilt maken op een subset van de bronkolommen, projecteren we alleen die kolommen voordat u de invoegtoepassing aanroept.
Gebruik hint.distribution = per_node wanneer de logica in uw script kan worden gedistribueerd.
U kunt ook de partitieoperator gebruiken voor het partitioneren van de invoergegevens et.

Gebruik waar mogelijk de Kusto-querytaal om de logica van uw R-script te implementeren.

Bijvoorbeeld:

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

Tips voor gebruik

Conflicten tussen Kusto-tekenreeksscheidingstekens en R-tekenreeksscheidingstekens voorkomen:
- Gebruik enkele aanhalingstekens (') voor letterlijke Kusto-tekenreeksen in Kusto-query's.
- Gebruik dubbele aanhalingstekens (") voor letterlijke R-tekenreeksen in R-scripts.

Gebruik de externe gegevensoperator om de inhoud op te halen van een script dat u hebt opgeslagen op een externe locatie, zoals Azure Blob Storage of een openbare GitHub-opslagplaats.

Bijvoorbeeld:

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

Pakketten voor de R-invoegtoepassing installeren

Volg deze stapsgewijze instructies om pakketten te installeren die niet zijn opgenomen in de basisinstallatiekopieën van de invoegtoepassing.

Vereisten

Maak een blobcontainer om de pakketten te hosten, bij voorkeur op dezelfde plaats als uw cluster. Bijvoorbeeld , https://artifactswestus.blob.core.windows.net/rervan uitgaande dat uw cluster zich in VS - west bevindt.
Wijzig het bijschriftbeleid van het cluster om toegang tot die locatie toe te staan.
- Voor deze wijziging zijn AllDatabasesAdmin-machtigingen vereist.
- Voer bijvoorbeeld de volgende opdracht uit om toegang tot een blob in https://artifactswestus.blob.core.windows.net/rte schakelen:
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/r/","CanCall": true } ]'
```

Pakketten installeren

In de onderstaande voorbeeldknipsels wordt ervan uitgegaan dat de lokale R-computer zich in een Windows-omgeving bevindt.

Controleer of u de juiste R-versie gebruikt. De huidige R Sandbox-versie is 3.4.4:
```
> R.Version()["version.string"]

$version.string
[1] "R version 3.4.4 (2018-03-15)"
```
Indien nodig kunt u deze hier downloaden.
De x64 RGui starten
Maak een nieuwe lege map die moet worden gevuld met alle relevante pakketten die u wilt installeren. In dit voorbeeld installeren we het brglm2-pakket, dus maken we 'C:\brglm2'.
Voeg het zojuist gemaakte mappad toe aan lib-paden:
```
> .libPaths("C://brglm2")
```

Controleer of de nieuwe map nu het eerste pad in .libPaths() is:

> .libPaths()

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

Zodra deze installatie is voltooid, wordt elk pakket dat we installeren toegevoegd aan deze nieuwe map. Laten we het aangevraagde pakket en de bijbehorende afhankelijkheden installeren:
```
> install.packages("brglm2")
```
Als de vraag 'Wilt u installeren vanuit bronnen de pakketten die compilatie nodig hebben?' wordt weergegeven, antwoordt u 'Y'.
Controleer of er nieuwe mappen zijn toegevoegd aan 'C:\brglm2':
Selecteer alle items in die map en zip ze naar bijvoorbeeld libs.zip (zip de bovenliggende map niet). Als het goed is, krijgt u een archiefstructuur als volgt:

libs.zip:
- brglm2 (map)
- enrichwith (map)
- numDeriv (map)
Upload libs.zip naar de blobcontainer die hierboven is ingesteld
Roep de r invoegtoepassing aan.
- Geef de external_artifacts parameter op met een eigenschappenverzameling met de naam en verwijzing naar het zip-bestand (de URL van de blob, inclusief een SAS-token).
- Importeer zipfile in uw inline r-code uit sandboxutils en roep de methode aan install() met de naam van het zip-bestand.

Voorbeeld

Installeer het brglm2-pakket:

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

Zorg ervoor dat de naam van het archief (eerste waarde in pakketpaar) het achtervoegsel *.zip heeft om conflicten te voorkomen bij het uitpakken van mappen waarvan de naam identiek is aan de archiefnaam.

Deze mogelijkheid wordt niet ondersteund.

Delen via