Plug-in do Python

  • Artigo

O plug-in do Python executa uma UDF (função definida pelo usuário) usando um script Python. O script Python obtém dados tabulares como sua entrada e produz a saída tabular. O runtime do plug-in é hospedado em áreas restritas, em execução nos nós do cluster.

Syntax

T|evaluate [hint.distribution= (single | per_node)] [hint.remote= (autolocal | )] python(scriptde output_schema, [,script_parameters] [,external_artifacts][,spill_to_disk])

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome Tipo Obrigatório Descrição
output_schema string ✔️ Um type literal que define o esquema de saída dos dados tabulares, retornados pelo código Python. O formato é: typeof(ColumnName:ColumnType[, ...]). Por exemplo, typeof(col1:string, col2:long). Para estender o esquema de entrada, use a seguinte sintaxe: typeof(*, col1:string, col2:long).
script string ✔️ O script Python válido a ser executado. Para gerar cadeias de caracteres de várias linhas, consulte Dicas de uso.
script_parameters dynamic Um recipiente de propriedades de pares de valor de nome a ser passado para o script Python como o dicionário reservado kargs . Para obter mais informações, consulte Variáveis reservadas do Python.
hint.distribution string Uma dica para que a execução do plug-in seja distribuída entre vários nós de cluster. O valor padrão é 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 do bloco do Python for distribuída, uma instância do script será executada em cada nó, nos dados que ele contém.
hint.remote string Essa dica só é relevante para consultas entre clusters. O valor padrão é auto. auto significa que o servidor decide automaticamente em qual cluster o código Python é executado. Definir o valor como local força a execução do código Python no cluster local. Use-o caso o plug-in do Python esteja desabilitado no cluster remoto.
external_artifacts dynamic Um recipiente de propriedades de pares de nome e URL para artefatos acessíveis do armazenamento em nuvem. Veja mais em Usando artefatos externos.
spill_to_disk bool Especifica um método alternativo para serializar a tabela de entrada para a área restrita do Python. Para serializar tabelas grandes, defina-a como true para acelerar a serialização e reduzir significativamente o consumo de memória da área restrita. O padrão é true.

Variáveis reservadas do Python

As variáveis a seguir são reservadas para interação entre Linguagem de Consulta 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.

Habilitar o plug-in

O plug-in está desabilitado por padrão. Antes de começar, examine a lista de pré-requisitos. Para habilitar o plug-in e selecionar a versão da imagem do Python, consulte Habilitar extensões de linguagem em seu cluster.

Imagem da área restrita do Python

Para alterar a versão da imagem do Python, consulte Alterar a imagem de extensões da linguagem Python no cluster.

Para ver a lista de pacotes para as diferentes imagens do Python, confira Referência de pacote do Python.

Observação

  • Por padrão, o plug-in importa numpy como np e pandas como pd. Opcionalmente, você pode importar outros módulos conforme necessário.
  • Alguns pacotes podem ser incompatíveis com as limitações impostas pela área restrita em que o plug-in é executado.

Usar a ingestão da política de consulta e atualização

  • Use o plug-in em consultas que são:
  • Você não pode usar o plug-in em uma consulta definida como parte de uma política de atualização, cuja tabela de origem é ingerida usando a ingestão de streaming.

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 tela da demonstração de seno mostrando 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"})
)
Arquivo Tamanho
this_is_a_script 120
this_is_my_first_file 105

Dicas de desempenho

  • Reduza o conjunto de dados de entrada do plug-in para a quantidade mínima necessária (colunas/linhas).
    • Use filtros no conjunto de dados de origem, quando possível, com a linguagem de consulta do Kusto.
    • Para fazer um cálculo em um subconjunto das colunas de origem, projegue apenas essas colunas antes de invocar o plug-in.
  • Use hint.distribution = per_node sempre que a lógica em seu script for distribuível.
  • Use a linguagem de consulta do Kusto sempre que possível para implementar a lógica do script Python.

Dicas de uso

  • Para gerar cadeias de caracteres de várias linhas que contêm o script Python em seu editor de consultas, copie o script Python do editor favorito do Python (Jupyter, Visual Studio Code, PyCharm e assim por diante), cole-o no editor de consultas e coloque o script completo entre as linhas que contêm três backticks consecutivos. Por exemplo:

    ```
    python code
    ```

  • Use o externaldata operador para obter o conteúdo de um script que você armazenou em um local externo, 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

Usando artefatos externos

Artefatos externos do armazenamento em nuvem podem ser disponibilizados para o script e usados em runtime.

As URLs referenciadas pela propriedade de artefatos externos devem ser:

Observação

Ao autenticar artefatos externos usando Identidades Gerenciadas, o SandboxArtifacts uso deve ser definido na política de identidade gerenciada no nível do cluster.

Os artefatos são disponibilizados para o script consumir de um diretório temporário local, .\Temp. Os nomes fornecidos no recipiente de propriedades são usados como os nomes de arquivo local. Veja os exemplos.

Para obter informações sobre como fazer referência a pacotes externos, consulte Instalar pacotes para o plug-in do Python.

Atualizando o cache de artefatos externos

Os arquivos de artefato externo utilizados em consultas são armazenados em cache no cluster. Se você fizer atualizações em seus arquivos no armazenamento em nuvem e exigir sincronização imediata com o cluster, poderá usar o comando .clear cluster cache external-artifacts. Esse comando limpa os arquivos armazenados em cache e garante que as consultas subsequentes sejam executadas com a versão mais recente dos artefatos.

Instalar pacotes para o plug-in do Python

Talvez seja necessário instalar pacotes por conta própria, pelos seguintes motivos:

  • O pacote é privado e é seu.
  • O pacote é público, mas não está incluído na imagem base do plug-in.

Instale pacotes da seguinte maneira:

Pré-requisitos

  1. Crie um contêiner de blob para hospedar os pacotes, preferencialmente no mesmo lugar que o cluster. Por exemplo, , https://artifactswestus.blob.core.windows.net/pythonsupondo que seu cluster esteja no Oeste dos EUA.

  2. Altere a política de texto explicativo do cluster para permitir o acesso a esse local.

    • Essa alteração requer permissões AllDatabasesAdmin .

    • Por exemplo, para habilitar 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 em outros canais, baixe o pacote e suas dependências.

    • Em uma janela cmd em seu ambiente local do Windows Python, execute:
    pip wheel [-w download-dir] package-name.

  2. Crie um arquivo zip que contenha o pacote necessário e suas dependências.

    • Para pacotes privados, zip a pasta do pacote e as pastas de suas dependências.
    • Para pacotes públicos, zip os arquivos que foram baixados na etapa anterior.

    Observação

    • Baixe o pacote compatível com o mecanismo do Python e a plataforma do runtime de área restrita (atualmente 3.6.5 no Windows)
    • Certifique-se de fechar os .whl arquivos por conta própria e não a pasta pai.
    • Você pode ignorar .whl arquivos para pacotes que já existem com a mesma versão na imagem de área restrita base.

  3. Carregue o arquivo compactado em um blob no local dos artefatos (da etapa 1).

  4. Chame o python plug-in.

    • Especifique o external_artifacts parâmetro com um pacote de propriedades de nome e faça referência ao arquivo zip (a URL do blob, incluindo um token SAS).
    • No código python embutido, importe Zipackage e sandbox_utils chame seu install() método com o nome do arquivo 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 Nome
1 Gary Tapia
2 Emma Evans
3 Ashley Bowen

Conteúdo relacionado

Para obter mais exemplos de funções UDF que usam o plug-in do Python, consulte a biblioteca Funções.

O plug-in do Python executa uma UDF (função definida pelo usuário) usando um script Python. O script Python obtém dados tabulares como sua entrada e produz a saída tabular.

Syntax

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

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome Tipo Obrigatório Descrição
output_schema string ✔️ Um type literal que define o esquema de saída dos dados tabulares, retornados pelo código Python. O formato é: typeof(ColumnName:ColumnType[, ...]). Por exemplo, typeof(col1:string, col2:long). Para estender o esquema de entrada, use a seguinte sintaxe: typeof(*, col1:string, col2:long).
script string ✔️ O script Python válido a ser executado. Para gerar cadeias de caracteres de várias linhas, consulte Dicas de uso.
script_parameters dynamic Um recipiente de propriedades de pares de valor de nome a ser passado para o script Python como o dicionário reservado kargs . Para obter mais informações, consulte Variáveis reservadas do Python.
hint.distribution string Uma dica para que a execução do plug-in seja distribuída entre vários nós de cluster. O valor padrão é 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 do bloco do Python for distribuída, uma instância do script será executada em cada nó, nos dados que ele contém.
hint.remote string Essa dica só é relevante para consultas entre clusters. O valor padrão é auto. auto significa que o servidor decide automaticamente em qual cluster o código Python é executado. Definir o valor como local força a execução do código Python no cluster local. Use-o caso o plug-in do Python esteja desabilitado no cluster remoto.
spill_to_disk bool Especifica um método alternativo para serializar a tabela de entrada para a área restrita do Python. Para serializar tabelas grandes, defina-a como true para acelerar a serialização e reduzir significativamente o consumo de memória da área restrita. O padrão é true.

Variáveis reservadas do Python

As variáveis a seguir são reservadas para interação entre Linguagem de Consulta 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.

Habilitar o plug-in

O plug-in está desabilitado por padrão. Antes de começar, habilite o plug-in do Python no banco de dados KQL.

Imagem da área restrita do Python

Para ver a lista de pacotes para as diferentes imagens do Python, confira Referência de pacote do Python.

Observação

  • Por padrão, o plug-in importa numpy como np e pandas como pd. Opcionalmente, você pode importar outros módulos conforme necessário.
  • Alguns pacotes podem ser incompatíveis com as limitações impostas pela área restrita em que o plug-in é executado.

Usar a ingestão da política de consulta e atualização

  • Use o plug-in em consultas que são:
  • Você não pode usar o plug-in em uma consulta definida como parte de uma política de atualização, cuja tabela de origem é ingerida usando a ingestão de streaming.

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 tela da demonstração de seno mostrando o resultado da consulta.

Dicas de desempenho

  • Reduza o conjunto de dados de entrada do plug-in para a quantidade mínima necessária (colunas/linhas).
    • Use filtros no conjunto de dados de origem, quando possível, com a linguagem de consulta do Kusto.
    • Para fazer um cálculo em um subconjunto das colunas de origem, projegue apenas essas colunas antes de invocar o plug-in.
  • Use hint.distribution = per_node sempre que a lógica em seu script for distribuível.
  • Use a linguagem de consulta do Kusto sempre que possível para implementar a lógica do script Python.

Dicas de uso

  • Para gerar cadeias de caracteres de várias linhas que contêm o script Python no editor de consultas, copie o script Python do editor favorito do Python (Jupyter, Visual Studio Code, PyCharm e assim por diante), cole-o no editor de consultas e coloque o script completo entre as linhas que contêm três backticks consecutivos. Por exemplo:

    ```
    python code
    ```

  • Use o externaldata operador para obter o conteúdo de um script que você armazenou em um local externo, 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 usam o plug-in do Python, consulte a biblioteca functions.

Não há suporte para essa funcionalidade.