Plugin-program för Python

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.

Parameterar

Reserverade Python-variabler

Följande variabler är reserverade för interaktion mellan Kusto Query Language och Python-koden.

• df: Indata i tabellform (värdena T ovan) som en pandas DataFrame.
• kargs: Värdet för argumentet script_parameters som en Python-ordlista.
• result: En pandas DataFrame 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 bör du granska listan med krav. Om du vill aktivera plugin-programmet och välja versionen av Python-avbildningen läser du Aktivera språktillägg i klustret.

Python-sandbox-avbildning

Information om hur du ändrar versionen av Python-avbildningen till en annan hanterad avbildning eller en anpassad avbildning finns i Ändra python-språktilläggsavbildningen i klustret.

Information om hur du ser listan över paket för de olika Python-avbildningarna finns i Python-paketreferensen.

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 av köad inmatning.
  • 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ömmande inmatning.

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 

Prestandatips

• Minska plugin-programmets indatauppsättning 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.
  • Du kan också använda partitionsoperatorn för partitionering av indatauppsättningen.
• 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 pythonredigeraren (Jupyter, Visual Studio Code, PyCharm och så vidare), klistrar in det i frågeredigeraren och omsluter sedan det fullständiga skriptet mellan rader som innehåller tre på varandra följande backticks. Till exempel:

  ```
python code
```

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

Exempel på läsning av externa data för Python-skript

    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:er som refereras till av egenskapen externa artefakter måste vara:

• Ingår i klustrets pratbubblans princip.
• På en offentligt tillgänglig plats, eller ange nödvändiga autentiseringsuppgifter, enligt beskrivningen i lagringsanslutningssträngar.

Artefakterna görs tillgängliga för att skriptet ska kunna läsas från en lokal tillfällig katalog, .\Temp. Namnen som anges i egenskapsväskan används som lokala filnamn. Se Exempel.

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

Uppdatera 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

I de flesta fall kanske du föredrar att skapa en anpassad avbildning.

Du kanske vill installera paket själv av följande skäl:

• Du har inte behörighet att skapa en anpassad avbildning.
• Paketet är privat.
• Du föredrar att skapa en ad hoc-paketinstallation för testning och vill inte ha mer omkostnader för att skapa en anpassad avbildning.

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.

   • Kör från ett cmd-fönster i din lokala Windows Python-miljö:

   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.
   • För offentliga paket zippar du de filer som laddades ned i föregående steg.

   Anmärkning

   • Se till att ladda ned paketet som är kompatibelt med Python-motorn och plattformen för sandbox-körningen (för närvarande 3.10.8 eller 3.11.7 i Windows)
   • Se till att zippa .whl själva filerna 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 zip-filen till en blob på artefaktplatsen (från steg 1 av förhandskraven).

4. Anropa plugin-programmet python .

   • Ange parametern external_artifacts med en egenskapsuppsättning med lokalt namn och blob-URL för zip-filen (inklusive en SAS-token).
   • I din infogade Python-kod importerar Zipackage du från sandbox_utils och anropar dess install() metod med det lokala namnet på ZIP-filen.

Exempel med externa artefakter

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/Faker.zip;impersonate'))

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] [,external_artifacts] [,spill_to_disk])

Läs mer om syntaxkonventioner.

Parameterar

Reserverade Python-variabler

Följande variabler är reserverade för interaktion mellan Kusto Query Language och Python-koden.

• df: Indata i tabellform (värdena T ovan) som en pandas DataFrame.
• kargs: Värdet för argumentet script_parameters som en Python-ordlista.
• result: En pandas DataFrame 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

Information om hur du ser listan över paket för de olika Python-avbildningarna finns i Python-paketreferensen.

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 av köad inmatning.
  • 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ömmande inmatning.

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 

Prestandatips

• Minska plugin-programmets indatauppsättning 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.
  • Du kan också använda partitionsoperatorn för partitionering av indatauppsättningen.
• 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 pythonredigeraren (Jupyter, Visual Studio Code, PyCharm och så vidare), klistrar in det i frågeredigeraren och omsluter sedan det fullständiga skriptet mellan rader som innehåller tre på varandra följande backticks. Till exempel:

  ```
python code
```

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

Exempel på läsning av externa data för Python-skript

    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 OneLake Storage kan göras tillgängliga för skriptet och användas vid körning.

Artefakterna görs tillgängliga för att skriptet ska kunna läsas från en lokal tillfällig katalog, .\Temp. Namnen som anges i egenskapsväskan används som lokala filnamn. Se Exempel.

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

Uppdatera 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

Installera paket på följande sätt:

Förutsättning

• Skapa ett lakehouse som värd för paketen, helst på samma arbetsyta som ditt eventhouse.

Installera paket

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

   • Kör från ett cmd-fönster i din lokala Windows Python-miljö:

   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.
   • För offentliga paket zippar du de filer som laddades ned i föregående steg.

   Anmärkning

   • Se till att ladda ned paketet som är kompatibelt med Python-motorn och plattformen för sandbox-körningen (för närvarande 3.10.8 eller 3.11.7 i Windows)
   • Se till att zippa .whl själva filerna 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 zip-filen till lakehouse.

4. Kopiera OneLake-URL:en (från egenskaperna för den zippade filen)

5. Anropa plugin-programmet python .

   • Ange parametern external_artifacts med en egenskapsuppsättning med lokalt namn och OneLake-URL:en för zip-filen.
   • I din infogade Python-kod importerar Zipackage du från sandbox_utils och anropar dess install() metod med namnet på ZIP-filen.

Exempel med externa artefakter

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://msit-onelake.dfs.fabric.microsoft.com/MSIT_DEMO_WS/MSIT_DEMO_LH.Lakehouse/Files/Faker.zip;impersonate'))

Relaterat innehåll

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