Complemento R (versión preliminar)

Artículo
07/04/2024

El complemento de R ejecuta una función definida por el usuario (UDF) mediante un script de R.

El script obtiene datos tabulares como entrada y genera una salida tabular. El entorno de ejecución del complemento se hospeda en un espacio aislado en los nodos del clúster. El espacio aislado proporciona un entorno aislado y seguro.

Sintaxis

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

Obtenga más información sobre las convenciones de sintaxis.

Parámetros

Nombre	Type	Obligatorio	Descripción
output_schema	`string`	✔️	Literal `type` que define el esquema de salida de los datos tabulares, devuelto por el código de R. El formato es: `typeof(`ColumnName`:` ColumnType[, ...]`)`. Por ejemplo: `typeof(col1:string, col2:long)`. Para ampliar el esquema de entrada, use la sintaxis siguiente: `typeof(*, col1:string, col2:long)`.
Script	`string`	✔️	Script de R válido que se va a ejecutar.
script_parameters	`dynamic`		Contenedor de propiedades de pares de nombre y valor que se van a pasar al script de R como diccionario reservado `kargs` . Para obtener más información, consulte Variables reservadas de R.
`hint.distribution`	`string`		Sugerencia para que la ejecución del complemento se distribuya entre varios nodos de clúster. El valor predeterminado es `single`. `single` significa que una única instancia del script se ejecutará en todos los datos de consulta. `per_node` significa que si se distribuye la consulta antes del bloque de R, una instancia del script se ejecutará en cada nodo sobre los datos que contiene.
external_artifacts	`dynamic`		Contenedor de propiedades de pares de nombre y dirección URL para artefactos a los que se puede acceder desde el almacenamiento en la nube. Pueden estar disponibles para que el script se use en tiempo de ejecución. Las direcciones URL a las que se hace referencia en este contenedor de propiedades deben incluirse en la directiva de llamada del clúster y en una ubicación disponible públicamente, o contener las credenciales necesarias, como se explica en los cadena de conexión de almacenamiento. Los artefactos están disponibles para que el script lo consuma desde un directorio temporal local, `.\Temp`. Los nombres proporcionados en el contenedor de propiedades se usan como nombres de archivo locales. Consulte Ejemplo. Para obtener más información, consulte Instalación de paquetes para el complemento de R.

Variables reservadas de R

Las siguientes variables están reservadas para la interacción entre Lenguaje de consulta Kusto y el código de R:

df: los datos tabulares de entrada (los valores anteriores T ), como dataframe de R.
kargs: el valor del argumento script_parameters , como un diccionario de R.
result: un dataframe de R creado por el script de R. El valor se convierte en los datos tabulares que se envían a cualquier operador de consulta de Kusto que siga al complemento.

Habilitación del complemento

El complemento está deshabilitado de forma predeterminada.
Habilite o deshabilite el complemento en Azure Portal en la pestaña Configuración del clúster. Para más información, consulte Administración de extensiones de lenguaje en el clúster de Azure Data Explorer (versión preliminar)

Imagen de espacio aislado de R

La imagen de espacio aislado de R se basa en R 3.4.4 para Windows e incluye paquetes de la agrupación R Essentials de Anaconda.

Ejemplos

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

Demostración de Sine.

Consejos de rendimiento

Reduzca el conjunto de datos de entrada del complemento a la cantidad mínima necesaria (columnas o filas).
Use filtros en el conjunto de datos de origen mediante el Lenguaje de consulta Kusto, siempre que sea posible.
Para realizar un cálculo en un subconjunto de las columnas de origen, proyecta solo esas columnas antes de invocar el complemento.
Use hint.distribution = per_node siempre que la lógica del script sea distribuible.
También puede usar el operador de partición para crear particiones de los datos de entrada et.

Siempre que sea posible, use el Lenguaje de consulta Kusto para implementar la lógica del script de R.

Por ejemplo:

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

Consejos de uso

Para evitar conflictos entre delimitadores de cadena de Kusto y delimitadores de cadenas de R:
- Use caracteres de comillas simples (') para literales de cadena kusto en consultas de Kusto.
- Use caracteres de comillas dobles (") para literales de cadena de R en scripts de R.

Use el operador de datos externos para obtener el contenido de un script que ha almacenado en una ubicación externa, como Azure Blob Storage o un repositorio público de GitHub.

Por ejemplo:

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

Instalación de paquetes para el complemento de R

Siga estas instrucciones paso a paso para instalar paquetes que no se incluyen en la imagen base del complemento.

Requisitos previos

Cree un contenedor de blobs para hospedar los paquetes, preferiblemente en el mismo lugar que el clúster. Por ejemplo, https://artifactswestus.blob.core.windows.net/r, suponiendo que el clúster se encuentra en Oeste de EE. UU.
Modifique la directiva de llamada del clúster para permitir el acceso a esa ubicación.
- Este cambio requiere permisos AllDatabasesAdmin .
- Por ejemplo, para habilitar el acceso a un blob ubicado en https://artifactswestus.blob.core.windows.net/r, ejecute el siguiente comando:
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/r/","CanCall": true } ]'
```

Instalar paquetes

En los ejemplos siguientes se da por supuesto que la máquina R local en el entorno de Windows.

Compruebe que usa la versión de R adecuada: la versión actual del espacio aislado de R es la 3.4.4:
```
> R.Version()["version.string"]

$version.string
[1] "R version 3.4.4 (2018-03-15)"
```
Si es necesario, puede descargarlo desde aquí.
Inicio de RGui x64
Cree una carpeta vacía que se rellenará con todos los paquetes pertinentes que desea instalar. En este ejemplo se instala el paquete brglm2, por lo que se crea "C:\brglm2".
Agregue la ruta de acceso de carpeta recién creada a las rutas de acceso lib:
```
> .libPaths("C://brglm2")
```
Compruebe que la nueva carpeta es ahora la primera ruta de acceso de .libPaths():
```
> .libPaths()

[1] "C:/brglm2"    "C:/Program Files/R/R-3.4.4/library"
```
Una vez finalizada esta configuración, cualquier paquete que instalemos se agregará a esta nueva carpeta. Vamos a instalar el paquete solicitado y sus dependencias:
```
> install.packages("brglm2")
```
En caso de que aparezca la pregunta "¿Desea instalar desde orígenes los paquetes que necesitan compilación?", responda "Y".
Compruebe que se agregaron nuevas carpetas a "C:\brglm2":
Seleccione todos los elementos de esa carpeta y comprimalos en, por ejemplo, libs.zip (no comprima la carpeta primaria). Debería obtener una estructura de archivo de la siguiente manera:

libs.zip:
- brglm2 (carpeta)
- enrichwith (carpeta)
- numDeriv (carpeta)
Carga libs.zip en el contenedor de blobs que se estableció anteriormente
Llame al r complemento.
- Especifique el external_artifacts parámetro con un contenedor de propiedades de nombre y referencia al archivo ZIP (la dirección URL del blob, incluido un token de SAS).
- En el código r insertado, importe zipfile desde sandboxutils y llame a su install() método con el nombre del archivo ZIP.

Ejemplo

Instale el paquete 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

Asegúrese de que el nombre del archivo (primer valor en el par del paquete) tenga el sufijo *.zip para evitar colisiones al descomprimir carpetas cuyo nombre sea idéntico al nombre de archivo.

Esta funcionalidad no se admite.

Compartir a través de