Complemento de Python
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.remote
hint.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 anterioresT
), como dataframepandas
.kargs
: valor del argumento script_parameters , como diccionario de Python.result
: dataFramepandas
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:
- Se define como parte de una directiva de actualización, cuya tabla de origen se ingiere para usar la ingesta de no streaming .
- Ejecute como parte de un comando que ingiere desde una consulta, como
.set-or-append
.
- 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
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.- También puede usar el operador de partición para particionar 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 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:
- Se incluye en la directiva de llamada del clúster.
- En una ubicación disponible públicamente o proporcione las credenciales necesarias, como se explica en cadenas de conexión de almacenamiento.
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
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.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
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.
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.
Cargue el archivo comprimido en un blob en la ubicación de artefactos (del paso 1).
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
ysandbox_utils
llame a suinstall()
método con el nombre del archivo ZIP.
- Especifique el
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
[ (single
per_node
| )] [hint.remote
=
hint.distribution
=
(auto
local
| )] 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 anterioresT
), como dataframepandas
.kargs
: valor del argumento script_parameters , como diccionario de Python.result
: dataFramepandas
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:
- Se define como parte de una directiva de actualización, cuya tabla de origen se ingiere para usar la ingesta de no streaming .
- Ejecute como parte de un comando que ingiere desde una consulta, como
.set-or-append
.
- 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
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.- También puede usar el operador de partición para particionar 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 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.
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea:Enviar y ver comentarios de