R-invoegtoepassing (preview)
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 vanT
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
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 enkele aanhalingstekens (
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/r
ervan 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/r
te 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 uitsandboxutils
en roep de methode aaninstall()
met de naam van het zip-bestand.
- Geef de
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.
Feedback
https://aka.ms/ContentUserFeedback.
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie:Feedback verzenden en weergeven voor