Plug-in Python

Si applica a: ✅Microsoft Fabric✅Azure Esplora dati

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

Sintassi

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

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome	Digita	Obbligatorio	Descrizione
output_schema	string	✔️	Valore type letterale che definisce lo schema di output dei dati tabulari, restituito dal codice Python. Il formato è ColumnName typeof(: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 nome valore 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 nei dati 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. L'impostazione del 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.
spill_to_disk	bool		Specifica un metodo alternativo per serializzare la tabella di input nella sandbox Python. Per serializzare tabelle di grandi dimensioni impostarla 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 pandas dataframe.
• kargs: valore dell'argomento script_parameters , come dizionario Python.
• resultpandas: dataframe 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 di default. 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 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 che sono:
  • Definito come parte di un criterio di aggiornamento, la cui tabella di origine viene inserita per l'uso dell'inserimento non in streaming .
  • Eseguire come parte di un comando che inserisce da una query, ad esempio .set-or-append.
• 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.

Esempi

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 

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.
  • È anche possibile usare l'operatore partition per partizionare il set di dati di input.
• Usare il linguaggio di query di Kusto, quando possibile, per implementare la logica dello script Python.

Suggerimenti per l'uso

• Per generare stringhe su 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'operatore externaldata 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 

Contenuto correlato

Per altri esempi di funzioni definite dall'utente che usano il plug-in Python, vedere la libreria funzioni.