Modul plug-in jazyka R (Preview)

Článek
01/23/2024

Modul plug-in jazyka R spustí uživatelem definovanou funkci (UDF) pomocí skriptu jazyka R.

Skript získá tabulková data jako svůj vstup a vytvoří tabulkový výstup. Modul runtime modulu plug-in je hostovaný v sandboxu na uzlech clusteru. Sandbox poskytuje izolované a zabezpečené prostředí.

Syntax

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

Přečtěte si další informace o konvencích syntaxe.

Parametry

Název	Typ	Vyžadováno	Popis
output_schema	`string`	✔️	Literál `type` , který definuje výstupní schéma tabulkových dat vrácené kódem R. Formát je: `typeof(`ColumnName`:`ColumnType[, ...]`)`. Příklad: `typeof(col1:string, col2:long)`. K rozšíření vstupního schématu použijte následující syntaxi: `typeof(*, col1:string, col2:long)`.
Skript	`string`	✔️	Platný skript jazyka R, který se má spustit.
script_parameters	`dynamic`		Pytel vlastností párů název a hodnota, které se mají předat do skriptu jazyka R jako rezervovaný `kargs` slovník. Další informace najdete v tématu Rezervované proměnné jazyka R.
`hint.distribution`	`string`		Nápověda k distribuci spuštění modulu plug-in mezi více uzlů clusteru Výchozí hodnota je `single`. `single` znamená, že jedna instance skriptu se spustí přes celá data dotazu. `per_node` znamená, že pokud je dotaz před distribuovaným blokem R, spustí se instance skriptu na každém uzlu přes data, která obsahuje.
external_artifacts	`dynamic`		Pytel vlastností s názvy a adresami URL pro artefakty, které jsou přístupné z cloudového úložiště. Můžou být k dispozici pro skript, který může používat za běhu. Adresy URL odkazované v tomto kontejneru vlastností musí být zahrnuté do zásad popisku clusteru a ve veřejně dostupném umístění nebo musí obsahovat potřebné přihlašovací údaje, jak je vysvětleno v připojovacích řetězcích úložiště. Artefakty jsou dostupné pro skript, který může využívat z místního dočasného adresáře `.\Temp`. Názvy zadané v kontejneru vlastností se používají jako názvy místních souborů. Viz příklad. Další informace najdete v tématu Instalace balíčků pro modul plug-in jazyka R.

Rezervované proměnné R

Pro interakci mezi dotazovací jazyk Kusto a kódem R jsou vyhrazeny následující proměnné:

df: Vstupní tabulková data (výše uvedené T hodnoty) jako datový rámec R.
kargs: Hodnota argumentu script_parameters jako slovníku jazyka R.
result: Datový rámec jazyka R vytvořený skriptem jazyka R. Hodnota se stane tabulková data, která se odesílají do libovolného operátoru dotazu Kusto, který následuje za modulem plug-in.

Povolení modulu plug-in

Modul plug-in je ve výchozím nastavení zakázaný.
Povolte nebo zakažte modul plug-in v Azure Portal na kartě Konfigurace clusteru. Další informace najdete v tématu Správa jazykových rozšíření v clusteru Azure Data Explorer (Preview).

Obrázek sandboxu R

Image sandboxu R je založená na R 3.4.4 pro Windows a obsahuje balíčky ze sady R Essentials anacondy.

Příklady

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.

Tipy pro zvýšení výkonu

Snižte vstupní datovou sadu modulu plug-in na minimální požadované množství (sloupce/řádky).
Pokud je to možné, použijte filtry pro zdrojovou datovou sadu pomocí dotazovací jazyk Kusto.
Pokud chcete provést výpočet na podmnožině zdrojových sloupců, promítněte před vyvoláním modulu plug-in pouze tyto sloupce.
Použijte hint.distribution = per_node vždy, když je logika ve vašem skriptu distribuovatelná.
Můžete také použít operátor oddílu pro dělení vstupních dat et.

Kdykoli je to možné, použijte dotazovací jazyk Kusto k implementaci logiky skriptu jazyka R.

Příklad:

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

Tipy k používání

Abyste se vyhnuli konfliktům mezi oddělovači řetězců Kusto a oddělovači řetězců R:
- V dotazech Kusto používejte jednoduché uvozovky (') pro řetězcové literály Kusto.
- Používejte uvozovky (") pro literály řetězců jazyka R ve skriptech jazyka R.

Pomocí operátoru externích dat získejte obsah skriptu, který jste uložili v externím umístění, jako je azure blob storage nebo veřejné úložiště GitHub.

Příklad:

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

Instalace balíčků pro modul plug-in jazyka R

Podle těchto podrobných pokynů nainstalujte balíčky, které nejsou součástí základní image modulu plug-in.

Požadavky

Vytvořte kontejner objektů blob, který bude hostovat balíčky, nejlépe na stejném místě jako váš cluster. Například , za předpokladu, https://artifactswestus.blob.core.windows.net/rže se váš cluster nachází v oblasti USA – západ.
Upravte zásady popisku clusteru tak, aby umožňovaly přístup k danému umístění.
- Tato změna vyžaduje oprávnění AllDatabasesAdmin .
- Pokud například chcete povolit přístup k objektu blob umístěnému v https://artifactswestus.blob.core.windows.net/r, spusťte následující příkaz:
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/r/","CanCall": true } ]'
```

Instalace balíčků

Následující příklad výstřižku předpokládá místní počítač R v prostředí Windows.

Ověřte, že používáte odpovídající verzi R – aktuální verze sandboxu R je 3.4.4:
```
> R.Version()["version.string"]

$version.string
[1] "R version 3.4.4 (2018-03-15)"
```
V případě potřeby si ho můžete stáhnout odsud.
Spusťte x64 RGui
Vytvořte novou prázdnou složku, která se naplní všemi relevantními balíčky, které chcete nainstalovat. V tomto příkladu nainstalujeme balíček brglm2, takže vytvoříme "C:\brglm2".
Přidejte nově vytvořenou cestu ke složce do cest knihovny:
```
> .libPaths("C://brglm2")
```

Ověřte, že je nová složka nyní první cestou v souboru .libPaths():

> .libPaths()

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

Po dokončení tohoto nastavení se do této nové složky přidají všechny balíčky, které nainstalujete. Pojďme nainstalovat požadovaný balíček a jeho závislosti:
```
> install.packages("brglm2")
```
V případě, že se zobrazí otázka "Chcete nainstalovat ze zdrojů balíčky, které potřebují kompilaci?" , odpovězte "Y".
Ověřte, že se do složky C:\brglm2 přidaly nové složky:
Vyberte všechny položky v této složce a zazipujte je například do libs.zip (nezazipujte nadřazenou složku). Měli byste získat strukturu archivu, jako je tato:

libs.zip:
- brglm2 (složka)
- enrichwith (složka)
- numDeriv (složka)
Nahrání libs.zip do kontejneru objektů blob, který byl nastavený výše
Zavolejte modul plug-in r .
- external_artifacts Zadejte parametr s sadou vlastností s názvem a odkazem na soubor zip (adresa URL objektu blob včetně tokenu SAS).
- V vložený kód r importujte zipfile z sandboxutils a volejte jeho install() metodu s názvem souboru ZIP.

Příklad

Nainstalujte balíček 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

Ujistěte se, že název archivu (první hodnota v páru balíčku) má příponu *.zip, aby se zabránilo kolizím při rozbalování složek, jejichž název je stejný jako název archivu.

Tato funkce není podporovaná.

Sdílet prostřednictvím