Plug-in python

  • Artigo

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 acima T ), como um pandas DataFrame.
  • kargs: o valor do argumento script_parameters , como um dicionário Python.
  • result: Um pandas 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:
  • 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

Captura de ecrã a mostrar a demonstração sine a mostrar o resultado da 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"})
)
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.
  • 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:

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

  1. 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.

  2. 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

  1. 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.

  2. 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.

  3. Carregue o ficheiro zipado para um blob na localização dos artefactos (a partir do passo 1).

  4. 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 e sandbox_utils chame o respetivo install() método com o nome do ficheiro zip.

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 acima T ), como um pandas DataFrame.
  • kargs: o valor do argumento script_parameters , como um dicionário Python.
  • result: um pandas 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:
  • 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

Captura de ecrã da demonstração sine a mostrar o resultado da consulta.

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.
  • 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.