Wtyczka języka R (wersja zapoznawcza)

Artykuł
01/23/2024

Wtyczka języka R uruchamia funkcję zdefiniowaną przez użytkownika (UDF) przy użyciu skryptu języka R.

Skrypt pobiera dane tabelaryczne jako dane wejściowe i generuje dane wyjściowe tabelaryczne. Środowisko uruchomieniowe wtyczki jest hostowane w piaskownicy w węzłach klastra. Piaskownica zapewnia izolowane i bezpieczne środowisko.

Składnia

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

Dowiedz się więcej o konwencjach składniowych.

Parametry

Nazwa	Typ	Wymagane	Opis
output_schema	`string`	✔️	Literał `type` definiujący schemat wyjściowy danych tabelarycznych zwracany przez kod języka R. Format to: `typeof(`ColumnName`:`ColumnType[, ...]`)`. Na przykład: `typeof(col1:string, col2:long)`. Aby rozszerzyć schemat wejściowy, użyj następującej składni: `typeof(*, col1:string, col2:long)`.
Skrypt	`string`	✔️	Prawidłowy skrypt języka R do wykonania.
script_parameters	`dynamic`		Zbiór właściwości par nazw i wartości, które mają zostać przekazane do skryptu języka R jako słownika zarezerwowanego `kargs` . Aby uzyskać więcej informacji, zobacz Zmienne zarezerwowane języka R.
`hint.distribution`	`string`		Wskazówka dotycząca wykonywania wtyczki, która ma być dystrybuowana między wieloma węzłami klastra. Wartość domyślna to `single`. `single` oznacza, że pojedyncze wystąpienie skryptu zostanie uruchomione na wszystkich danych zapytania. `per_node` oznacza, że jeśli zapytanie przed dystrybucją bloku języka R, wystąpienie skryptu zostanie uruchomione w każdym węźle nad danymi, które zawiera.
external_artifacts	`dynamic`		Zbiór właściwości par nazw i adresów URL dla artefaktów, które są dostępne z magazynu w chmurze. Można je udostępnić dla skryptu do użycia w czasie wykonywania. Adresy URL, do których odwołuje się ten zbiór właściwości, muszą być uwzględnione w zasadach objaśnień klastra i w publicznie dostępnej lokalizacji lub zawierają niezbędne poświadczenia, jak wyjaśniono w parametrach połączenia magazynu. Artefakty są udostępniane dla skryptu do korzystania z lokalnego katalogu tymczasowego , `.\Temp`. Nazwy podane w torbie właściwości są używane jako lokalne nazwy plików. Zobacz przykład. Aby uzyskać więcej informacji, zobacz Instalowanie pakietów dla wtyczki języka R.

Zarezerwowane zmienne języka R

Następujące zmienne są zarezerwowane do interakcji między język zapytań Kusto a kodem języka R:

df: wejściowe dane tabelaryczne (wartości T powyżej) jako ramka danych języka R.
kargs: wartość argumentu script_parameters jako słownik języka R.
result: ramka danych języka R utworzona przez skrypt języka R. Wartość staje się danymi tabelarycznymi, które są wysyłane do dowolnego operatora zapytania Kusto, który jest zgodny z wtyczką.

Włączanie wtyczki

Wtyczka jest domyślnie wyłączona.
Włącz lub wyłącz wtyczkę w Azure Portal na karcie Konfiguracja klastra. Aby uzyskać więcej informacji, zobacz Zarządzanie rozszerzeniami języka w klastrze usługi Azure Data Explorer (wersja zapoznawcza)

Obraz piaskownicy języka R

Obraz piaskownicy języka R jest oparty na wersji R 3.4.4 dla systemu Windows i zawiera pakiety z pakietu R Essentials platformy Anaconda.

Przykłady

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.

Porady dotyczące wydajności

Zmniejsz wejściowy zestaw danych wtyczki do minimalnej wymaganej ilości (kolumny/wiersze).
Użyj filtrów w źródłowym zestawie danych przy użyciu język zapytań Kusto, gdy jest to możliwe.
Aby wykonać obliczenie w podzestawie kolumn źródłowych, przed wywołaniem wtyczki projektuj tylko te kolumny.
Należy używać hint.distribution = per_node za każdym razem, gdy logika w skry skrycie jest dystrybuowana.
Można również użyć operatora partycji do partycjonowania danych wejściowych et.

Jeśli to możliwe, użyj język zapytań Kusto, aby zaimplementować logikę skryptu języka R.

Na przykład:

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

Porady dotyczące użycia

Aby uniknąć konfliktów między ogranicznikami ciągów Kusto i ogranicznikami ciągów języka R:
- Używaj znaków pojedynczego cudzysłowu (') dla literałów ciągu Kusto w zapytaniach Kusto.
- Używaj znaków podwójnego cudzysłowu (") dla literałów ciągu języka R w skryptach języka R.

Użyj zewnętrznego operatora danych , aby uzyskać zawartość skryptu przechowywanego w lokalizacji zewnętrznej, takiej jak usługa Azure Blob Storage lub publiczne repozytorium GitHub.

Na przykład:

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

Instalowanie pakietów dla wtyczki języka R

Postępuj zgodnie z tymi instrukcjami krok po kroku, aby zainstalować pakiety, które nie są uwzględnione w obrazie podstawowym wtyczki.

Wymagania wstępne

Utwórz kontener obiektów blob do hostowania pakietów, najlepiej w tym samym miejscu co klaster. Na przykład , zakładając, https://artifactswestus.blob.core.windows.net/rże klaster znajduje się w regionie Zachodnie stany USA.
Zmień zasady objaśnienie klastra, aby zezwolić na dostęp do tej lokalizacji.
- Ta zmiana wymaga uprawnień AllDatabasesAdmin .
- Aby na przykład włączyć dostęp do obiektu blob znajdującego się w https://artifactswestus.blob.core.windows.net/rlokalizacji , uruchom następujące polecenie:
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/r/","CanCall": true } ]'
```

Instalowanie pakietów

W poniższym przykładzie przyjęto założenie, że lokalna maszyna języka R w środowisku systemu Windows.

Sprawdź, czy używasz odpowiedniej wersji języka R — bieżąca wersja piaskownicy języka R to 3.4.4:
```
> R.Version()["version.string"]

$version.string
[1] "R version 3.4.4 (2018-03-15)"
```
W razie potrzeby możesz pobrać go z tego miejsca.
Uruchamianie interfejsu RGui x64
Utwórz nowy pusty folder, który ma zostać wypełniony wszystkimi odpowiednimi pakietami, które chcesz zainstalować. W tym przykładzie instalujemy pakiet brglm2, więc tworzymy "C:\brglm2".
Dodaj nowo utworzoną ścieżkę folderu do ścieżek lib:
```
> .libPaths("C://brglm2")
```
Sprawdź, czy nowy folder jest teraz pierwszą ścieżką w pliku .libPaths():
```
> .libPaths()

[1] "C:/brglm2"    "C:/Program Files/R/R-3.4.4/library"
```
Po zakończeniu instalacji do tego nowego folderu zostaną dodane wszystkie instalowane pakiety. Zainstalujmy żądany pakiet i jego zależności:
```
> install.packages("brglm2")
```
Jeśli pojawi się pytanie "Czy chcesz zainstalować ze źródeł pakiety, które wymagają kompilacji?", odpowiedz "Y".
Sprawdź, czy nowe foldery zostały dodane do folderu "C:\brglm2":
Zaznacz wszystkie elementy w tym folderze i spakuj je na przykład libs.zip (nie spakuj folderu nadrzędnego). Powinna zostać wyświetlona struktura archiwum w następujący sposób:

libs.zip:
- brglm2 (folder)
- enrichwith (folder)
- numDeriv (folder)
Przekaż libs.zip do kontenera obiektów blob, który został ustawiony powyżej
Wywołaj wtyczkę r .
- external_artifacts Określ parametr z nazwą właściwości i odwołaniem do pliku zip (adres URL obiektu blob, w tym token SAS).
- W kodzie wbudowanym r zaimportuj zipfile metodę sandboxutils i wywołaj jej install() metodę z nazwą pliku zip.

Przykład

Zainstaluj pakiet 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

Upewnij się, że nazwa archiwum (pierwsza wartość w parze pakietów) ma sufiks *.zip, aby zapobiec kolizjom podczas rozpakowywania folderów, których nazwa jest identyczna z nazwą archiwum.

Ta funkcja nie jest obsługiwana.

Share via