Complemento de Python

Se aplica a: ✅Microsoft Fabric✅Azure 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.

Sintaxis

T|evaluate [hint.distribution= (singleper_node | )] [hint.remote= (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	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 espacios aislados. El valor predeterminado es single. single significa que una sola instancia del script se ejecutará en todos los datos de consulta en un único espacio aislado. per_node significa que si la consulta antes del bloque de Python se distribuye a las particiones, cada partición se ejecutará en su propio espacio aislado en paralelo.
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 nombres y direcciones URL para artefactos a los que se puede acceder desde OneLake Storage. 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, 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 mediante la ingesta en cola.
  • 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.

Ejemplo

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 

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 operador externaldata para obtener el contenido de un script que ha almacenado en una ubicación externa, como Azure Blob Storage.

Ejemplo de lectura de los datos externos del script de Python

    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 de OneLake Storage pueden estar disponibles para el script y usarse en tiempo de ejecución.

Los artefactos están disponibles para que el script se lea 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 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

Instale los paquetes de la manera siguiente:

Prerrequisito

• Cree una instancia de Lakehouse para hospedar los paquetes, preferiblemente en la misma área de trabajo que el centro de eventos.

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.10.8 o 3.11.7 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 ZIP en lakehouse.

4. Copie la dirección URL de OneLake (desde las propiedades del archivo comprimido)

5. Llame al python complemento.

   • Especifique el external_artifacts parámetro con un contenedor de propiedades del nombre local y la dirección URL de OneLake del archivo ZIP.
   • 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 de uso de artefactos externos

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://msit-onelake.dfs.fabric.microsoft.com/MSIT_DEMO_WS/MSIT_DEMO_LH.Lakehouse/Files/Faker.zip;impersonate'))

identificación	Nombre
1	Gary Tapia
2	Emma Evans
3	Ashley Bowen

Contenido relacionado

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