Plugin de Python

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

Sintaxe

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 convenções de sintaxe.

Parâmetros

Variáveis Python reservadas

As variáveis a seguir são reservadas para interação entre Kusto Query Language 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 plugin.

Ativar o plugin

O plugin está desativado por padrão. Antes de começar, revise a lista de pré-requisitos. Para ativar o plug-in e selecionar a versão da imagem do Python, consulte Ativar extensões de linguagem no cluster.

Imagem de sandbox do Python

Para alterar a versão da imagem Python para uma imagem gerenciada diferente ou uma imagem personalizada, consulte Alterar a imagem de extensões de linguagem Python no cluster.

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

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

• Use o plugin em consultas que são:
  • Definido como parte de uma política de atualização, cuja tabela de origem é ingerida por ingestão em fila.
  • Executar como parte de um comando que ingere a partir de uma consulta, como .set-or-append.
• 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 ingestão de streaming.

Exemplo

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 plugin 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, projete apenas essas colunas antes de invocar o plugin.
• Use hint.distribution = per_node sempre que a lógica em seu script for distribuível.
  • Você também pode usar o operador de partição para particionar o conjunto de dados de entrada.
• Use a linguagem de consulta do Kusto sempre que possível, para implementar a lógica do seu script Python.

Dicas de uso

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

  ```
python code
```

• Use o operador externaldata para obter o conteúdo de um script que você armazenou em um local externo, como o armazenamento de Blob do Azure.

Exemplo de leitura dos dados externos do script 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 

Usando artefatos externos

Artefatos externos do armazenamento em nuvem podem ser disponibilizados para o script e usados em tempo de execução.

As URLs referenciadas pela propriedade de artefatos externos devem ser:

• Incluído na política de texto explicativo do cluster.
• Em um local disponível publicamente ou forneça as credenciais necessárias, conforme explicado em cadeias de conexão de armazenamento.

Os artefatos são disponibilizados para que o script seja lido a partir de um diretório temporário local, .\Temp. Os nomes fornecidos no pacote de propriedades são usados como os nomes de arquivo local. Ver Exemplo.

Para obter informações sobre como referenciar pacotes externos, consulte Instalar pacotes para o plug-in Python.

Atualizando o cache de artefatos externos

Os arquivos de artefatos externos 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 seu 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 plugin Python

Na maioria dos casos de uso, você pode preferir criar uma imagem personalizada.

Você pode querer instalar o(s) pacote(s) por conta própria, pelos seguintes motivos:

• Você não tem permissões para criar uma imagem personalizada.
• O pacote é privado.
• Você prefere criar uma instalação de pacote ad hoc para teste e não quer a sobrecarga de criar uma imagem personalizada.

Instale os pacotes da seguinte forma:

Pré-requisitos

1. Crie um contêiner de blob para hospedar os pacotes, de preferência no mesmo local do 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 no 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 em PyPi ou 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 contendo o pacote necessário e suas dependências.

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

   Observação

   • Certifique-se de baixar o pacote que é compatível com o mecanismo Python e a plataforma do tempo de execução da sandbox (atualmente 3.10.8 ou 3.11.7 no Windows)
   • Certifique-se de compactar os próprios arquivos, e não a .whl 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 zip para um blob no local dos artefatos (a partir da etapa 1 dos pré-requisitos).

4. Ligue para o python plugin.

   • Especifique o external_artifacts parâmetro com um conjunto de propriedades de nome local e URL de blob do arquivo zip (incluindo um token SAS).
   • Em seu código python embutido, importe Zipackage e sandbox_utils chame seu install() método com o nome local do arquivo ZIP.

Exemplo usando artefatos externos

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/Faker.zip;impersonate'))

Conteúdo relacionado

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

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

Sintaxe

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 convenções de sintaxe.

Parâmetros

Variáveis Python reservadas

As variáveis a seguir são reservadas para interação entre Kusto Query Language 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 plugin.

Ativar o plugin

O plugin está desativado por padrão. Antes de começar, ative o plug-in Python em seu banco de dados KQL.

Imagem de sandbox do Python

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

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

• Use o plugin em consultas que são:
  • Definido como parte de uma política de atualização, cuja tabela de origem é ingerida por ingestão em fila.
  • Executar como parte de um comando que ingere a partir de uma consulta, como .set-or-append.
• 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 ingestão de streaming.

Exemplo

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 plugin 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, projete apenas essas colunas antes de invocar o plugin.
• Use hint.distribution = per_node sempre que a lógica em seu script for distribuível.
  • Você também pode usar o operador de partição para particionar o conjunto de dados de entrada.
• Use a linguagem de consulta do Kusto sempre que possível, para implementar a lógica do seu script Python.

Dicas de uso

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

  ```
python code
```

• Use o operador externaldata para obter o conteúdo de um script que você armazenou em um local externo, como o armazenamento de Blob do Azure.

Exemplo de leitura dos dados externos do script 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 

Usando artefatos externos

Artefatos externos do armazenamento OneLake podem ser disponibilizados para o script e usados em tempo de execução.

Os artefatos são disponibilizados para que o script seja lido a partir de um diretório temporário local, .\Temp. Os nomes fornecidos no pacote de propriedades são usados como os nomes de arquivo local. Ver Exemplo.

Para obter informações sobre como referenciar pacotes externos, consulte Instalar pacotes para o plug-in Python.

Atualizando o cache de artefatos externos

Os arquivos de artefatos externos 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 seu 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 plugin Python

Instale os pacotes da seguinte forma:

Pré-requisito

• Crie uma lakehouse para hospedar os pacotes, de preferência no mesmo espaço de trabalho da sua casa de eventos.

Instalar pacotes

1. Para pacotes públicos em PyPi ou 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 contendo o pacote necessário e suas dependências.

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

   Observação

   • Certifique-se de baixar o pacote que é compatível com o mecanismo Python e a plataforma do tempo de execução da sandbox (atualmente 3.10.8 ou 3.11.7 no Windows)
   • Certifique-se de compactar os próprios arquivos, e não a .whl 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 zip para a casa do lago.

4. Copie a URL do OneLake (das propriedades do arquivo compactado)

5. Ligue para o python plugin.

   • Especifique o external_artifacts parâmetro com um pacote de propriedades de nome local e URL OneLake do arquivo zip.
   • Em seu código python embutido, importe Zipackage e sandbox_utils chame seu install() método com o nome do arquivo ZIP.

Exemplo usando artefatos externos

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

Conteúdo relacionado

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