R プラグイン (プレビュー)

R プラグインは、R スクリプトを使用してユーザー定義関数 (UDF) を実行します。

このスクリプトは、表形式のデータを入力として取得し、表形式の出力を生成します。 プラグインのランタイムはクラスタのノード上のサンドボックスでホストされます。 サンドボックスは、分離された安全な環境を提供します。

構文

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

構文規則について詳しく知る。

パラメーター

名前	型	必須	説明
output_schema	string	✔️	type R コードによって返される表形式データの出力スキーマを定義するリテラル。 形式は ColumnName:typeof(ColumnType[, ...] です)。たとえば、 ですtypeof(col1:string, col2:long)。 入力スキーマを拡張するには、typeof(*, col1:string, col2:long) という構文を使用します。
script	string	✔️	実行する有効な R スクリプト。
script_parameters	dynamic		予約済み kargs ディクショナリとして R スクリプトに渡される名前と値のペアのプロパティ バッグ。 詳しくは、「予約済み R 変数」を参照してください。
hint.distribution	string		プラグインの実行を複数のクラスター ノードに分散するためのヒント。 既定値は single です。 single は、スクリプトの 1 つのインスタンスがクエリ データ全体で実行されることを意味します。 per_node は、R ブロックの前のクエリが分散されている場合、スクリプトのインスタンスが、含まれているデータを介して各ノードで実行されることを意味します。
external_artifacts	dynamic		クラウド ストレージからアクセスできる成果物の名前と URL のペアのプロパティ バッグ。 実行時にスクリプトで使用できるように設定できます。 このプロパティ バッグで参照される URL は、ストレージ接続文字列で説明されているように、クラスターの吹き出しポリシーと一般公開されている場所に含めるか、必要な資格情報を含める必要があります。 成果物は、スクリプトがローカルの一時ディレクトリ (.\Temp) から使用できます。 プロパティ バッグに指定された名前は、ローカル ファイル名として使用されます。 「例」を参照してください。 詳細については、「R プラグインのパッケージをインストールする」を参照してください。

予約済み R 変数

次の変数は、Kusto クエリ言語と R コード間のやり取りのために予約されています。

• df: R DataFrame としての入力表形式データ (上記の T の値)。
• kargs: 引数 script_parameters の値を R 辞書として指定します。
• result: R スクリプトで作成された R DataFrame。 値は、プラグインに従う任意の Kusto クエリ演算子に送信される表形式のデータになります。

プラグインの有効化

• 既定では、このオプションが無効になっています。
• クラスターの [構成] タブで、Azure portal のプラグインを有効または無効にします。 詳細については、「Azure Data Explorer クラスターでの言語拡張機能の管理 (プレビュー)」を参照してください。

R サンドボックス イメージ

• R Sandbox イメージは R 3.4.4 for Windows に基き、Anaconda の R Essentials bundle からのパッケージを含んでいます。

例

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 文字列リテラルに二重引用符文字 ( " ) を使用します。

• 外部データ演算子を使用して、Azure BLOB ストレージ やパブリック 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 にある BLOB にアクセスできるようにするには、次のコマンドを実行します。

   .alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/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. 新しく作成したフォルダー パスをライブラリ パスに追加します。

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

5. 新しいフォルダーが .libPaths() の最初のパスになっていることを確認します。

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

6. この設定が完了すると、インストールするすべてのパッケージがこの新しいフォルダーに追加されます。 要求パッケージとその依存関係をインストールしてみましょう。

   > install.packages("brglm2")
   

   "Do you want to install from sources the packages which need compilation? (ソースからコンパイルが必要なパッケージをインストールしますか)" という質問が表示された場合は、"Y" で答えます。

7. 新しいフォルダーが "C:\brglm2" に追加されたことを確認します。

   

8. そのフォルダー内のすべての項目を選択し、libs.zip などに圧縮します (親フォルダーを圧縮しないでください)。 次のようなアーカイブ構造になっている必要があります。

   libs.zip:

   • brglm2 (フォルダー)
   • enrichwith (フォルダー)
   • numDeriv (フォルダー)

9. 上記で設定した BLOB コンテナーに libs.zip をアップロードします

10. r プラグインを呼び出します。

    • external_artifacts パラメーターに、zip ファイルの名前と参照 (SAS トークンを含む BLOB の URL) からなるプロパティ バッグを指定します。
    • インライン 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://artifactswestus.blob.core.windows.net/r/libs.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))

x	ver
1	1.8.2

アーカイブ名 (パック ペアの最初の値) に *.zip サフィックスが付いていることを確認し、アーカイブ名と同じ名前のフォルダーを解凍する際の競合を防ぎます。

---

この機能はサポートされていません。