Подключаемый модуль R (предварительная версия)

Статья
01/10/2024

Подключаемый модуль R запускает определяемую пользователем функцию (UDF) с помощью скрипта R.

Скрипт получает табличные данные в качестве входных данных и создает табличные выходные данные. Среда выполнения подключаемого модуля размещается в песочнице на узлах кластера. Песочница предоставляет изолированную и безопасную среду.

Синтаксис

T|evaluate [hint.distribution= (single | per_node)] r(скрипт output_schema, [,script_parameters] [,external_artifacts])

Дополнительные сведения о соглашениях о синтаксисе.

Параметры

Имя	Тип	Обязательно	Описание
output_schema	`string`	✔️	Литерал `type` , определяющий схему вывода табличных данных, возвращаемых кодом R. Формат: `typeof(`ColumnName`:`ColumnType[, ...]`)`. Например: `typeof(col1:string, col2:long)`. Чтобы расширить входную схему, используйте следующий синтаксис: `typeof(*, col1:string, col2:long)`.
script	`string`	✔️	Допустимый скрипт R для выполнения.
script_parameters	`dynamic`		Контейнер свойств с парами "имя- значение", передаваемый в скрипт R в качестве зарезервированного `kargs` словаря. Дополнительные сведения см. в разделе Зарезервированные переменные R.
`hint.distribution`	`string`		Указание для распределения выполнения подключаемого модуля между несколькими узлами кластера. Значение по умолчанию — `single`. `single` означает, что один экземпляр скрипта будет выполняться по всем данным запроса. `per_node` означает, что если запрос перед блоком R будет распределен, экземпляр скрипта будет выполняться на каждом узле над содержащимися в нем данными.
external_artifacts	`dynamic`		Набор свойств, в который входят пары имен и URL-адресов для артефактов, доступных из облачного хранилища. Они могут быть доступны для скрипта для использования во время выполнения. URL-адреса, на которые ссылается этот контейнер свойств, должны быть включены в политику выноски кластера и в общедоступном расположении либо содержать необходимые учетные данные, как описано в строках подключения к хранилищу. Артефакты становятся доступными для использования скриптом из локального временного каталога `.\Temp`. Имена, указанные в контейнере свойств, используются в качестве имен локальных файлов. См . пример. Дополнительные сведения см. в разделе Установка пакетов для подключаемого модуля R.

Зарезервированные переменные R

Следующие переменные зарезервированы для взаимодействия между язык запросов Kusto и кодом R:

df: входные табличные данные (значения выше) в виде кадра T данных R.
kargs: значение аргумента script_parameters в виде словаря R.
result: кадр данных R, созданный скриптом R. Значение становится табличными данными, которые отправляются любому оператору запроса Kusto, который следует за подключаемым модулем.

Включение подключаемого модуля

Подключаемый модуль отключен по умолчанию.
Включите или отключите подключаемый модуль в портал Azure на вкладке Конфигурация кластера. Дополнительные сведения см. в статье Управление расширениями языка в кластере Azure Data Explorer (предварительная версия)

Изображение песочницы R

Образ песочницы R основан на R 3.4.4 для Windows и включает пакеты из пакета R Essentials Anaconda.

Примеры

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

Демонстрация синуса.

Советы по улучшению производительности

Уменьшите входной набор данных подключаемого модуля до минимально необходимого количества (столбцов или строк).
По возможности используйте фильтры для исходного набора данных с помощью язык запросов Kusto.
Чтобы выполнить вычисление для подмножества исходных столбцов, проецирование только этих столбцов перед вызовом подключаемого модуля.
Используйте hint.distribution = per_node каждый раз, когда логика в скрипте распространяется.
Вы также можете использовать оператор секционирования для секционирования входных данных et.

По возможности используйте язык запросов Kusto для реализации логики скрипта R.

Пример:

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

Советы по использованию

Чтобы избежать конфликтов между разделителями строк Kusto и разделителями строк R, выполните приведенные ниже действия.
- Используйте одинарные кавычки (') для строковых литералы Kusto в запросах Kusto.
- Используйте символы с двойными кавычками (") для строковых литералы R в скриптах R.
Используйте оператор внешних данных для получения содержимого скрипта, хранящегося во внешнем расположении, например в хранилище BLOB-объектов Azure или общедоступном репозитории GitHub.

Пример:
```
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 
```

Установка пакетов для подключаемого модуля R

Выполните эти пошаговые инструкции, чтобы установить пакеты, которые не включены в базовый образ подключаемого модуля.

Предварительные требования

Создайте контейнер больших двоичных объектов для размещения пакетов, желательно в том же месте, что и кластер. Например, предполагается, https://artifactswestus.blob.core.windows.net/rчто кластер находится в западной части США.
Измените политику выноски кластера, чтобы разрешить доступ к такому расположению.
- Для этого изменения требуются разрешения AllDatabasesAdmin .
- Например, чтобы разрешить доступ к большому двоичному объекту, расположенному в https://artifactswestus.blob.core.windows.net/r, выполните следующую команду:
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/r/","CanCall": true } ]'
```

Установка пакетов

В примерах фрагментов кода ниже предполагается локальный компьютер R в среде Windows.

Убедитесь, что вы используете соответствующую версию R. Текущая версия песочницы R — 3.4.4:
```
> R.Version()["version.string"]

$version.string
[1] "R version 3.4.4 (2018-03-15)"
```
При необходимости его можно скачать здесь.
Запустите X64 RGui
Создайте пустую папку для заполнения всеми соответствующими пакетами, которые вы хотите установить. В этом примере мы установим пакет brglm2, чтобы создать "C:\brglm2".
Добавьте только что созданный путь к папке к путям lib:
```
> .libPaths("C://brglm2")
```
Убедитесь, что новая папка теперь является первым путем в .libPaths():
```
> .libPaths()

[1] "C:/brglm2"    "C:/Program Files/R/R-3.4.4/library"
```
После завершения установки все устанавливаемые пакеты будут добавлены в эту новую папку. Давайте установим запрошенный пакет и его зависимости:
```
> install.packages("brglm2")
```
Если появится вопрос "Вы хотите установить из источников пакеты, которые нуждаются в компиляции?", ответьте "Y".
Убедитесь, что в "C:\brglm2" добавлены новые папки:
Выберите все элементы в этой папке и запакуйте их, например, libs.zip (не архивируйте родительскую папку). Вы должны получить структуру архива, как показано ниже:

libs.zip:
- brglm2 (папка)
- enrichwith (папка)
- numDeriv (папка)
Отправка libs.zip в контейнер BLOB-объектов, заданный выше
Вызовите подключаемый r модуль.
- external_artifacts Укажите параметр с именем контейнера свойств и ссылкой на ZIP-файл (URL-адрес BLOB-объекта, включая маркер SAS).
- Во встроенном коде r импортируйте zipfile из sandboxutils и вызовите его install() метод с именем ZIP-файла.

Пример

Установите пакет 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

Убедитесь, что имя архива (первое значение в паре пакетов) содержит суффикс *.zip, чтобы предотвратить конфликты при распакуировании папок, имя которых идентично имени архива.

Эта возможность не поддерживается.

Поделиться через