Compartilhar via

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

  • Artigo

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

O script obtém dados tabulares como sua entrada e produz a saída tabular. O runtime do plug-in é hospedado em uma área restrita nos nós do cluster. A área restrita fornece um ambiente isolado e seguro.

Syntax

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

Nome Tipo Obrigatório Descrição
output_schema string ✔️ Um type literal que define o esquema de saída dos dados tabulares, retornado pelo código R. O formato é: typeof(ColumnName:ColumnType[, ...]). Por exemplo: typeof(col1:string, col2:long). Para estender o esquema de entrada, use a seguinte sintaxe: typeof(*, col1:string, col2:long).
script string ✔️ O script R válido a ser executado.
script_parameters dynamic Um recipiente de propriedades de pares de nome e valor a ser passado para o script R como o dicionário reservado kargs . Para obter mais informações, consulte Variáveis reservadas do R.
hint.distribution string Dica para que a execução do plug-in seja distribuída entre vários nós de cluster. O valor padrão é single. single significa que uma única instância do script será executada em todos os dados de consulta. per_node significa que, se a consulta antes do bloco R for distribuída, uma instância do script será executada em cada nó sobre os dados que ele contém.
external_artifacts dynamic Um recipiente de propriedades de pares de nome e URL para artefatos acessíveis do armazenamento em nuvem. Eles podem ser disponibilizados para o script usar em runtime. As URLs referenciadas neste recipiente de propriedades precisam ser incluídas na política de texto explicativo do cluster e em um local disponível publicamente ou conter as credenciais necessárias, conforme explicado nas cadeias de conexão de armazenamento. Os artefatos são disponibilizados para o script consumir de um diretório temporário local, .\Temp. Os nomes fornecidos no recipiente de propriedades são usados como os nomes de arquivo local. Consulte Exemplo. Para obter mais informações, consulte Instalar pacotes para o plug-in do R.

Variáveis reservadas do R

As variáveis a seguir são reservadas para interação entre 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 R criado pelo script 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

Imagem da área restrita do R

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

Demonstração de seno.

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 o Linguagem de Consulta Kusto, quando possível.

  • Para fazer um cálculo em um subconjunto das colunas de origem, projetem 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 o 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 que você armazenou em um local externo, como o Armazenamento de Blobs do Azure ou um repositório GitHub público.

    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 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 lugar que o cluster. Por exemplo, https://artifactswestus.blob.core.windows.net/r, supondo 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 snips de exemplo abaixo pressupõem que o computador R local no ambiente windows.

  1. Verifique se você está usando a versão apropriada do R – a versão atual do R Sandbox é a 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 daqui.

  2. Iniciar o RGui x64

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

  4. Adicione o caminho da pasta recém-criado aos caminhos de biblioteca:

    > .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. Depois que essa configuração for concluída, 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 de fontes os pacotes que precisam de compilação?" apareça, responda "Y".

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

    Captura de tela do conteúdo do diretório da biblioteca.

  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 arquivos como esta:

    libs.zip:

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

  9. Carregar libs.zip no contêiner de blob que foi definido acima

  10. Chame o r plug-in.

    • Especifique o external_artifacts parâmetro com um recipiente de propriedades de nome 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 ***'))
x ver
1 1.8.2

Verifique se 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 morto.

Não há suporte para essa funcionalidade.