R 插件（预览版）

R 插件使用 R 脚本运行用户定义的函数 (UDF)。

此脚本获取表格数据作为其输入，并生成表格输出。 插件的运行时承载在群集节点上的沙盒中。 沙盒提供隔离的安全环境。

语法

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

详细了解语法约定。

参数

客户	类型​​	必需	说明
output_schema	string	✔	type 文本，定义由 R 代码返回的表格数据的输出架构。 格式为：typeof(ColumnName:ColumnType[, ...])，例如 typeof(col1:string, col2:long)。 若要扩展输入架构，请使用以下语法：typeof(*, col1:string, col2:long)。
脚本	string	✔	要执行的有效 R 脚本。
script_parameters	dynamic		要作为保留的 kargs 字典传递给 R 脚本的名称和值对的属性包。 有关详细信息，请参阅保留的 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 数据资源管理器群集中的语言扩展（预览版）

R 沙盒映像

• R 沙盒映像基于 R 3.4.4 for Windows，并且包括来自 Anaconda's R Essentials 捆绑包的程序包。

示例

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。

• 还可以使用分区运算符对输入数据集进行分区。

• 请尽可能使用 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 字符串文本使用双引号字符 (")。

• 使用 externaldata 运算符获取存储在外部位置（例如 Azure Blob 存储或公共 GitHub 存储库）中的脚本内容。

  例如：

  let script = 
      externaldata(script:string)
      [h'https://kustoscriptsamples.blob.core.chinacloudapi.cn/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://artifactschinaeast2.blob.core.chinacloudapi.cn/r，假设群集位于中国东部 2。

2. 更改群集的标注策略以允许访问该位置。

   • 此更改需要 AllDatabasesAdmin 权限。

   • 例如，若要启用对位于 https://artifactschinaeast2.blob.core.chinacloudapi.cn/r 中的 blob 的访问，请运行以下命令：

   .alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactschinaeast2\\.blob\\.core\\.chinacloudapi\\.cn/r/","CanCall": true } ]'
   

安装包

下面的示例片段假定有一个处于 Windows 环境中的本地 R 计算机。

1. 验证使用的是否是适当的 R 版本 - 当前 R 沙盒版本为 3.4.4：

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

   如果需要，可以从此处下载它。

2. 启动 x64 RGui

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 上传到上面设置的 blob 容器

10. 调用 r 插件。

    • 使用一个包含名称和对 zip 文件（blob 的 URL，包括一个 SAS 令牌）的引用的属性包指定 external_artifacts 参数。
    • 在内联 r 代码中，从 sandboxutils 导入 zipfile 并使用 zip 文件的名称调用其 install() 方法。

示例

安装 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://artifactschinaeast2.blob.core.chinacloudapi.cn/r/libs.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))

x	ver
1	1.8.2

请确保存档的名称（包对中的第一个值）具有 *.zip 后缀，以防止在对名称与存档名称相同的文件夹进行解压缩时发生冲突。

---

不支持此功能。