Plug-in python
O plug-in python executa uma função definida pelo utilizador (UDF) com um script python. O script python obtém dados tabulares como entrada e produz uma saída tabular. O runtime do plug-in está alojado em sandboxes, em execução nos nós do cluster.
Syntax
T|
evaluate
[hint.distribution
=
(single
| per_node
)] [hint.remote
=
(auto
| local
)] python(
output_schema,
script [,
script_parameters] [,
external_artifacts][,
spill_to_disk])
Saiba mais sobre as convenções de sintaxe.
Parâmetros
Nome | Tipo | Necessário | Descrição |
---|---|---|---|
output_schema | string |
✔️ | Um type literal que define o esquema de saída dos dados tabulares, devolvido pelo código Python. O formato é: typeof( ColumnName: ColumnType[, ...]) . Por exemplo, typeof(col1:string, col2:long) . Para expandir o esquema de entrada, utilize a seguinte sintaxe: typeof(*, col1:string, col2:long) . |
script | string |
✔️ | O script Python válido a executar. Para gerar cadeias de várias linhas, veja Sugestões de utilização. |
script_parameters | dynamic |
Um saco de propriedades de pares de valor de nome a ser transmitido para o script python como o dicionário reservado kargs . Para obter mais informações, veja Variáveis de Python Reservadas. |
|
hint.distribution | string |
Uma sugestão para que a execução do plug-in seja distribuída por vários nós de cluster. O valor predefinido é single . single significa que uma única instância do script será executada sobre todos os dados de consulta. per_node significa que, se a consulta antes do bloco Python ser distribuída, será executada uma instância do script em cada nó, nos dados que contém. |
|
hint.remote | string |
Esta sugestão só é relevante para consultas entre clusters. O valor predefinido é auto . auto significa que o servidor decide automaticamente em que cluster o código Python é executado. Definir o valor para forçar a local execução do código Python no cluster local. Utilize-o caso o plug-in python esteja desativado no cluster remoto. |
|
external_artifacts | dynamic |
Um saco de propriedades de pares de nome e URL para artefactos acessíveis a partir do armazenamento na cloud. Veja mais em Utilizar artefactos externos. | |
spill_to_disk | bool |
Especifica um método alternativo para serializar a tabela de entrada para o sandbox python. Para serializar tabelas grandes, defina-a para true acelerar a serialização e reduzir significativamente o consumo de memória do sandbox. A predefinição é true . |
Variáveis de Python Reservadas
As seguintes variáveis estão reservadas para interação entre Linguagem de Pesquisa Kusto e o código Python.
df
: os dados tabulares de entrada (os valores acimaT
), como umpandas
DataFrame.kargs
: o valor do argumento script_parameters , como um dicionário Python.result
: Umpandas
DataFrame criado pelo script python, cujo valor se torna os dados tabulares que são enviados para o operador de consulta Kusto que segue o plug-in.
Ativar o plug-in
O plug-in está desativado por predefinição. Antes de começar, reveja a lista de pré-requisitos. Para ativar o plug-in e selecionar a versão da imagem do Python, veja Ativar extensões de idioma no cluster.
Imagem do sandbox do Python
Para alterar a versão da imagem do Python, consulte Alterar a imagem de extensões de linguagem Python no cluster.
Para ver a lista de pacotes para as diferentes imagens do Python, veja Referência do pacote python.
Nota
- Por predefinição, o plug-in importa numpy como np e pandas como pd. Opcionalmente, pode importar outros módulos conforme necessário.
- Alguns pacotes podem ser incompatíveis com as limitações impostas pelo sandbox onde o plug-in é executado.
Utilizar a ingestão a partir da consulta e da política de atualização
- Utilize o plug-in em consultas que são:
- Definido como parte de uma política de atualização, cuja tabela de origem é ingerida para utilizar ingestão não de transmissão em fluxo .
- Execute como parte de um comando que ingere a partir de uma consulta, como
.set-or-append
.
- Não pode utilizar o plug-in numa consulta definida como parte de uma política de atualização, cuja tabela de origem é ingerida através da ingestão de transmissão em fluxo.
Exemplos
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"})
)
Ficheiro | Tamanho |
---|---|
this_is_a_script | 120 |
this_is_my_first_file | 105 |
Sugestões de desempenho
- Reduza o conjunto de dados de entrada do plug-in para a quantidade mínima necessária (colunas/linhas).
- Utilize filtros no conjunto de dados de origem, sempre que possível, com a linguagem de consulta do Kusto.
- Para fazer um cálculo num subconjunto das colunas de origem, projete apenas essas colunas antes de invocar o plug-in.
- Utilize
hint.distribution = per_node
sempre que a lógica no script for distribuível.- Também pode utilizar o operador de partição para criar partições do conjunto de dados de entrada.
- Utilize a linguagem de consulta do Kusto sempre que possível para implementar a lógica do script python.
Sugestões de utilização
Para gerar cadeias de várias linhas que contenham o script python no editor de consultas, copie o script python do seu editor de Python favorito (Jupyter, Visual Studio Code, PyCharm, etc.), cole-o no editor de consultas e, em seguida, coloque o script completo entre linhas que contenham três backticks consecutivos. Por exemplo:
```
python code
```
Utilize o
externaldata
operador para obter o conteúdo de um script que armazenou numa localização externa, como o armazenamento de Blobs do Azure.
Exemplo
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
Utilizar Artefactos Externos
Os artefactos externos do armazenamento na cloud podem ser disponibilizados para o script e utilizados no runtime.
Os URLs referenciados pela propriedade artefactos externos têm de ser:
- Incluído na política de nota de aviso do cluster.
- Numa localização publicamente disponível ou forneça as credenciais necessárias, conforme explicado nas cadeias de ligação de armazenamento.
Nota
Ao autenticar artefactos externos com Identidades Geridas, a SandboxArtifacts
utilização tem de ser definida na política de identidade gerida ao nível do cluster.
Os artefactos são disponibilizados para o script consumir a partir de um diretório temporário local, .\Temp
. Os nomes fornecidos no saco de propriedades são utilizados como nomes de ficheiros locais. Veja Exemplos.
Para obter informações sobre a referência a pacotes externos, veja Instalar pacotes para o plug-in do Python.
Atualizar cache de artefactos externos
Os ficheiros de artefactos externos utilizados em consultas são colocados em cache no cluster. Se fizer atualizações aos seus ficheiros no armazenamento na cloud e necessitar de sincronização imediata com o cluster, pode utilizar o comando .clear cluster cache external-artifacts. Este comando limpa os ficheiros em cache e garante que as consultas subsequentes são executadas com a versão mais recente dos artefactos.
Instalar pacotes para o plug-in do Python
Poderá ter de instalar o(s) pacote(s) por si próprio, pelos seguintes motivos:
- O pacote é privado e é seu.
- O pacote é público, mas não está incluído na imagem de base do plug-in.
Instale pacotes da seguinte forma:
Pré-requisitos
Crie um contentor de blobs para alojar os pacotes, preferencialmente no mesmo local que o cluster. Por exemplo,
https://artifactswestus.blob.core.windows.net/python
, partindo do princípio de que o cluster está nos E.U.A. Oeste.Altere a política de nota de aviso do cluster para permitir o acesso a essa localização.
Esta alteração requer permissões AllDatabasesAdmin .
Por exemplo, para ativar o acesso a um blob localizado em
https://artifactswestus.blob.core.windows.net/python
, execute o seguinte comando:
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/python/","CanCall": true } ]'
Instalar pacotes
Para pacotes públicos no PyPi ou noutros canais, transfira o pacote e as respetivas dependências.
- A partir de uma janela cmd no seu ambiente local do Windows Python, execute:
pip wheel [-w download-dir] package-name.
Crie um ficheiro zip que contenha o pacote necessário e as respetivas dependências.
- Para pacotes privados, zipe a pasta do pacote e as pastas das respetivas dependências.
- Para pacotes públicos, zipe os ficheiros que foram transferidos no passo anterior.
Nota
- Certifique-se de que transfere o pacote compatível com o motor Python e a plataforma do runtime do sandbox (atualmente 3.6.5 no Windows)
- Certifique-se de que zipa os
.whl
próprios ficheiros e não a respetiva pasta principal. - Pode ignorar
.whl
ficheiros para pacotes que já existem com a mesma versão na imagem do sandbox base.
Carregue o ficheiro zipado para um blob na localização dos artefactos (a partir do passo 1).
Chame o
python
plug-in.- Especifique o
external_artifacts
parâmetro com um conjunto de propriedades de nome e referência ao ficheiro zip (o URL do blob, incluindo um token de SAS). - No código python inline, importe
Zipackage
esandbox_utils
chame o respetivoinstall()
método com o nome do ficheiro zip.
- Especifique o
Exemplo
Instale o pacote Faker que gera dados 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 | Name |
---|---|
1 | Gary Tapia |
2 | Emma Evans |
3 | Ashley Bowen |
Conteúdo relacionado
Para obter mais exemplos de funções UDF que utilizam o plug-in python, veja a Biblioteca de funções.
O plug-in python executa uma função definida pelo utilizador (UDF) com um script python. O script de Python obtém dados tabulares como entrada e produz resultados tabulares.
Syntax
T|
evaluate
[hint.distribution
=
(single
| per_node
)] [hint.remote
=
(auto
| local
)] python(
output_schema,
script [,
script_parameters] [,
spill_to_disk])
Saiba mais sobre as convenções de sintaxe.
Parâmetros
Nome | Tipo | Necessário | Descrição |
---|---|---|---|
output_schema | string |
✔️ | Um type literal que define o esquema de saída dos dados tabulares, devolvido pelo código Python. O formato é: typeof( ColumnName: ColumnType[, ...]) . Por exemplo, typeof(col1:string, col2:long) . Para expandir o esquema de entrada, utilize a seguinte sintaxe: typeof(*, col1:string, col2:long) . |
script | string |
✔️ | O script de Python válido a executar. Para gerar cadeias de múltiplas linhas, veja Sugestões de utilização. |
script_parameters | dynamic |
Um conjunto de propriedades de pares de valores de nome para serem transmitidos para o script python como o dicionário reservado kargs . Para obter mais informações, veja Reserved Python variables (Variáveis reservadas do Python). |
|
hint.distribution | string |
Uma sugestão para que a execução do plug-in seja distribuída por vários nós de cluster. O valor predefinido é single . single significa que uma única instância do script será executada em todos os dados de consulta. per_node significa que, se a consulta antes da distribuição do bloco python, uma instância do script será executada em cada nó, nos dados que contém. |
|
hint.remote | string |
Esta sugestão só é relevante para consultas entre clusters. O valor predefinido é auto . auto significa que o servidor decide automaticamente em que cluster o código Python é executado. Definir o valor para forçar a local execução do código Python no cluster local. Utilize-o caso o plug-in do Python esteja desativado no cluster remoto. |
|
spill_to_disk | bool |
Especifica um método alternativo para serializar a tabela de entrada para o sandbox python. Para serializar tabelas grandes, defina-a para true acelerar a serialização e reduzir significativamente o consumo de memória do sandbox. A predefinição é true . |
Variáveis reservadas do Python
As seguintes variáveis estão reservadas para interação entre Linguagem de Pesquisa Kusto e o código Python.
df
: os dados tabulares de entrada (os valores acimaT
), como umpandas
DataFrame.kargs
: o valor do argumento script_parameters , como um dicionário Python.result
: umpandas
DataFrame criado pelo script do Python, cujo valor se torna os dados tabulares que são enviados para o operador de consulta Kusto que segue o plug-in.
Ativar o plug-in
O plug-in está desativado por predefinição. Antes de começar, ative o plug-in python na base de dados KQL.
Imagem do sandbox do Python
Para ver a lista de pacotes para as diferentes imagens do Python, veja Referência do pacote python.
Nota
- Por predefinição, o plug-in importa numpy como np e pandas como pd. Opcionalmente, pode importar outros módulos conforme necessário.
- Alguns pacotes podem ser incompatíveis com as limitações impostas pelo sandbox onde o plug-in é executado.
Utilizar a ingestão da consulta e da política de atualização
- Utilize o plug-in em consultas que são:
- Definido como parte de uma política de atualização, cuja tabela de origem é ingerida para utilizar ingestão não de transmissão em fluxo .
- Execute como parte de um comando que ingere a partir de uma consulta, como
.set-or-append
.
- Não pode utilizar o plug-in numa consulta definida como parte de uma política de atualização, cuja tabela de origem é ingerida através da ingestão de transmissão em fluxo.
Exemplos
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
Sugestões de desempenho
- Reduza o conjunto de dados de entrada do plug-in para a quantidade mínima necessária (colunas/linhas).
- Utilize filtros no conjunto de dados de origem, sempre que possível, com a linguagem de consulta do Kusto.
- Para fazer um cálculo num subconjunto das colunas de origem, projete apenas essas colunas antes de invocar o plug-in.
- Utilize
hint.distribution = per_node
sempre que a lógica no script for distribuível.- Também pode utilizar o operador de partição para criar partições do conjunto de dados de entrada.
- Utilize a linguagem de consulta do Kusto sempre que possível para implementar a lógica do script do Python.
Sugestões de utilização
Para gerar cadeias de múltiplas linhas que contenham o script de Python no editor de consultas, copie o script de Python do seu editor de Python favorito (Jupyter, Visual Studio Code, PyCharm, etc.), cole-o no editor de consultas e, em seguida, coloque o script completo entre linhas que contenham três backticks consecutivos. Por exemplo:
```
python code
```
Utilize o
externaldata
operador para obter o conteúdo de um script que armazenou numa localização externa, como o armazenamento de Blobs do Azure.
Exemplo
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
Conteúdo relacionado
Para obter mais exemplos de funções UDF que utilizam o plug-in python, veja a Biblioteca de funções.
Esta capacidade não é suportada.
Comentários
https://aka.ms/ContentUserFeedback.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários