Plug-in Python

  • Articolo

Il plug-in Python esegue una funzione definita dall'utente usando uno script Python. Lo script Python ottiene i dati tabulari come input e produce un output tabulare. Il runtime del plug-in è ospitato in sandbox, in esecuzione nei nodi del cluster.

Sintassi

T|evaluate [hint.distribution= (single | per_node)] [hint.remote= (auto | local)] python(scriptoutput_schema, [script_parameters] [,,external_artifacts][,spill_to_disk])

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome Tipo Obbligatoria Descrizione
output_schema string ✔️ Valore type letterale che definisce lo schema di output dei dati tabulari, restituito dal codice Python. Il formato è: typeof(ColumnName:ColumnType[, ...]). Ad esempio, typeof(col1:string, col2:long). Per estendere lo schema di input, usare la sintassi seguente: typeof(*, col1:string, col2:long).
script string ✔️ Script Python valido da eseguire. Per generare stringhe su più righe, vedere Suggerimenti sull'utilizzo.
script_parameters dynamic Contenitore di proprietà di coppie valore nome da passare allo script Python come dizionario riservato kargs . Per altre informazioni, vedere Variabili Python riservate.
hint.distribution string Suggerimento per l'esecuzione del plug-in da distribuire tra più nodi del cluster. Il valore predefinito è single. single significa che una singola istanza dello script verrà eseguita sull'intero dati della query. per_node significa che se la query prima della distribuzione del blocco Python, un'istanza dello script verrà eseguita in ogni nodo, sui dati in esso contenuti.
hint.remote string Questo hint è rilevante solo per le query tra cluster. Il valore predefinito è auto. auto indica che il server decide automaticamente in quale cluster viene eseguito il codice Python. Impostando il valore su local forza l'esecuzione del codice Python nel cluster locale. Usarlo nel caso in cui il plug-in Python sia disabilitato nel cluster remoto.
external_artifacts dynamic Contenitore di proprietà di coppie nome e URL per gli artefatti accessibili dall'archiviazione cloud. Per altre informazioni, vedere Uso di artefatti esterni.
spill_to_disk bool Specifica un metodo alternativo per serializzare la tabella di input nella sandbox Python. Per la serializzazione di tabelle di grandi dimensioni, impostarla su per true velocizzare la serializzazione e ridurre significativamente il consumo di memoria sandbox. Il valore predefinito è true.

Variabili Python riservate

Le variabili seguenti sono riservate per l'interazione tra Linguaggio di query Kusto e il codice Python.

  • df: dati tabulari di input (i valori di T sopra), come dataframe pandas .
  • kargs: valore dell'argomento script_parameters , come dizionario Python.
  • result: dataframe pandas creato dallo script Python, il cui valore diventa i dati tabulari inviati all'operatore di query Kusto che segue il plug-in.

Abilitare il plug-in

Il plug-in è disabilitato per impostazione predefinita. Prima di iniziare, esaminare l'elenco dei prerequisiti. Per abilitare il plug-in e selezionare la versione dell'immagine Python, vedere Abilitare le estensioni del linguaggio nel cluster.

Immagine sandbox python

Per modificare la versione dell'immagine Python, vedere Modificare l'immagine delle estensioni del linguaggio Python nel cluster.

Per visualizzare l'elenco dei pacchetti per le diverse immagini Python, vedere Informazioni di riferimento sui pacchetti Python.

Nota

  • Per impostazione predefinita, il plug-in importa numpy come np e pandas come pd. Facoltativamente, è possibile importare altri moduli in base alle esigenze.
  • Alcuni pacchetti potrebbero non essere compatibili con le limitazioni applicate dalla sandbox in cui viene eseguito il plug-in.

Usare l'inserimento da criteri di query e aggiornamento

  • Usare il plug-in nelle query seguenti:
  • Non è possibile usare il plug-in in una query definita come parte di un criterio di aggiornamento, la cui tabella di origine viene inserita usando l'inserimento in streaming.

Esempio

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

Screenshot della demo sine che mostra il risultato della query. 

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"})
)
File Dimensione
this_is_a_script 120
this_is_my_first_file 105

Suggerimenti per incrementare le prestazioni

  • Ridurre il set di dati di input del plug-in alla quantità minima richiesta (colonne/righe).
    • Usare i filtri nel set di dati di origine, quando possibile, con il linguaggio di query di Kusto.
    • Per eseguire un calcolo su un subset delle colonne di origine, proiettare solo le colonne prima di richiamare il plug-in.
  • Usare hint.distribution = per_node ogni volta che la logica nello script è distribuibile.
  • Usare il linguaggio di query di Kusto, quando possibile, per implementare la logica dello script Python.

Suggerimenti per l'uso

  • Per generare stringhe a più righe contenenti lo script Python nell'editor di query, copiare lo script Python dall'editor Python preferito (Jupyter, Visual Studio Code, PyCharm e così via), incollarlo nell'editor di query e quindi racchiudere lo script completo tra le righe contenenti tre backtick consecutivi. Ad esempio:

    ```
    python code
    ```

  • Usare l'operatoreexternaldata per ottenere il contenuto di uno script archiviato in una posizione esterna, ad esempio Archiviazione BLOB di Azure.

Esempio

    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

Uso di artefatti esterni

Gli artefatti esterni dall'archiviazione cloud possono essere resi disponibili per lo script e usati in fase di esecuzione.

Gli URL a cui fa riferimento la proprietà degli artefatti esterni devono essere:

Nota

Quando si autenticano artefatti esterni usando identità gestite, l'utilizzo SandboxArtifacts deve essere definito nei criteri di identità gestita a livello di cluster.

Gli artefatti vengono resi disponibili per l'utilizzo dello script da una directory temporanea locale, .\Temp. I nomi specificati nel contenitore delle proprietà vengono usati come nomi di file locali. Vedere Esempi.

Per informazioni sul riferimento a pacchetti esterni, vedere Installare i pacchetti per il plug-in Python.

Aggiornamento della cache degli artefatti esterni

I file di artefatti esterni utilizzati nelle query vengono memorizzati nella cache nel cluster. Se si apportano aggiornamenti ai file nell'archiviazione cloud e si richiede una sincronizzazione immediata con il cluster, è possibile usare il comando con estensione clear cluster cache external-artifacts. Questo comando cancella i file memorizzati nella cache e garantisce che le query successive vengano eseguite con la versione più recente degli artefatti.

Installare pacchetti per il plug-in Python

Potrebbe essere necessario installare i pacchetti, per i motivi seguenti:

  • Il pacchetto è privato ed è il proprio.
  • Il pacchetto è pubblico, ma non è incluso nell'immagine di base del plug-in.

Installare i pacchetti come indicato di seguito:

Prerequisiti

  1. Creare un contenitore BLOB per ospitare i pacchetti, preferibilmente nella stessa posizione del cluster. Ad esempio, presupponendo https://artifactswestus.blob.core.windows.net/pythonche il cluster si trova negli Stati Uniti occidentali.

  2. Modificare i criteri di callout del cluster per consentire l'accesso a tale posizione.

    • Questa modifica richiede autorizzazioni AllDatabasesAdmin .

    • Ad esempio, per abilitare l'accesso a un BLOB che si trova in https://artifactswestus.blob.core.windows.net/python, eseguire il comando seguente:

    .alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/python/","CanCall": true } ]'

Installare i pacchetti

  1. Per i pacchetti pubblici in PyPi o in altri canali, scaricare il pacchetto e le relative dipendenze.

    • Da una finestra cmd nell'ambiente Python locale eseguire:
    pip wheel [-w download-dir] package-name.

  2. Creare un file zip contenente il pacchetto richiesto e le relative dipendenze.

    • Per i pacchetti privati, zip la cartella del pacchetto e le cartelle delle relative dipendenze.
    • Per i pacchetti pubblici, zip i file scaricati nel passaggio precedente.

    Nota

    • Assicurarsi di scaricare il pacchetto compatibile con il motore Python e la piattaforma del runtime sandbox (attualmente 3.6.5 in Windows)
    • Assicurarsi di comprimere i .whl file stessi e non della cartella padre.
    • È possibile ignorare .whl i file per i pacchetti già esistenti con la stessa versione nell'immagine sandbox di base.

  3. Caricare il file compresso in un BLOB nel percorso degli artefatti (dal passaggio 1).

  4. Chiamare il python plug-in.

    • Specificare il external_artifacts parametro con un contenitore di proprietà di nome e riferimento al file zip (URL del BLOB, incluso un token di firma di accesso condiviso).
    • Nel codice python inline importare Zipackagesandbox_utils e chiamare il install() relativo metodo con il nome del file zip.

Esempio

Installare il pacchetto Faker che genera dati falsi.

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

Contenuti correlati

Per altri esempi di funzioni UDF che usano il plug-in Python, vedere la libreria funzioni.

Il plug-in Python esegue una funzione definita dall'utente usando uno script Python. Lo script Python ottiene dati tabulari come input e produce output tabulare.

Sintassi

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

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome Tipo Obbligatoria Descrizione
output_schema string ✔️ Valore type letterale che definisce lo schema di output dei dati tabulari restituiti dal codice Python. Il formato è: typeof(ColumnName:ColumnType[, ...]). Ad esempio, typeof(col1:string, col2:long). Per estendere lo schema di input, usare la sintassi seguente: typeof(*, col1:string, col2:long).
script string ✔️ Script Python valido da eseguire. Per generare stringhe a più righe, vedere Suggerimenti sull'utilizzo.
script_parameters dynamic Un contenitore di proprietà di coppie valore nome da passare allo script Python come dizionario riservato kargs . Per altre informazioni, vedere Variabili Python riservate.
hint.distribution string Suggerimento per l'esecuzione del plug-in da distribuire in più nodi del cluster. Il valore predefinito è single. single significa che una singola istanza dello script verrà eseguita sull'intero dati della query. per_node significa che se la query prima che il blocco Python venga distribuito, un'istanza dello script verrà eseguita in ogni nodo, nei dati che contiene.
hint.remote string Questo hint è rilevante solo per le query tra cluster. Il valore predefinito è auto. auto significa che il server decide automaticamente in quale cluster viene eseguito il codice Python. Impostando il valore su forza l'esecuzione local del codice Python nel cluster locale. Usarlo nel caso in cui il plug-in Python sia disabilitato nel cluster remoto.
spill_to_disk bool Specifica un metodo alternativo per serializzare la tabella di input nella sandbox Python. Per la serializzazione di grandi tabelle impostate per true velocizzare la serializzazione e ridurre significativamente il consumo di memoria sandbox. Il valore predefinito è true.

Variabili Python riservate

Le variabili seguenti sono riservate per l'interazione tra Linguaggio di query Kusto e il codice Python.

  • df: i dati tabulari di input (i valori di T sopra), come pandas dataframe.
  • kargs: valore dell'argomento script_parameters , come dizionario Python.
  • result: dataframe pandas creato dallo script Python, il cui valore diventa i dati tabulari inviati all'operatore di query Kusto che segue il plug-in.

Abilitare il plug-in

Il plug-in è disabilitato per impostazione predefinita. Prima di iniziare, abilitare il plug-in Python nel database KQL.

Immagine sandbox python

Per visualizzare l'elenco dei pacchetti per le diverse immagini Python, vedere Riferimento al pacchetto Python.

Nota

  • Per impostazione predefinita, il plug-in importa numpy come np e pandas come pd. Facoltativamente, è possibile importare altri moduli in base alle esigenze.
  • Alcuni pacchetti potrebbero non essere compatibili con le limitazioni applicate dalla sandbox in cui viene eseguito il plug-in.

Usare l'inserimento da criteri di query e aggiornamento

  • Usare il plug-in nelle query che sono:
  • Non è possibile usare il plug-in una query definita come parte di un criterio di aggiornamento, la cui tabella di origine viene inserita usando l'inserimento in streaming.

Esempio

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

Screenshot della demo sine che mostra il risultato della query.

Suggerimenti per incrementare le prestazioni

  • Ridurre il set di dati di input del plug-in alla quantità minima richiesta (colonne/righe).
    • Usare i filtri nel set di dati di origine, quando possibile, con il linguaggio di query di Kusto.
    • Per eseguire un calcolo su un subset delle colonne di origine, proiettare solo queste colonne prima di richiamare il plug-in.
  • Usare hint.distribution = per_node ogni volta che la logica nello script è distribuibile.
  • Usare il linguaggio di query di Kusto ogni volta che possibile, per implementare la logica dello script Python.

Suggerimenti per l'uso

  • Per generare stringhe multilinea contenenti lo script Python nell'editor di query, copiare lo script Python dall'editor Python preferito (Jupyter, Visual Studio Code, PyCharm e così via), incollarlo nell'editor di query e quindi racchiudere lo script completo tra le righe contenenti tre backtick consecutivi. Ad esempio:

    ```
    python code
    ```

  • Usare l'operatoreexternaldata per ottenere il contenuto di uno script archiviato in un percorso esterno, ad esempio Archiviazione BLOB di Azure.

Esempio

    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

Contenuti correlati

Per altri esempi di funzioni UDF che usano il plug-in Python, vedere la libreria funzioni.

Questa funzionalità non è supportata.