Plug-in do Python

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer

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.

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

Parâmetros

Nome	Digitar	Obrigatória	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([, ...]:. Por exemplo, . Para estender o esquema de entrada, use a seguinte sintaxe: typeof(*, col1:string, col2:long).
roteiro	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 valores de nome a serem passados 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 a execução do plug-in a ser distribuída entre várias áreas restritas. O valor padrão é single. single significa que uma única instância do script será executada sobre todos os dados de consulta em uma única área restrita. per_node significa que, se a consulta antes do bloco do Python for distribuída para partições, cada partição será executada em sua própria área restrita em paralelo.
dica.remoto	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 para local forçar a execução do código Python no cluster local. Use-o caso o plug-in Python esteja desabilitado no cluster remoto.
external_artifacts	dynamic		Um recipiente de propriedades de nomes e pares de URL para artefatos que podem ser acessados no armazenamento do OneLake. 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-o para true 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 a 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 de sandbox Python

Para ver a lista de pacotes para as diferentes imagens do Python, consulte 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 sandbox onde 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:
  • Definido como parte de uma política de atualização, cuja tabela de origem é ingerida pela ingestão na fila.
  • Execute como parte de um comando que ingere 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 a 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 

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, projete 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.
  • 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 no editor de consultas, copie o script Python do editor Python favorito (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 acentos graves consecutivos. Por exemplo:

  ```
python code
```

• Use o operador externaldata para obter o conteúdo de um script armazenado em um local externo, como o Armazenamento de Blobs 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 do OneLake podem ser disponibilizados para o script e usados em runtime.

Os artefatos são disponibilizados para que o script seja lido de um diretório temporário local. .\Temp Os nomes fornecidos no recipiente de propriedades são usados como os nomes de arquivo locais. Veja Exemplo.

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

Atualizando o cache de artefato externo

Os arquivos de artefato externos utilizados em consultas são armazenados em cache no cluster. Se você fizer atualizações em seus arquivos no armazenamento em nuvem e precisar de 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 plug-in Python

Instale os pacotes da seguinte maneira:

Pré-requisito

• Crie um lakehouse para hospedar os pacotes, preferencialmente no mesmo workspace que sua casa de eventos.

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

   • Baixe o pacote compatível com o mecanismo python e a plataforma do runtime de área restrita (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 sandbox base.

3. Carregue o arquivo zip no lakehouse.

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

5. Chame o python plug-in.

   • Especifique o external_artifacts parâmetro com um recipiente de propriedades de nome local e a URL do OneLake do arquivo zip.
   • Em seu código python embutido, importe Zipackagesandbox_utils e 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'))

Número de Identificação	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 Python, consulte a biblioteca de funções.