Complemento de Python

  • Artículo

El complemento de Python ejecuta una función definida por el usuario (UDF) mediante un script de Python. El script de Python obtiene datos tabulares como entrada y genera una salida tabular. El entorno de ejecución del complemento se hospeda en espacios aislados, ejecutándose en los nodos del clúster.

Syntax

T|evaluate [ (single | per_node)] [hint.remotehint.distribution== (auto | local)] python(output_schema,script [,script_parameters] [,external_artifacts][,spill_to_disk])

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

Parámetros

Nombre Tipo Requerido Descripción
output_schema string ✔️ type Literal que define el esquema de salida de los datos tabulares devueltos por el código de Python. 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 Python válido que se va a ejecutar. Para generar cadenas de varias líneas, consulte Sugerencias de uso.
script_parameters dynamic Contenedor de propiedades de pares de valores de nombre que se pasarán al script de Python como diccionario reservado kargs . Para más información, consulte Variables reservadas de Python.
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 Python, se ejecutará una instancia del script en cada nodo, en los datos que contiene.
hint.remote string Esta sugerencia solo es relevante para las consultas entre clústeres. El valor predeterminado es auto. auto significa que el servidor decide automáticamente en qué clúster se ejecuta el código de Python. Establecer el valor en fuerza a local ejecutar el código de Python en el clúster local. Úselo en caso de que el complemento de Python esté deshabilitado en el clúster remoto.
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. Consulte más información en Uso de artefactos externos.
spill_to_disk bool Especifica un método alternativo para serializar la tabla de entrada en el espacio aislado de Python. Para serializar tablas grandes, establézcala para true acelerar la serialización y reducir significativamente el consumo de memoria del espacio aislado. El valor predeterminado es true.

Variables reservadas de Python

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

  • df: los datos tabulares de entrada (los valores anteriores T ), como dataframe pandas .
  • kargs: valor del argumento script_parameters , como diccionario de Python.
  • result: dataFrame pandas creado por el script de Python, cuyo valor se convierte en los datos tabulares que se envían al operador de consulta kusto que sigue al complemento.

Habilitación del complemento

El complemento está deshabilitado de forma predeterminada. Antes de empezar, revise la lista de requisitos previos. Para habilitar el complemento y seleccionar la versión de la imagen de Python, consulte Habilitación de extensiones de lenguaje en el clúster.

Imagen de espacio aislado de Python

Para cambiar la versión de la imagen de Python, consulte Cambio de la imagen de extensiones de lenguaje python en el clúster.

Para ver la lista de paquetes de las distintas imágenes de Python, consulte Referencia de paquetes de Python.

Nota

  • De forma predeterminada, el complemento importa numpy como np y pandas como pd. Opcionalmente, puede importar otros módulos según sea necesario.
  • Algunos paquetes podrían ser incompatibles con las limitaciones aplicadas por el espacio aislado donde se ejecuta el complemento.

Uso de la ingesta desde la consulta y la directiva de actualización

  • Use el complemento en las consultas que son:
  • No puede usar el complemento en una consulta que se define como parte de una directiva de actualización, cuya tabla de origen se ingiere mediante la ingesta de streaming.

Ejemplos

range x from 1 to 360 step 1
| evaluate python(
//
typeof(*, fx:double),               //  Output schema: append a new fx column to original table 
```
result = df
n = df.shape[0]
g = kargs["gain"]
f = kargs["cycles"]
result["fx"] = g * np.sin(df["x"]/n*2*np.pi*f)
```
, bag_pack('gain', 100, 'cycles', 4)    //  dictionary of parameters
)
| render linechart

Captura de pantalla de la demostración del seno que muestra el resultado de la consulta. 

print "This is an example for using 'external_artifacts'"
| evaluate python(
    typeof(File:string, Size:string), ```if 1:
    import os
    result = pd.DataFrame(columns=['File','Size'])
    sizes = []
    path = '.\\\\Temp'
    files = os.listdir(path)
    result['File']=files
    for file in files:
        sizes.append(os.path.getsize(path + '\\\\' + file))
    result['Size'] = sizes
    ```,
    external_artifacts = 
        dynamic({"this_is_my_first_file":"https://kustoscriptsamples.blob.core.windows.net/samples/R/sample_script.r",
                 "this_is_a_script":"https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py"})
)
Archivo Size
this_is_a_script 120
this_is_my_first_file 105

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, siempre que sea posible, con el lenguaje de consulta de Kusto.
    • 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 cada vez que se pueda distribuir la lógica del script.
  • Use el lenguaje de consulta de Kusto siempre que sea posible para implementar la lógica del script de Python.

Consejos de uso

  • Para generar cadenas de varias líneas que contengan el script de Python en el editor de consultas, copie el script de Python desde el editor de Python favorito (Jupyter, Visual Studio Code, PyCharm, etc.), péguelo en el editor de consultas y, a continuación, incluya el script completo entre líneas que contengan tres subprocesos consecutivos. Por ejemplo:

    ```
    python code
    ```

  • Use el externaldata operador para obtener el contenido de un script que ha almacenado en una ubicación externa, como Azure Blob Storage.

Ejemplo

    let script = 
        externaldata(script:string)
        [h'https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py']
        with(format = raw);
    range x from 1 to 360 step 1
    | evaluate python(
        typeof(*, fx:double),
        toscalar(script), 
        bag_pack('gain', 100, 'cycles', 4))
    | render linechart

Uso de artefactos externos

Los artefactos externos del almacenamiento en la nube pueden estar disponibles para el script y usarse en tiempo de ejecución.

Las direcciones URL a las que hace referencia la propiedad de artefactos externos deben ser:

Nota

Al autenticar artefactos externos mediante identidades administradas, el SandboxArtifacts uso debe definirse en la directiva de identidad administrada de nivel de clúster.

Los artefactos están disponibles para que el script consuma desde un directorio temporal local, .\Temp. Los nombres proporcionados en el contenedor de propiedades se usan como nombres de archivo locales. Ver ejemplos.

Para obtener información sobre cómo hacer referencia a paquetes externos, consulte Instalación de paquetes para el complemento de Python.

Actualización de la caché de artefactos externos

Los archivos de artefactos externos utilizados en las consultas se almacenan en caché en el clúster. Si realiza actualizaciones en los archivos en el almacenamiento en la nube y requiere una sincronización inmediata con el clúster, puede usar el comando .clear cluster cache external-artifacts. Este comando borra los archivos almacenados en caché y garantiza que las consultas posteriores se ejecuten con la versión más reciente de los artefactos.

Instalación de paquetes para el complemento de Python

Es posible que tenga que instalar los paquetes usted mismo, por los siguientes motivos:

  • El paquete es privado y es suyo propio.
  • El paquete es público, pero no se incluye en la imagen base del complemento.

Instale los paquetes de la siguiente manera:

Requisitos previos

  1. 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/python, suponiendo que el clúster está en Oeste de EE. UU.

  2. 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/python, ejecute el siguiente comando:

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

Instalar paquetes

  1. Para paquetes públicos en PyPi u otros canales, descargue el paquete y sus dependencias.

    • Desde una ventana cmd en el entorno local de Python de Windows, ejecute:
    pip wheel [-w download-dir] package-name.

  2. Cree un archivo ZIP que contenga el paquete necesario y sus dependencias.

    • En el caso de los paquetes privados, comprima la carpeta del paquete y las carpetas de sus dependencias.
    • En el caso de los paquetes públicos, comprima los archivos que se descargaron en el paso anterior.

    Nota

    • Asegúrese de descargar el paquete compatible con el motor de Python y la plataforma del entorno de ejecución del espacio aislado (actualmente 3.6.5 en Windows)
    • Asegúrese de comprimir los .whl propios archivos y no su carpeta primaria.
    • Puede omitir .whl los archivos de los paquetes que ya existen con la misma versión en la imagen de espacio aislado base.

  3. Cargue el archivo comprimido en un blob en la ubicación de artefactos (del paso 1).

  4. Llame al python 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 de Python insertado, importe Zipackage y sandbox_utils llame a su install() método con el nombre del archivo ZIP.

Ejemplo

Instale el paquete Faker que genera datos falsos.

range ID from 1 to 3 step 1 
| extend Name=''
| evaluate python(typeof(*), ```if 1:
    from sandbox_utils import Zipackage
    Zipackage.install("Faker.zip")
    from faker import Faker
    fake = Faker()
    result = df
    for i in range(df.shape[0]):
        result.loc[i, "Name"] = fake.name()
    ```,
    external_artifacts=bag_pack('faker.zip', 'https://artifacts.blob.core.windows.net/kusto/Faker.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))
ID Nombre
1 Gary Tapia
2 Emma Evans
3 Ashley Bowen

Contenido relacionado

Para obtener más ejemplos de funciones UDF que usan el complemento de Python, consulte la biblioteca de Functions.

El complemento de Python ejecuta una función definida por el usuario (UDF) mediante un script de Python. El script de Python obtiene datos tabulares como entrada y genera una salida tabular.

Syntax

T|evaluate [ (singleper_node | )] [hint.remote=hint.distribution= (autolocal | )] python(output_schema,script [,script_parameters] [,spill_to_disk])

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

Parámetros

Nombre Tipo Requerido Descripción
output_schema string ✔️ type Literal que define el esquema de salida de los datos tabulares devueltos por el código de Python. 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 Python válido que se va a ejecutar. Para generar cadenas de varias líneas, consulte Sugerencias de uso.
script_parameters dynamic Contenedor de propiedades de pares de valores de nombre que se pasarán al script de Python como diccionario reservado kargs . Para más información, consulte Variables reservadas de Python.
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 Python, se ejecutará una instancia del script en cada nodo, en los datos que contiene.
hint.remote string Esta sugerencia solo es relevante para las consultas entre clústeres. El valor predeterminado es auto. auto significa que el servidor decide automáticamente en qué clúster se ejecuta el código de Python. Establecer el valor en fuerza a local ejecutar el código de Python en el clúster local. Úselo en caso de que el complemento de Python esté deshabilitado en el clúster remoto.
spill_to_disk bool Especifica un método alternativo para serializar la tabla de entrada en el espacio aislado de Python. Para serializar tablas grandes, establézcala para true acelerar la serialización y reducir significativamente el consumo de memoria del espacio aislado. El valor predeterminado es true.

Variables reservadas de Python

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

  • df: los datos tabulares de entrada (los valores anteriores T ), como dataframe pandas .
  • kargs: valor del argumento script_parameters , como diccionario de Python.
  • result: dataFrame pandas creado por el script de Python, cuyo valor se convierte en los datos tabulares que se envían al operador de consulta kusto que sigue al complemento.

Habilitación del complemento

El complemento está deshabilitado de forma predeterminada. Antes de empezar, habilite el complemento de Python en la base de datos de KQL.

Imagen de espacio aislado de Python

Para ver la lista de paquetes de las distintas imágenes de Python, consulte Referencia de paquetes de Python.

Nota

  • De forma predeterminada, el complemento importa numpy como np y pandas como pd. Opcionalmente, puede importar otros módulos según sea necesario.
  • Algunos paquetes podrían ser incompatibles con las limitaciones aplicadas por el espacio aislado donde se ejecuta el complemento.

Uso de la ingesta desde la consulta y la directiva de actualización

  • Use el complemento en las consultas que son:
  • No puede usar el complemento en una consulta que se define como parte de una directiva de actualización, cuya tabla de origen se ingiere mediante la ingesta de streaming.

Ejemplos

range x from 1 to 360 step 1
| evaluate python(
//
typeof(*, fx:double),               //  Output schema: append a new fx column to original table 
```
result = df
n = df.shape[0]
g = kargs["gain"]
f = kargs["cycles"]
result["fx"] = g * np.sin(df["x"]/n*2*np.pi*f)
```
, bag_pack('gain', 100, 'cycles', 4)    //  dictionary of parameters
)
| render linechart

Captura de pantalla de la demostración del seno que muestra el resultado de la consulta.

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, siempre que sea posible, con el lenguaje de consulta de Kusto.
    • 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 cada vez que se pueda distribuir la lógica del script.
  • Use el lenguaje de consulta de Kusto siempre que sea posible para implementar la lógica del script de Python.

Consejos de uso

  • Para generar cadenas de varias líneas que contengan el script de Python en el editor de consultas, copie el script de Python desde el editor de Python favorito (Jupyter, Visual Studio Code, PyCharm, etc.), péguelo en el editor de consultas y, a continuación, incluya el script completo entre líneas que contengan tres subprocesos consecutivos. Por ejemplo:

    ```
    python code
    ```

  • Use el externaldata operador para obtener el contenido de un script que ha almacenado en una ubicación externa, como Azure Blob Storage.

Ejemplo

    let script = 
        externaldata(script:string)
        [h'https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py']
        with(format = raw);
    range x from 1 to 360 step 1
    | evaluate python(
        typeof(*, fx:double),
        toscalar(script), 
        bag_pack('gain', 100, 'cycles', 4))
    | render linechart

Contenido relacionado

Para obtener más ejemplos de funciones UDF que usan el complemento de Python, consulte la biblioteca de Functions.

Esta funcionalidad no se admite.