R plugin (pré-visualização)

O plug-in R executa uma função definida pelo usuário (UDF) usando um script R.

O script obtém dados tabulares como sua entrada e produz saída tabular. O tempo de execução do plug-in é hospedado em uma área restrita nos nós do cluster. O sandbox fornece um ambiente isolado e seguro.

Sintaxe

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

Saiba mais sobre convenções de sintaxe.

Parâmetros

Variáveis R reservadas

As seguintes variáveis são reservadas para interação entre Kusto Query Language e o código R:

• df: Os dados tabulares de entrada (os valores acima T ), como um R DataFrame.
• kargs: O valor do argumento script_parameters , como um dicionário R.
• result: Um DataFrame R criado pelo script R. O valor torna-se os dados tabulares que são enviados para qualquer operador de consulta Kusto que siga o plugin.

Ativar o plugin

• O plugin está desativado por padrão.
• Habilite ou desabilite o plug-in no portal do Azure na guia Configuração do cluster. Para obter mais informações, consulte Gerenciar extensões de idioma em seu cluster do Azure Data Explorer (visualização)

Imagem de sandbox R

• A imagem da área restrita R é baseada na R 3.4.4 para Windows e inclui pacotes do pacote R Essentials da Anaconda.

Exemplos

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 

Sugestões de desempenho

• Reduza o conjunto de dados de entrada do plugin para a quantidade mínima necessária (colunas/linhas).

• Use filtros no conjunto de dados de origem usando a Linguagem de Consulta Kusto, quando possível.

• Para fazer um cálculo em um subconjunto das colunas de origem, projete apenas essas colunas antes de invocar o plug-in.

• Use hint.distribution = per_node sempre que a lógica em seu script for distribuível.

• Você também pode usar o operador de partição para particionar o conjunto de dados de entrada.

• Sempre que possível, use a Kusto Query Language para implementar a lógica do seu script R.

  Por exemplo:

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

Dicas de uso

• Para evitar conflitos entre delimitadores de cadeia Kusto e delimitadores de cadeia R:

  • Use caracteres de aspas simples (') para literais de cadeia de caracteres Kusto em consultas Kusto.
  • Use caracteres de aspas duplas (") para literais de cadeia de caracteres R em scripts R.

• Use o operador de dados externos para obter o conteúdo de um script que você armazenou em um local externo, como o armazenamento de blobs do Azure ou um repositório público do GitHub.

  Por exemplo:

  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 
  

Instalar pacotes para o plugin R

Siga estas instruções passo a passo para instalar pacote(s) que não estão incluídos na imagem base do plugin.

Pré-requisitos

1. Crie um contêiner de blob para hospedar os pacotes, de preferência no mesmo local do cluster. Por exemplo, https://artifactswestus.blob.core.windows.net/rsupondo que seu cluster esteja no oeste dos EUA.

2. Altere a política de texto explicativo do cluster para permitir o acesso a esse local.

   • Essa alteração requer permissões AllDatabasesAdmin .

   • Por exemplo, para habilitar o acesso a um blob localizado no https://artifactswestus.blob.core.windows.net/r, execute o seguinte comando:

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

Instalar pacotes

Os trechos de exemplo abaixo assumem a máquina R local no ambiente Windows.

1. Verifique se você está usando a versão R apropriada – a versão atual do R Sandbox é 3.4.4:

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

   Se necessário, você pode baixá-lo aqui.

2. Inicie o x64 RGui

3. Crie uma nova pasta vazia para ser preenchida com todos os pacotes relevantes que você gostaria de instalar. Neste exemplo, instalamos o pacote brglm2, criando assim "C:\brglm2".

4. Adicione o caminho da pasta recém-criada aos caminhos lib:

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

5. Verifique se a nova pasta é agora o primeiro caminho em .libPaths():

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

6. Uma vez feita esta configuração, qualquer pacote que instalamos será adicionado a esta nova pasta. Vamos instalar o pacote solicitado e suas dependências:

   > install.packages("brglm2")
   

   Caso a pergunta "Você deseja instalar a partir de fontes os pacotes que precisam de compilação?" apareça, responda "Y".

7. Verifique se novas pastas foram adicionadas a "C:\brglm2":

   

8. Selecione todos os itens nessa pasta e compacte-os para, por exemplo, libs.zip (não compacte a pasta pai). Você deve obter uma estrutura de arquivo como esta:

   libs.zip:

   • brglm2 (pasta)
   • enrichwith (pasta)
   • numDeriv (pasta)

9. Carregue libs.zip para o contêiner de blob definido acima

10. Ligue para o r plugin.

    • Especifique o external_artifacts parâmetro com um conjunto de propriedades de nome e referência ao arquivo ZIP (URL do blob, incluindo um token SAS).
    • No seu código r embutido, importe zipfile e sandboxutils chame seu install() método com o nome do arquivo ZIP.

Exemplo

Instale o pacote 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 ***'))

Certifique-se de que o nome do arquivo (primeiro valor no par de pacotes) tem o sufixo *.zip para evitar colisões ao descompactar pastas cujo nome é idêntico ao nome do arquivo.