Python-plugin-program

  • Artikel

Python-plugin-programmet kör en användardefinierad funktion (UDF) med hjälp av ett Python-skript. Python-skriptet hämtar tabelldata som indata och genererar tabellutdata. Plugin-programmets körning finns i sandbox-miljöer och körs på klustrets noder.

Syntax

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

Läs mer om syntaxkonventioner.

Parametrar

Namn Typ Obligatorisk Beskrivning
output_schema string ✔️ En type literal som definierar utdataschemat för tabelldata som returneras av Python-koden. Formatet är: typeof(ColumnName:ColumnType[, ...]). Till exempel typeof(col1:string, col2:long). Om du vill utöka indataschemat använder du följande syntax: typeof(*, col1:string, col2:long).
Skript string ✔️ Det giltiga Python-skriptet som ska köras. Information om hur du genererar flerradssträngar finns i Användningstips.
script_parameters dynamic En egenskapsuppsättning med namnvärdepar som ska skickas till Python-skriptet som den reserverade kargs ordlistan. Mer information finns i Reserverade Python-variabler.
hint.distribution string Ett tips för att plugin-programmets körning ska distribueras över flera klusternoder. Standardvärdet är single. single innebär att en enda instans av skriptet körs över hela frågedata. per_node innebär att om frågan innan Python-blocket distribueras körs en instans av skriptet på varje nod, på de data som den innehåller.
hint.remote string Det här tipset är endast relevant för frågor mellan kluster. Standardvärdet är auto. auto innebär att servern automatiskt bestämmer i vilket kluster Python-koden ska köras. Ange värdet för att local framtvinga körning av Python-koden i det lokala klustret. Använd det om Python-plugin-programmet är inaktiverat i fjärrklustret.
external_artifacts dynamic En egenskapsuppsättning med namn- och URL-par för artefakter som är tillgängliga från molnlagring. Mer information finns i Använda externa artefakter.
spill_to_disk bool Anger en alternativ metod för serialisering av indatatabellen till Sandbox-miljön i Python. För serialisering av stora tabeller anger du det till true för att påskynda serialiseringen och avsevärt minska förbrukningen av sandbox-minne. Standardvärdet är true.

Reserverade Python-variabler

Följande variabler är reserverade för interaktion mellan Kusto-frågespråk och Python-koden.

  • df: Tabelldata för indata (värdena T ovan) som en pandas DataFrame.
  • kargs: Värdet för argumentet script_parameters som en Python-ordlista.
  • result: En pandas dataram som skapats av Python-skriptet, vars värde blir tabelldata som skickas till Kusto-frågeoperatorn som följer plugin-programmet.

Aktivera plugin-programmet

Plugin-programmet är inaktiverat som standard. Granska listan över förutsättningar innan du börjar. Om du vill aktivera plugin-programmet och välja version av Python-avbildningen läser du Aktivera språktillägg i klustret.

Python-sandbox-avbildning

Om du vill ändra versionen av Python-avbildningen läser du Ändra bilden för Python-språktillägg i klustret.

En lista över paket för de olika Python-avbildningarna finns i Python-paketreferens.

Anteckning

  • Som standard importerar plugin-programmet numpy som np och pandas som pd. Du kan också importera andra moduler efter behov.
  • Vissa paket kan vara inkompatibla med de begränsningar som tillämpas av sandbox-miljön där plugin-programmet körs.

Använda inmatning från fråge- och uppdateringsprincip

  • Använd plugin-programmet i frågor som är:
    • Definieras som en del av en uppdateringsprincip, vars källtabell matas in till att använda inmatning utan direktuppspelning .
    • Kör som en del av ett kommando som matar in från en fråga, till exempel .set-or-append.
  • Du kan inte använda plugin-programmet i en fråga som definieras som en del av en uppdateringsprincip, vars källtabell matas in med strömningsinmatning.

Exempel

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

Skärmbild av sinusdemo som visar frågeresultatet. 

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"})
)
Fil Storlek
this_is_a_script 120
this_is_my_first_file 105

Prestandatips

  • Minska indatauppsättningen för plugin-programmet till den minsta mängd som krävs (kolumner/rader).
    • Använd filter på källdatauppsättningen, när det är möjligt, med Kustos frågespråk.
    • Om du vill göra en beräkning på en delmängd av källkolumnerna projicerar du bara dessa kolumner innan du anropar plugin-programmet.
  • Använd hint.distribution = per_node när logiken i skriptet kan distribueras.
  • Använd Kustos frågespråk när det är möjligt för att implementera logiken i python-skriptet.

Användningstips

  • Om du vill generera flerradssträngar som innehåller Python-skriptet i frågeredigeraren kopierar du Python-skriptet från valfri Python-redigerare (Jupyter, Visual Studio Code, PyCharm och så vidare), klistrar in det i frågeredigeraren och omger sedan det fullständiga skriptet mellan rader som innehåller tre efterföljande backticks. Exempel:

    ```
    python code
    ```

  • Använd operatornexternaldata för att hämta innehållet i ett skript som du har lagrat på en extern plats, till exempel Azure Blob Storage.

Exempel

    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

Använda externa artefakter

Externa artefakter från molnlagring kan göras tillgängliga för skriptet och användas vid körning.

URL:erna som refereras av egenskapen externa artefakter måste vara:

Anteckning

När externa artefakter autentiseras SandboxArtifacts med hjälp av hanterade identiteter måste användningen definieras på klusternivåprincipen för hanterad identitet.

Artefakterna görs tillgängliga för skriptet att använda från en lokal tillfällig katalog, .\Temp. Namnen som anges i egenskapsuppsättningen används som lokala filnamn. Se Exempel.

Information om hur du refererar till externa paket finns i Installera paket för Python-plugin-programmet.

Uppdaterar extern artefaktcache

Externa artefaktfiler som används i frågor cachelagras i klustret. Om du gör uppdateringar av dina filer i molnlagringen och kräver omedelbar synkronisering med klustret kan du använda kommandot .clear cluster cache external-artifacts. Det här kommandot rensar de cachelagrade filerna och ser till att efterföljande frågor körs med den senaste versionen av artefakterna.

Installera paket för Python-plugin-programmet

Du kan behöva installera paket själv av följande skäl:

  • Paketet är privat och är ditt eget.
  • Paketet är offentligt men ingår inte i plugin-programmets basavbildning.

Installera paket på följande sätt:

Förutsättningar

  1. Skapa en blobcontainer som värd för paketen, helst på samma plats som klustret. Anta till exempel att klustret finns i USA, https://artifactswestus.blob.core.windows.net/pythonvästra.

  2. Ändra klustrets pratbubblans princip för att tillåta åtkomst till den platsen.

    • Den här ändringen kräver Behörigheter för AllDatabasesAdmin .

    • Om du till exempel vill aktivera åtkomst till en blob som finns i https://artifactswestus.blob.core.windows.net/pythonkör du följande kommando:

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

Installera paket

  1. För offentliga paket i PyPi eller andra kanaler laddar du ned paketet och dess beroenden.

    • Från ett cmd-fönster i din lokala Windows Python-miljö kör du:
    pip wheel [-w download-dir] package-name.

  2. Skapa en zip-fil som innehåller det nödvändiga paketet och dess beroenden.

    • För privata paket zippar du mappen för paketet och mapparna för dess beroenden.
    • Zippa de filer som laddades ned i föregående steg för offentliga paket.

    Anteckning

    • Se till att ladda ned paketet som är kompatibelt med Python-motorn och plattformen för sandbox-körningen (för närvarande 3.6.5 i Windows)
    • Se till att zippa filerna .whl själva och inte deras överordnade mapp.
    • Du kan hoppa över .whl filer för paket som redan finns med samma version i den grundläggande sandbox-avbildningen.

  3. Ladda upp den komprimerade filen till en blob på artefaktplatsen (från steg 1).

  4. Anropa plugin-programmet python .

    • Ange parametern external_artifacts med en egenskapsuppsättning med namn och referens till zip-filen (blobens URL, inklusive en SAS-token).
    • I den infogade Python-koden importerar Zipackage du från sandbox_utils och anropar dess install() -metod med namnet på zip-filen.

Exempel

Installera Faker-paketet som genererar falska 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://artifacts.blob.core.windows.net/kusto/Faker.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))
ID Name
1 Gary Tapia
2 Emma Evans
3 Ashley Bowen

Relaterat innehåll

Fler exempel på UDF-funktioner som använder Python-plugin-programmet finns i Functions-biblioteket.

Python-plugin-programmet kör en användardefinierad funktion (UDF) med hjälp av ett Python-skript. Python-skriptet hämtar tabelldata som indata och genererar tabellutdata.

Syntax

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

Läs mer om syntaxkonventioner.

Parametrar

Namn Typ Obligatorisk Beskrivning
output_schema string ✔️ En type literal som definierar utdataschemat för tabelldata som returneras av Python-koden. Formatet är: typeof(ColumnName:ColumnType[, ...]). Till exempel typeof(col1:string, col2:long). Om du vill utöka indataschemat använder du följande syntax: typeof(*, col1:string, col2:long).
Skript string ✔️ Det giltiga Python-skriptet som ska köras. Information om hur du genererar flerradssträngar finns i Användningstips.
script_parameters dynamic En egenskapsuppsättning med namnvärdepar som ska skickas till Python-skriptet som den reserverade kargs ordlistan. Mer information finns i Reserverade Python-variabler.
hint.distribution string Ett tips för att plugin-programmets körning ska distribueras över flera klusternoder. Standardvärdet är single. single innebär att en enda instans av skriptet körs över hela frågedata. per_node innebär att om frågan innan Python-blocket distribueras körs en instans av skriptet på varje nod, på de data som den innehåller.
hint.remote string Det här tipset är endast relevant för frågor mellan kluster. Standardvärdet är auto. auto innebär att servern automatiskt bestämmer i vilket kluster Python-koden ska köras. Ange värdet för att local framtvinga körning av Python-koden i det lokala klustret. Använd det om Python-plugin-programmet är inaktiverat i fjärrklustret.
spill_to_disk bool Anger en alternativ metod för serialisering av indatatabellen till Sandbox-miljön i Python. För serialisering av stora tabeller anger du det till true för att påskynda serialiseringen och avsevärt minska förbrukningen av sandbox-minne. Standardvärdet är true.

Reserverade Python-variabler

Följande variabler är reserverade för interaktion mellan Kusto-frågespråk och Python-koden.

  • df: Tabelldata för indata (värdena T ovan) som en pandas DataFrame.
  • kargs: Värdet för argumentet script_parameters som en Python-ordlista.
  • result: En pandas dataram som skapats av Python-skriptet, vars värde blir tabelldata som skickas till Kusto-frågeoperatorn som följer plugin-programmet.

Aktivera plugin-programmet

Plugin-programmet är inaktiverat som standard. Innan du börjar aktiverar du Python-plugin-programmet i din KQL-databas.

Python-sandbox-avbildning

En lista över paket för de olika Python-avbildningarna finns i Python-paketreferens.

Anteckning

  • Som standard importerar plugin-programmet numpy som np och pandas som pd. Du kan också importera andra moduler efter behov.
  • Vissa paket kan vara inkompatibla med de begränsningar som tillämpas av sandbox-miljön där plugin-programmet körs.

Använda inmatning från fråge- och uppdateringsprincip

  • Använd plugin-programmet i frågor som är:
    • Definieras som en del av en uppdateringsprincip, vars källtabell matas in till att använda inmatning utan direktuppspelning .
    • Kör som en del av ett kommando som matar in från en fråga, till exempel .set-or-append.
  • Du kan inte använda plugin-programmet i en fråga som definieras som en del av en uppdateringsprincip, vars källtabell matas in med strömningsinmatning.

Exempel

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

Skärmbild av sinusdemo som visar frågeresultatet.

Prestandatips

  • Minska indatauppsättningen för plugin-programmet till den minsta mängd som krävs (kolumner/rader).
    • Använd filter på källdatauppsättningen, när det är möjligt, med Kustos frågespråk.
    • Om du vill göra en beräkning på en delmängd av källkolumnerna projicerar du bara dessa kolumner innan du anropar plugin-programmet.
  • Använd hint.distribution = per_node när logiken i skriptet kan distribueras.
  • Använd Kustos frågespråk när det är möjligt för att implementera logiken i python-skriptet.

Användningstips

  • Om du vill generera flerradssträngar som innehåller Python-skriptet i frågeredigeraren kopierar du Python-skriptet från valfri Python-redigerare (Jupyter, Visual Studio Code, PyCharm och så vidare), klistrar in det i frågeredigeraren och omger sedan det fullständiga skriptet mellan rader som innehåller tre efterföljande backticks. Exempel:

    ```
    python code
    ```

  • Använd operatornexternaldata för att hämta innehållet i ett skript som du har lagrat på en extern plats, till exempel Azure Blob Storage.

Exempel

    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

Relaterat innehåll

Fler exempel på UDF-funktioner som använder Python-plugin-programmet finns i Functions-biblioteket.

Den här funktionen stöds inte.