Plug-in R (versão prévia)

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

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

Sintaxe

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

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Variáveis R reservadas

As seguintes variáveis são reservadas para interação entre a Linguagem de Consulta Kusto e o código R:

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

Habilitar o plug-in

• O plug-in está desabilitado 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 no cluster do Azure Data Explorer (versão prévia)

Imagem de área restrita do R

• A imagem da área restrita do R é baseada no R 3.4.4 para Windows e inclui pacotes do pacote R Essentials do 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 

Dicas de desempenho

• Reduza o conjunto de dados de entrada do plug-in 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 os dados de entrada et.

• Sempre que possível, use a Linguagem de Consulta Kusto para implementar a lógica do 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 de caracteres Kusto e delimitadores de cadeia de caracteres 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 armazenado 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 plug-in do R

Siga estas instruções passo a passo para instalar pacotes que não estão incluídos na imagem base do plug-in.

Pré-requisitos

1. Crie um contêiner de blob para hospedar os pacotes, preferencialmente no mesmo local que o cluster. Por exemplo, https://artifactswestus.blob.core.windows.net/rsupondo que o 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 em 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 recortes de exemplo abaixo pressupõem que o computador 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 RGui x64

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 "C:\brglm2".

4. Adicione o caminho da pasta recém-criado aos caminhos da 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 essa configuração, qualquer pacote que instalarmos será adicionado a essa nova pasta. Vamos instalar o pacote solicitado e suas dependências:

   > install.packages("brglm2")
   

   Caso a pergunta "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, por exemplo, libs.zip (não compacte a pasta pai). Você deve obter uma estrutura de arquivo como esta:

   libs.zip:

   • brglm2 (pasta)
   • enriquecer com (pasta)
   • numDeriv (pasta)

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

10. Chame o r plug-in.

    • Especifique o external_artifacts parâmetro com um recipiente de propriedades de name e referência ao arquivo ZIP (a URL do blob, incluindo um token SAS).
    • No 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) tenha o sufixo *.zip para evitar colisões ao descompactar pastas cujo nome é idêntico ao nome do arquivo.