Python-invoegtoepassing

  • Artikel

Met de Python-invoegtoepassing wordt een door de gebruiker gedefinieerde functie (UDF) uitgevoerd met behulp van een Python-script. Het Python-script haalt gegevens in tabelvorm op als invoer en produceert uitvoer in tabelvorm. De runtime van de invoegtoepassing wordt gehost in sandboxes en wordt uitgevoerd op de knooppunten van het cluster.

Syntax

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.

Parameters

Naam Type Vereist Beschrijving
output_schema string ✔️ Een type letterlijke waarde die het uitvoerschema van de gegevens in tabelvorm 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 Tips voor gebruik als u tekenreeksen met meerdere regels wilt genereren.
script_parameters dynamic Een eigenschappenverzameling met naamwaardeparen die als gereserveerde woordenlijst moeten worden doorgegeven aan het Python-script kargs . Zie Gereserveerde Python-variabelen voor meer informatie.
hint.distribution string Een hint voor de uitvoering van de invoegtoepassing die moet worden gedistribueerd over meerdere clusterknooppunten. De standaardwaarde is single. single betekent dat één exemplaar van het script wordt uitgevoerd voor de volledige querygegevens. per_node betekent dat als de query vóór het Python-blok wordt gedistribueerd, een exemplaar van het script wordt uitgevoerd op elk knooppunt, op de gegevens die het bevat.
hint.remote string Deze hint is alleen relevant voor clusteroverschrijdende query's. De standaardwaarde is auto. auto betekent dat de server automatisch bepaalt in welk cluster de Python-code wordt uitgevoerd. Als u de waarde instelt op, local wordt de Python-code uitgevoerd op het lokale cluster. Gebruik dit voor het geval 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 cloudopslag. Zie Externe artefacten gebruiken voor meer informatie.
spill_to_disk bool Hiermee geeft u een alternatieve methode voor het serialiseren van de invoertabel naar de Python-sandbox. Voor het serialiseren van grote tabellen stelt u deze in op true om de serialisatie te 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-querytaal en de Python-code.

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

De invoegtoepassing inschakelen

De invoegtoepassing is standaard uitgeschakeld. Bekijk voordat u begint de lijst met vereisten. Zie Taalextensies inschakelen in uw cluster om de invoegtoepassing in te schakelen en de versie van de Python-installatiekopieën te selecteren.

Installatiekopieën van Python-sandbox

Als u de versie van de Python-installatiekopieën wilt wijzigen, raadpleegt u De python-taaluitbreidingsinstallatiekopieën in uw cluster wijzigen.

Zie Naslaginformatie over Python-pakketten voor een overzicht van de lijst met pakketten voor de verschillende Python-installatiekopieën.

Notitie

  • 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 uit query- en updatebeleid gebruiken

  • Gebruik de invoegtoepassing in query's die zijn:
    • Gedefinieerd als onderdeel van een updatebeleid, waarvan de brontabel wordt opgenomen in het gebruik van niet-streamingopname .
    • Voer uit als onderdeel van een opdracht die uit een query wordt opgenomen, 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.

Voorbeelden

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

Schermopname van sinusdemo met het queryresultaat. 

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 Grootte
this_is_a_script 120
this_is_my_first_file 105

Tips voor prestaties

  • Verminder de invoergegevensset van de invoegtoepassing tot de minimaal vereiste hoeveelheid (kolommen/rijen).
    • Gebruik waar mogelijk filters voor de brongegevensset met de querytaal van Kusto.
    • Als u een berekening wilt uitvoeren op een subset van de bronkolommen, moet u alleen die kolommen projecteren voordat u de invoegtoepassing aanroept.
  • Gebruik hint.distribution = per_node 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 met het Python-script in uw query-editor, kopieert u het Python-script uit uw favoriete Python-editor (Jupyter, Visual Studio Code, PyCharm, enzovoort), plakt u het in uw query-editor en plaatst u het volledige script tussen regels met drie opeenvolgende backticks. Bijvoorbeeld:

    ```
    python code
    ```

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

Voorbeeld

    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 uit cloudopslag kunnen beschikbaar worden gemaakt voor het script en tijdens runtime worden gebruikt.

De URL's waarnaar wordt verwezen door de eigenschap externe artefacten moeten zijn:

Notitie

Bij het verifiëren van externe artefacten met behulp van beheerde identiteiten, moet het SandboxArtifacts gebruik worden gedefinieerd op het beleid voor beheerde identiteit op clusterniveau.

De artefacten worden beschikbaar gesteld voor het script om te gebruiken vanuit een lokale tijdelijke map, .\Temp. De namen in de eigenschappenverzameling worden gebruikt als de lokale bestandsnamen. Zie Voorbeelden.

Zie Install packages for the Python plugin (Pakketten installeren voor de Python-invoegtoepassing) voor informatie over het verwijzen naar externe pakketten.

Externe artefactcache vernieuwen

Externe artefactbestanden die worden gebruikt in query's, worden in de cache opgeslagen in uw cluster. Als u uw bestanden in cloudopslag bijwerkt 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 voor de Python-invoegtoepassing installeren

Mogelijk moet u pakketten zelf installeren, om de volgende redenen:

  • Het pakket is privé en is uw eigen pakket.
  • Het pakket is openbaar, maar is niet opgenomen in de basisinstallatiekopieën van de invoegtoepassing.

Installeer pakketten als volgt:

Vereisten

  1. Maak een blobcontainer om de pakketten te hosten, bij voorkeur op dezelfde plaats als uw cluster. Bijvoorbeeld , https://artifactswestus.blob.core.windows.net/pythonervan uitgaande dat uw cluster zich in VS - west bevindt.

  2. Wijzig het bijschriftbeleid van het cluster om toegang tot die locatie toe te staan.

    • Voor deze wijziging zijn AllDatabasesAdmin-machtigingen vereist.

    • Voer bijvoorbeeld de volgende opdracht uit om toegang tot een blob in https://artifactswestus.blob.core.windows.net/pythonte schakelen:

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

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 dat het vereiste pakket en de bijbehorende afhankelijkheden bevat.

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

    Notitie

    • Zorg ervoor dat u het pakket downloadt dat compatibel is met de Python-engine en het platform van de sandbox-runtime (momenteel 3.6.5 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-sandboxinstallatiekopieën.

  3. Upload het zip-bestand naar een blob op de locatie van de artefacten (uit stap 1).

  4. Roep de python invoegtoepassing aan.

    • Geef de external_artifacts parameter op met een eigenschappenverzameling met de naam en verwijzing naar het zip-bestand (de URL van de blob, inclusief een SAS-token).
    • Importeer Zipackage in uw inline Python-code uit sandbox_utils en roep de methode aan install() met de naam van het zip-bestand.

Voorbeeld

Installeer het Faker-pakket waarmee valse gegevens worden gegenereerd.

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 Name
1 Gary Tapia
2 Emma Evans
3 Ashley Bowen

Gerelateerde inhoud

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

Met de Python-invoegtoepassing wordt een door de gebruiker gedefinieerde functie (UDF) uitgevoerd met behulp van een Python-script. Het Python-script haalt gegevens in tabelvorm op als invoer en produceert uitvoer in tabelvorm.

Syntax

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

Meer informatie over syntaxisconventies.

Parameters

Naam Type Vereist Beschrijving
output_schema string ✔️ Een type letterlijke waarde die het uitvoerschema van de gegevens in tabelvorm 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 Tips voor gebruik als u tekenreeksen met meerdere regels wilt genereren.
script_parameters dynamic Een eigenschappenverzameling met naamwaardeparen die als gereserveerde woordenlijst moeten worden doorgegeven aan het Python-script kargs . Zie Gereserveerde Python-variabelen voor meer informatie.
hint.distribution string Een hint voor de uitvoering van de invoegtoepassing die moet worden gedistribueerd over meerdere clusterknooppunten. De standaardwaarde is single. single betekent dat één exemplaar van het script wordt uitgevoerd voor de volledige querygegevens. per_node betekent dat als de query voordat het Python-blok wordt gedistribueerd, een exemplaar van het script wordt uitgevoerd op elk knooppunt, op de gegevens die het bevat.
hint.remote string Deze hint is alleen relevant voor clusteroverschrijdende query's. De standaardwaarde is auto. auto betekent dat de server automatisch bepaalt in welk cluster de Python-code wordt uitgevoerd. Als u de waarde instelt op local , wordt het uitvoeren van de Python-code op het lokale cluster afgeslagen. Gebruik deze voor het geval de Python-invoegtoepassing is uitgeschakeld op het externe cluster.
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 op true om de serialisatie te 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-querytaal en de Python-code.

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

De invoegtoepassing inschakelen

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

Installatiekopieën van Python-sandbox

Zie Naslaginformatie over Python-pakketten voor een overzicht van de lijst met pakketten voor de verschillende Python-installatiekopieën.

Notitie

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

Opname uit query- en updatebeleid gebruiken

  • Gebruik de invoegtoepassing in query's die:
    • Gedefinieerd als onderdeel van een updatebeleid waarvan de brontabel wordt opgenomen voor gebruik van niet-streamingopname .
    • Voer uit 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.

Voorbeelden

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

Schermopname van sinusdemo met het queryresultaat.

Tips voor prestaties

  • Verminder de invoergegevensset van de invoegtoepassing tot de minimaal vereiste hoeveelheid (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, moet u alleen die kolommen projecteren voordat u de invoegtoepassing aanroept.
  • Gebruik hint.distribution = per_node 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 het Python-script uit uw favoriete Python-editor (Jupyter, Visual Studio Code, PyCharm, enzovoort), plakt u het in uw query-editor en plaatst u het volledige script tussen regels met drie opeenvolgende backticks. Bijvoorbeeld:

    ```
    python code
    ```

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

Voorbeeld

    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

Gerelateerde inhoud

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

Deze mogelijkheid wordt niet ondersteund.