Python-plugin

Van toepassing op: ✅Microsoft Fabric✅Azure Data Explorer-

De Python-invoegtoepassing voert een door de gebruiker gedefinieerde functie (UDF) uit met behulp van een Python-script. Het Python-script haalt tabellaire gegevens op als invoer en produceert tabellaire uitvoer.

Syntaxis

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

Meer informatie over syntaxisconventies.

Parameterwaarden

Naam	Typologie	Verplicht	Beschrijving
output_schema	string	✔️	Een type letterlijke waarde die het uitvoerschema van de tabelgegevens definieert, geretourneerd door de Python-code. De indeling is: typeof(ColumnName:ColumnType[, ...]). Bijvoorbeeld typeof(col1:string, col2:long). Gebruik de volgende syntaxis om het invoerschema uit te breiden: typeof(*, col1:string, col2:long)
script	string	✔️	Het geldige Python-script dat moet worden uitgevoerd. Zie gebruikstips voor het genereren van tekenreeksen met meerdere regels.
script_parameters	dynamic		Een eigenschappenverzameling met naam-waardeparen die als gereserveerde kargs woordenlijst moeten worden doorgegeven aan het Python-script. Zie Gereserveerde Python-variabelen voor meer informatie.
hint.distribution	string		Een hint voor de uitvoering van de invoegtoepassing die moet worden gedistribueerd over meerdere sandboxes. De standaardwaarde is single. single betekent dat één exemplaar van het script wordt uitgevoerd voor de volledige querygegevens in één sandbox. per_node betekent dat als de query voordat het Python-blok wordt gedistribueerd naar partities, elke partitie parallel in een eigen sandbox wordt uitgevoerd.
hint.remote	string		Deze hint is alleen relevant voor query's voor meerdere clusters. De standaardwaarde is auto. auto betekent dat de server automatisch bepaalt in welk cluster de Python-code wordt uitgevoerd. Als u de waarde instelt om de Python-code op het lokale cluster uit te local voeren. Gebruik deze als de Python-invoegtoepassing is uitgeschakeld op het externe cluster.
external_artifacts	dynamic		Een eigenschappenverzameling met naam- en URL-paren voor artefacten die toegankelijk zijn vanuit OneLake-opslag. Zie meer in Externe artefacten gebruiken.
spill_to_disk	bool		Hiermee geeft u een alternatieve methode op voor het serialiseren van de invoertabel naar de Python-sandbox. Voor het serialiseren van grote tabellen stelt u deze in om de serialisatie te true versnellen en het geheugenverbruik van de sandbox aanzienlijk te verminderen. De standaardinstelling is true.

Gereserveerde Python-variabelen

De volgende variabelen zijn gereserveerd voor interactie tussen Kusto Query Language en de Python-code.

• df: De gegevens in tabelvorm (de bovenstaande waarden T ) als een pandas DataFrame.
• kargs: De waarde van het argument script_parameters , als een Python-woordenlijst.
• result: Een pandas DataFrame dat is gemaakt door het Python-script, waarvan de waarde de tabelgegevens wordt die worden verzonden naar de Kusto-queryoperator die volgt op de invoegtoepassing.

De invoegtoepassing inschakelen

De invoegtoepassing is standaard uitgeschakeld. Voordat u begint, schakelt u de Python-invoegtoepassing in uw KQL-database in.

Python-sandboxinstallatiekopieën

Als u de lijst met pakketten voor de verschillende Python-installatiekopieën wilt bekijken, raadpleegt u de python-pakketreferentie.

Opmerking

• Standaard importeert de invoegtoepassing numpy als np en pandas als pd. U kunt desgewenst andere modules importeren.
• Sommige pakketten zijn mogelijk niet compatibel met de beperkingen die worden afgedwongen door de sandbox waarop de invoegtoepassing wordt uitgevoerd.

Opname gebruiken vanuit query- en updatebeleid

• Gebruik de invoegtoepassing in query's die:
  • Gedefinieerd als onderdeel van een updatebeleid, waarvan de brontabel wordt opgenomen door opname in de wachtrij.
  • Uitvoeren als onderdeel van een opdracht die wordt opgenomen uit een query, zoals .set-or-append.
• U kunt de invoegtoepassing niet gebruiken in een query die is gedefinieerd als onderdeel van een updatebeleid, waarvan de brontabel wordt opgenomen met behulp van streamingopname.

Voorbeeld

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 

Prestatietips

• Verminder de invoergegevensset van de invoegtoepassing tot de minimale hoeveelheid die is vereist (kolommen/rijen).
  • Gebruik, indien mogelijk, filters voor de brongegevensset met de querytaal van Kusto.
  • Als u een berekening wilt uitvoeren op een subset van de bronkolommen, projecteren ze alleen die kolommen voordat u de invoegtoepassing aanroept.
• Gebruik hint.distribution = per_node deze functie wanneer de logica in uw script kan worden gedistribueerd.
  • U kunt ook de partitieoperator gebruiken voor het partitioneren van de invoergegevensset.
• Gebruik waar mogelijk de querytaal van Kusto om de logica van uw Python-script te implementeren.

Tips voor gebruik

• Als u tekenreeksen met meerdere regels wilt genereren die het Python-script in uw queryeditor bevatten, kopieert u uw Python-script vanuit uw favoriete Python-editor (Jupyter, Visual Studio Code, PyCharm enzovoort), plakt u het in de query-editor en plaatst u het volledige script tussen regels met drie opeenvolgende backticks. Voorbeeld:

  ```
python code
```

• Gebruik de operator externaldata om de inhoud te verkrijgen van een script dat u hebt opgeslagen op een externe locatie, zoals Azure Blob Storage.

Voorbeeld van het lezen van het Python-script externe gegevens

    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 

Externe artefacten gebruiken

Externe artefacten van OneLake-opslag kunnen beschikbaar worden gesteld voor het script en tijdens runtime worden gebruikt.

De artefacten worden beschikbaar gesteld zodat het script kan worden gelezen uit een lokale tijdelijke map, .\Temp. De namen die in de eigenschappentas worden opgegeven, worden gebruikt als de lokale bestandsnamen. Zie Voorbeeld.

Zie Pakketten installeren voor de Python-invoegtoepassing voor informatie over het verwijzen naar externe pakketten.

Cache voor externe artefacten vernieuwen

Externe artefactbestanden die worden gebruikt in query's, worden in de cache opgeslagen in uw cluster. Als u updates voor uw bestanden in cloudopslag aanbrengt en onmiddellijke synchronisatie met uw cluster vereist, kunt u de opdracht .clear clustercache external-artifacts gebruiken. Met deze opdracht worden de bestanden in de cache gewist en wordt ervoor gezorgd dat volgende query's worden uitgevoerd met de nieuwste versie van de artefacten.

Pakketten installeren voor de Python-invoegtoepassing

Installeer pakketten als volgt:

Voorwaarde

• Maak een lakehouse om de pakketten te hosten, bij voorkeur in dezelfde werkruimte als uw eventhouse.

Pakketten installeren

1. Voor openbare pakketten in PyPi of andere kanalen downloadt u het pakket en de bijbehorende afhankelijkheden.

   • Voer vanuit een cmd-venster in uw lokale Windows Python-omgeving het volgende uit:

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

2. Maak een ZIP-bestand met het vereiste pakket en de bijbehorende afhankelijkheden.

   • Voor privépakketten zipt u de map van het pakket en de mappen van de bijbehorende afhankelijkheden.
   • Voor openbare pakketten zipt u de bestanden die in de vorige stap zijn gedownload.

   Opmerking

   • Download het pakket dat compatibel is met de Python-engine en het platform van de sandbox-runtime (momenteel 3.10.8 of 3.11.7 op Windows)
   • Zorg ervoor dat u de .whl bestanden zelf zipt en niet de bovenliggende map.
   • U kunt bestanden overslaan .whl voor pakketten die al bestaan met dezelfde versie in de basis-sandbox-installatiekopieën.

3. Upload het zip-bestand naar het lakehouse.

4. Kopieer de OneLake-URL (uit de eigenschappen van het gezipte bestand)

5. Roep de python invoegtoepassing aan.

   • Geef de external_artifacts parameter op met een eigenschapsverzameling met lokale naam en OneLake-URL van het zip-bestand.
   • Importeer Zipackage in uw inline Python-code de sandbox_utils methode en roep install() deze aan met de naam van het ZIP-bestand.

Voorbeeld van het gebruik van externe artefacten

Installeer het Faker-pakket dat valse gegevens genereert.

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

ID-kaart	Naam
1	Gary Tapia
2	Emma Evans
3	Ashley Bowen

Verwante inhoud

Zie de Functions-bibliotheek voor meer voorbeelden van UDF-functies die gebruikmaken van de Python-invoegtoepassing.