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

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

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

Синтаксис

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

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

Параметры

Зарезервированные переменные 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

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

Необходимые компоненты

1. Создайте контейнер BLOB-объектов для размещения пакетов, желательно в том же месте, что и кластер. Например, предположим, что https://artifactswestus.blob.core.windows.net/rкластер находится в западной части США.

2. Измените политику выноски кластера, чтобы разрешить доступ к такому расположению.

   • Для этого изменения требуются разрешения 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.

1. Убедитесь, что вы используете соответствующую версию R: текущая версия песочницы R — 3.4.4:

   > R.Version()["version.string"]
   
   $version.string
   [1] "R version 3.4.4 (2018-03-15)"
   

   При необходимости его можно скачать здесь.

2. Запуск RGui x64

3. Создайте пустую папку для заполнения всех соответствующих пакетов, которые вы хотите установить. В этом примере мы устанавливаем пакет brglm2, поэтому создадим "C:\brglm2".

4. Добавьте только что созданный путь к папке в пути lib:

   > .libPaths("C://brglm2")
   

5. Убедитесь, что новая папка теперь является первым путем в .libPaths():

   > .libPaths()
   
   [1] "C:/brglm2"    "C:/Program Files/R/R-3.4.4/library"
   
   

6. После завершения установки в эту новую папку будет добавлен любой пакет, который мы установим. Давайте установим запрошенный пакет и его зависимости:

   > install.packages("brglm2")
   

   Если появится вопрос "Требуется ли установить из источников пакеты, необходимые для компиляции?", ответьте "Y".

7. Убедитесь, что в C:\brglm2 добавлены новые папки:

   

8. Выберите все элементы в этой папке и запакуйте их, например libs.zip (не запакуйте родительскую папку). Вы должны получить архивную структуру следующим образом:

   libs.zip:

   • brglm2 (папка)
   • enrichwith (папка)
   • numDeriv (папка)

9. Отправка libs.zip в контейнер БОЛЬШИХ двоичных объектов, заданный выше

10. Вызов подключаемого r модуля.

    • external_artifacts Укажите параметр с контейнером свойств имени и ссылкой на ZIP-файл (URL-адрес большого двоичного объекта, включая маркер 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 ***'))

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