Compartir a través de


Complemento de Python

Se aplica a: ✅Microsoft FabricAzure Data Explorer

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 tiempo de ejecución del complemento se hospeda en espacios aislados, ejecutándose en los nodos del clúster.

Sintaxis

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

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 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 valor de nombre que se van a pasar 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 sola instancia del script se ejecutará en todos los datos de consulta. per_node significa que si la consulta anterior al bloque de Python se distribuye, una instancia del script se ejecutará 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 a otra imagen administrada o una imagen personalizada, 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 pueden ser incompatibles con las limitaciones que aplica el espacio aislado en el que 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:
    • Se define como parte de una directiva de actualización, cuya tabla de origen se ingiere para usar la ingesta sin streaming .
    • Ejecute como parte de un comando que ingiere desde una consulta, como .set-or-append.
  • No puede usar el complemento en una consulta definida 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 de 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 siempre que la lógica del script sea distribuible.
    • También puede usar el operador de partición para crear particiones en el conjunto de datos de entrada.
  • 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 del 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 contienen tres acentos posteriores 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 lo 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 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

En la mayoría de los casos de uso, es posible que prefiera crear una imagen personalizada.

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

  • No tiene permisos para crear una imagen personalizada.
  • El paquete es privado.
  • Prefiere crear una instalación de paquetes ad hoc para las pruebas y no desea que la sobrecarga de crear una imagen personalizada.

Instale los paquetes de la manera siguiente:

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 se encuentra 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 los paquetes públicos en PyPi u otros canales, descargue el paquete y sus dependencias.

    • Desde una ventana cmd del 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 de 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 los 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 desde sandbox_utils y 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/Faker.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))
ID Nombre
1 Gary Tapia
2 Emma Evans
3 Ashley Bowen

Para obtener más ejemplos de funciones de 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.

Sintaxis

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

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 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 valor de nombre que se van a pasar 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 sola instancia del script se ejecutará en todos los datos de consulta. per_node significa que si la consulta anterior al bloque de Python se distribuye, una instancia del script se ejecutará 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 pueden ser incompatibles con las limitaciones que aplica el espacio aislado en el que 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:
    • Se define como parte de una directiva de actualización, cuya tabla de origen se ingiere para usar la ingesta sin streaming .
    • Ejecute como parte de un comando que ingiere desde una consulta, como .set-or-append.
  • No puede usar el complemento en una consulta definida 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 de 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 siempre que la lógica del script sea distribuible.
    • También puede usar el operador de partición para crear particiones en el conjunto de datos de entrada.
  • 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 del 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 contienen tres acentos posteriores 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 

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