Modul plug-in Pythonu

Platí pro: ✅Microsoft Fabric✅Azure Data Explorer

Modul plug-in Pythonu spouští uživatelem definovanou funkci (UDF) pomocí skriptu Pythonu. Skript Pythonu získá jako vstup tabulková data a vytvoří tabulkový výstup.

Syntaxe

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

Přečtěte si další informace o konvencích syntaxe.

Parametry

Název	Typ	Požadováno	Popis
output_schema	string	✔️	Literál type , který definuje výstupní schéma tabulkových dat vrácených kódem Pythonu. Formát je: typeof(ColumnName:ColumnType[, ...]). Například typeof(col1:string, col2:long). Chcete-li rozšířit vstupní schéma, použijte následující syntaxi: typeof(*, col1:string, col2:long).
skript	string	✔️	Platný skript Pythonu, který se má spustit. Pokud chcete generovat víceřádkové řetězce, přečtěte si tipy k používání.
script_parameters	dynamic		Sada vlastností párů hodnot názvů, které se mají předat skriptu Pythonu jako vyhrazený kargs slovník. Další informace najdete v tématu Rezervované proměnné Pythonu.
hint.distribution	string		Tip pro spuštění modulu plug-in, který se má distribuovat napříč několika sandboxy. Výchozí hodnota je single. single znamená, že jedna instance skriptu se spustí přes celá data dotazu v jednom sandboxu. per_node znamená, že pokud je dotaz před blokem Pythonu distribuován do oddílů, každý oddíl se spustí paralelně ve vlastním sandboxu.
hint.remote	string		Tento tip je relevantní pouze pro dotazy napříč clustery. Výchozí hodnota je auto. auto znamená, že se server rozhodne automaticky v clusteru, ve kterém se kód Pythonu spustí. Nastavení hodnoty pro local vynutí spuštění kódu Pythonu v místním clusteru. Použijte ho v případě, že je modul plug-in Pythonu ve vzdáleném clusteru zakázaný.
external_artifacts	dynamic		Sada vlastností párů názvů a adres URL pro artefakty, které jsou přístupné z úložiště OneLake. Další informace najdete v tématu Použití externích artefaktů.
spill_to_disk	bool		Určuje alternativní metodu serializace vstupní tabulky do sandboxu Pythonu. Pro serializaci velkých tabulek je nastavena na true zrychlení serializace a výrazně snížit spotřebu paměti sandboxu. Výchozí hodnota je true.

Rezervované proměnné Pythonu

Následující proměnné jsou vyhrazené pro interakci mezi dotazovací jazyk Kusto a kódem Pythonu.

• df: Vstupní tabulková data (hodnoty T výše) jako pandas datový rámec.
• kargs: Hodnota argumentu script_parameters jako slovník Pythonu.
• result pandas: Datový rámec vytvořený skriptem Pythonu, jehož hodnota se stane tabulkovými daty, která se odešlou do operátoru dotazu Kusto, který následuje za modulem plug-in.

Povolení modulu plug-in

Modul plug-in je ve výchozím nastavení zakázaný. Než začnete, povolte modul plug-in Pythonu v databázi KQL.

Obrázek sandboxu Pythonu

Seznam balíčků pro různé image Pythonu najdete v referenčních informacích k balíčkům Pythonu.

Poznámka:

• Ve výchozím nastavení modul plug-in importuje numpy jako np a pandas jako pd. Volitelně můžete podle potřeby importovat další moduly.
• Některé balíčky můžou být nekompatibilní s omezeními vynucenými sandboxem, ve kterém je modul plug-in spuštěný.

Použití příjmu dat z dotazů a zásad aktualizací

• Modul plug-in použijte v dotazech, které jsou:
  • Definuje se jako součást zásady aktualizace, jejíž zdrojová tabulka se ingestuje ve frontě.
  • Spusťte jako součást příkazu, který ingestuje z dotazu, například .set-or-append.
• Modul plug-in nemůžete použít v dotazu definovaném jako součást zásad aktualizace, jejichž zdrojová tabulka se ingestuje pomocí příjmu streamu.

Příklad

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 

Tipy týkající se výkonu

• Snižte vstupní datovou sadu modulu plug-in na minimální požadované množství (sloupce nebo řádky).
  • Pokud je to možné, použijte filtry u zdrojové datové sady s dotazovacím jazykem Kusto.
  • Pokud chcete provést výpočet pro podmnožinu zdrojových sloupců, projektujte před vyvoláním modulu plug-in pouze tyto sloupce.
• Použijte hint.distribution = per_node pokaždé, když je logika ve vašem skriptu distribuovatelná.
  • K dělení vstupní datové sady můžete použít také operátor oddílu.
• Pokud je to možné, použijte dotazovací jazyk Kusto k implementaci logiky skriptu Pythonu.

Tipy k používání

• Pokud chcete vygenerovat víceřádkové řetězce obsahující skript Pythonu v editoru dotazů, zkopírujte skript Pythonu z oblíbeného editoru Pythonu (Jupyter, Visual Studio Code, PyCharm atd.), vložte ho do editoru dotazů a pak celý skript uzavřete mezi řádky obsahující tři po sobě jdoucí backticky. Příklad:

  ```
python code
```

• Pomocí operátoru externaldata získáte obsah skriptu, který jste uložili do externího umístění, jako je azure Blob Storage.

Příklad čtení externích dat skriptu Pythonu

    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 

Použití externích artefaktů

Externí artefakty z úložiště OneLake je možné zpřístupnit pro skript a použít je za běhu.

Artefakty jsou zpřístupněny pro skript, který se má číst z místního dočasného adresáře, .\Temp. Názvy zadané v kontejneru vlastností se používají jako názvy místních souborů. Viz příklad.

Informace o odkazování na externí balíčky naleznete v tématu Instalace balíčků pro modul plug-in Python.

Aktualizace mezipaměti externích artefaktů

Soubory externích artefaktů využívané v dotazech se ukládají do mezipaměti ve vašem clusteru. Pokud aktualizujete soubory v cloudovém úložišti a vyžadujete okamžitou synchronizaci s clusterem, můžete použít příkaz .clear cluster cache external-artifacts. Tento příkaz vymaže soubory uložené v mezipaměti a zajistí, že následné dotazy poběží s nejnovější verzí artefaktů.

Instalace balíčků pro modul plug-in Pythonu

Balíčky nainstalujte následujícím způsobem:

Předpoklad

• Vytvořte lakehouse pro hostování balíčků, nejlépe ve stejném pracovním prostoru jako váš eventhouse.

Instalace balíčků

1. U veřejných balíčků v PyPi nebo jiných kanálech stáhněte balíček a jeho závislosti.

   • V okně příkazového panelu v místním prostředí Windows Pythonu spusťte:

   pip wheel [-w download-dir] package-name.
   

2. Vytvořte soubor ZIP obsahující požadovaný balíček a jeho závislosti.

   • U privátních balíčků zazipujte složku balíčku a složky jejích závislostí.
   • U veřejných balíčků zazipujte soubory, které byly staženy v předchozím kroku.

   Poznámka:

   • Nezapomeňte stáhnout balíček, který je kompatibilní s modulem Python a platformou modulu runtime sandboxu (aktuálně 3.10.8 nebo 3.11.7 ve Windows).
   • Nezapomeňte soubory zazipovat .whl sami, a ne jejich nadřazenou složku.
   • Soubory pro balíčky, které už existují se stejnou verzí v základní imagi sandboxu, můžete přeskočit .whl .

3. Nahrajte soubor ZIP do jezera.

4. Zkopírujte adresu URL OneLake (z vlastností zkomprimovaného souboru).

5. Zavolejte modul plug-in python .

   • external_artifacts Zadejte parametr s taškou vlastností místního názvu a adresu URL OneLake souboru ZIP.
   • Ve vloženém kódu Pythonu naimportujte Zipackagesandbox_utils a volejte jeho install() metodu s názvem souboru ZIP.

Příklad použití externích artefaktů

Nainstalujte balíček Faker, který generuje falešná data.

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

Průkaz totožnosti	Název
0	Gary Tapia
2	Emma Evans
3	Ashley Bowen

Související obsah

Další příklady funkcí definované uživatelem, které používají modul plug-in Pythonu, najdete v knihovně Functions.