Python-Plug-In

Gilt für: ✅Microsoft Fabric✅Azure Data Explorer

Das Python-Plug-In führt eine benutzerdefinierte Funktion (User-Defined Function, UDF) mithilfe eines Python-Skripts aus. Das Python-Skript ruft tabellarische Daten als Eingabe ab und erzeugt eine tabellarische Ausgabe.

Syntax

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

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name	Type	Erforderlich	Beschreibung
output_schema	string	✔️	Ein type Literal, das das Ausgabeschema der tabellarischen Daten definiert, die vom Python-Code zurückgegeben wird. Das Format lautet: typeof(ColumnName: ColumnType[, ...]). Beispiel: typeof(col1:string, col2:long). Verwenden Sie die folgende Syntax, um das Eingabeschema zu erweitern: typeof(*, col1:string, col2:long)
Skript	string	✔️	Das zu ausführende gültige Python-Skript. Informationen zum Generieren von mehrzeiligen Zeichenfolgen finden Sie in den Verwendungstipps.
script_parameters	dynamic		Ein Eigenschaftenbehälter mit Namenwertpaaren, die als reserviertes kargs Wörterbuch an das Python-Skript übergeben werden sollen. Weitere Informationen finden Sie unter Reservierte Python-Variablen.
hint.distribution	string		Ein Hinweis auf die Ausführung des Plug-Ins, die über mehrere Clusterknoten verteilt werden sollen. Der Standardwert ist single. single bedeutet, dass eine einzelne Instanz des Skripts über die gesamten Abfragedaten ausgeführt wird. per_node bedeutet: Wenn die Abfrage vor der Verteilung des Python-Blocks ausgeführt wird, wird eine Instanz des Skripts auf jedem Knoten auf den darin enthaltenen Daten ausgeführt.
hint.remote	string		Dieser Hinweis ist nur für clusterübergreifende Abfragen relevant. Der Standardwert ist auto. auto bedeutet, dass der Server automatisch entscheidet, in welchem Cluster der Python-Code ausgeführt wird. Festlegen des Werts, um die Ausführung des Python-Codes im lokalen Cluster zu local erzwingen. Verwenden Sie es, falls das Python-Plug-In auf dem Remotecluster deaktiviert ist.
spill_to_disk	bool		Gibt eine alternative Methode zum Serialisieren der Eingabetabelle in die Python-Sandbox an. Zum Serialisieren großer Tabellen legen sie fest, um true die Serialisierung zu beschleunigen und die Sandbox-Speicherauslastung erheblich zu verringern. Der Standardwert ist true.

Reservierte Python-Variablen

Die folgenden Variablen sind für die Interaktion zwischen Kusto-Abfragesprache und dem Python-Code reserviert.

• df: Die tabellarischen Eingabedaten (die Werte oben T ) als pandas DataFrame.
• kargs: Der Wert des arguments script_parameters als Python-Wörterbuch.
• result: Ein pandas vom Python-Skript erstelltes DataFrame, dessen Wert zu den tabellarischen Daten wird, die an den Kusto-Abfrageoperator gesendet werden, der auf das Plug-In folgt.

Aktivieren des Plug-Ins

Das Plug-In ist standardmäßig deaktiviert. Bevor Sie beginnen, aktivieren Sie das Python-Plug-In in Ihrer KQL-Datenbank.

Python-Sandkastenbild

Eine Liste der Pakete für die verschiedenen Python-Bilder finden Sie in der Python-Paketreferenz.

Hinweis

• Standardmäßig importiert das Plug-In numpy als np und pandas als pd. Optional können Sie andere Module nach Bedarf importieren.
• Einige Pakete sind möglicherweise nicht mit den Einschränkungen kompatibel, die von der Sandbox erzwungen werden, in der das Plug-In ausgeführt wird.

Verwenden der Erfassung von Abfrage- und Aktualisierungsrichtlinien

• Verwenden Sie das Plug-In in Abfragen, die folgendes sind:
  • Definiert als Teil einer Aktualisierungsrichtlinie, deren Quelltabelle bei Verwendung von Nicht-Streaming-Aufnahme aufgenommen wird.
  • Führen Sie als Teil eines Befehls aus, der aus einer Abfrage einnimmt, z .set-or-append. B. .
• Sie können das Plug-In nicht in einer Abfrage verwenden, die als Teil einer Updaterichtlinie definiert ist, deren Quelltabelle mithilfe der Streamingaufnahme aufgenommen wird.

Beispiele

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 

Leistungstipps

• Verringern Sie das Eingabe-Dataset des Plug-Ins auf die erforderliche Mindestmenge (Spalten/Zeilen).
  • Verwenden Sie Filter für das Quelldatenset, wenn möglich, mit der Abfragesprache von Kusto.
  • Wenn Sie eine Berechnung für eine Teilmenge der Quellspalten ausführen möchten, projizieren Sie nur diese Spalten, bevor Sie das Plug-In aufrufen.
• Verwenden Sie hint.distribution = per_node , wann immer die Logik in Ihrem Skript verteilt werden kann.
  • Sie können auch den Partitionsoperator für die Partitionierung des Eingabedatensets verwenden.
• Verwenden Sie kustos Abfragesprache, wenn möglich, um die Logik Ihres Python-Skripts zu implementieren.

Verwendungstipps

• Um mehrzeilige Zeichenfolgen zu generieren, die das Python-Skript in Ihrem Abfrage-Editor enthalten, kopieren Sie Ihr Python-Skript aus Ihrem bevorzugten Python-Editor (Jupyter, Visual Studio Code, PyCharm usw.), fügen Sie sie in Ihren Abfrage-Editor ein, und schließen Sie dann das vollständige Skript zwischen Zeilen ein, die drei aufeinander folgende Backticks enthalten. Zum Beispiel:

  ```
python code
```

• Verwenden Sie den externaldata Operator , um den Inhalt eines Skripts abzurufen, das Sie an einem externen Speicherort gespeichert haben, z. B. Azure Blob Storage.

Beispiel

    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 

Zugehöriger Inhalt

Weitere Beispiele für UDF-Funktionen, die das Python-Plug-In verwenden, finden Sie in der Funktionsbibliothek.