Python プラグイン

Python プラグインは、Python スクリプトを使用してユーザー定義関数 (UDF) を実行します。 Python スクリプトは、表形式のデータを入力として取得し、表形式の出力を生成します。 プラグインのランタイムはクラスターのノードで実行されている サンドボックスでホストされます。

構文

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

構文規則について詳しく知る。

パラメーター

予約済み Python 変数

次の変数は、Kusto 照会言語と Python コード間のやり取りのために予約されています。

• df: T DataFrame としての入力表形式データ (上記の pandas の値)。
• kargs: Python 辞書としての引数 script_parameters の値。
• result: Python スクリプトにより作成された pandas DataFrame。この値は、プラグインの後に続く Kusto クエリ演算子に送信される表形式データになります。

プラグインの有効化

プラグインは既定では無効です。 開始する前に、 前提条件の一覧を確認します。 プラグインを有効にし、Python イメージのバージョンを選択するには、クラスターで 使用可能な言語拡張機能を参照してください。

Python サンドボックス イメージ

Python イメージのバージョンを別のマネージド イメージまたはカスタム イメージに変更するには、「 クラスター上の Python 言語拡張イメージを変更するを参照してください。

さまざまな Python イメージのパッケージの一覧については、Python パッケージ リファレンス 参照してください。

クエリと更新ポリシーからのインジェストを使用する

• 次のクエリでプラグインを使用します。
  • キューに登録されたインジェストによってソース テーブルが取り込まれる更新ポリシーの一部として定義されます。
  • など.set-or-appendコマンドの一部として実行される。
• ソース テーブルがストリーミング インジェストを使用して取り込まれた更新ポリシーの一部として定義されているクエリでは、このプラグインを使用することはできません。

例

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 

パフォーマンスに関するヒント

• プラグインの入力データセットを、必要な最小量 (列/行) に減らします。
  • 可能な場合は、Kusto のクエリ言語でソース データセットにフィルターを使用します。
  • ソース列のサブセットに対して計算を行うには、プラグインを呼び出す前に、その列だけをプロジェクトに含めます。
• スクリプト内のロジックが配布可能な場合は、hint.distribution = per_nodeを使用します。
  • パーティション演算子を使用して、入力データセットをパーティション分割することもできます。
• Python スクリプトのロジックを実装するときには、可能な限り Kusto のクエリ言語を使用してください。

使用上のヒント

• クエリ エディターで Python スクリプトを含む複数行の文字列を生成するには、お気に入りの Python エディター (Jupyter、 Visual Studio Code、 PyCharm など) から Python スクリプトをコピーし、クエリ エディターに貼り付けて、3 つの連続するバックティックを含む行間で完全なスクリプトを囲みます。 次に例を示します。

  ```
python code
```

• externaldata 演算子を使用して、Azure Blob Storage などの外部の場所に保存したスクリプトの内容を取得します。

Python スクリプトの外部データの読み取りの例

    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 

外部成果物の使用

クラウド ストレージからの外部成果物をスクリプトで使用でき、実行時に使用できます。

外部成果物プロパティによって参照される URL は次の値である必要があります。

• クラスターのコールアウト ポリシーに含まれている。
• 一般公開されている場所にあるか、またはストレージ接続文字列に関するページで説明されている必要な資格情報を提供する。

成果物は、スクリプトをローカルの一時ディレクトリ ( .\Temp) から読み取るために使用できます。 プロパティ バッグに指定された名前は、ローカル ファイル名として使用されます。 「例」を参照してください。

外部パッケージの参照については、「 Install packages for the Python plugin(Python プラグインのパッケージのインストール)」を参照してください。

外部成果物キャッシュの更新

クエリで使用される外部成果物ファイルは、クラスターにキャッシュされます。 クラウド ストレージ内のファイルを更新し、クラスターとの即時同期が必要な場合は、 .clear クラスター キャッシュの外部成果物コマンドを使用できます。 このコマンドは、キャッシュされたファイルをクリアし、後続のクエリが最新バージョンの成果物で確実に実行されるようにします。

Python プラグインのパッケージをインストールする

ほとんどのユース ケースでは、カスタム イメージを 作成することをお。

次の理由により、パッケージを自分でインストールできます。

• カスタム イメージを作成するためのアクセス許可がありません。
• パッケージはプライベートです。
• テスト用のアドホック パッケージ インストールを作成することを好み、カスタム イメージを作成するオーバーヘッドは必要ありません。

パッケージを次のようにインストールします。

前提条件

1. パッケージをホストする BLOB コンテナーを作成します。できれば、クラスターと同じ場所に作成します。 たとえば https://artifactswestus.blob.core.windows.net/python では、クラスターが米国西部にあると想定されています。

2. クラスターのコールアウト ポリシーを変更して、その場所へのアクセスを許可します。

   • この変更を行うには、AllDatabasesAdmin アクセス許可が必要です。

   • たとえば、https://artifactswestus.blob.core.windows.net/python にある BLOB にアクセスできるようにするには、次のコマンドを実行します。

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

パッケージをインストールする

1. PyPi またはその他のチャネルのパブリック パッケージの場合は、パッケージとその依存関係をダウンロードします。

   • ローカルの Windows Python 環境の cmd ウィンドウで、次のコマンドを実行します。

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

2. 必要なパッケージとその依存関係を含む zip ファイルを作成します。

   • プライベート パッケージの場合は、パッケージのフォルダーとその依存関係のフォルダーを zip 圧縮します。
   • パブリック パッケージの場合は、前の手順でダウンロードしたファイルを zip 圧縮します。

   注

   • Python エンジンとサンドボックス ランタイムのプラットフォーム (Windows では現在 3.10.8 または 3.11.7) と互換性のあるパッケージをダウンロードしてください
   • 親フォルダーではなく、.whl ファイル自体を zip 圧縮してください。
   • ベース サンドボックス イメージに同じバージョンが既に存在するパッケージの .whl ファイルをスキップできます。

3. zip ファイルを成果物の場所の BLOB にアップロードします (前提条件の手順 1 から)。

4. python プラグインを呼び出します。

   • zip ファイルのローカル名と BLOB URL (SAS トークンを含む) のプロパティ バッグを使用して、 external_artifacts パラメーターを指定します。
   • インライン Python コードで、Zipackageからsandbox_utilsをインポートし、ZIP ファイルのローカル名でそのinstall() メソッドを呼び出します。

外部成果物の使用例

偽のデータを生成する Faker パッケージをインストールします。

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

関連するコンテンツ

Python プラグインを使用する UDF 関数のその他の例については、 Functions ライブラリを参照してください。

Python プラグインは、Python スクリプトを使用してユーザー定義関数 (UDF) を実行します。 Python スクリプトは、表形式のデータを入力として取得し、表形式の出力を生成します。

構文

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

構文規則について詳しく知る。

パラメーター

予約済み Python 変数

次の変数は、Kusto 照会言語と Python コード間のやり取りのために予約されています。

• df: T DataFrame としての入力表形式データ (上記の pandas の値)。
• kargs: Python 辞書としての引数 script_parameters の値。
• result: Python スクリプトにより作成された pandas DataFrame。この値は、プラグインの後に続く Kusto クエリ演算子に送信される表形式データになります。

プラグインの有効化

プラグインは既定では無効です。 開始する前に、KQL データベースで Python プラグインを有効にしてください。

Python サンドボックス イメージ

さまざまな Python イメージのパッケージの一覧については、Python パッケージ リファレンス 参照してください。

クエリと更新ポリシーからのインジェストを使用する

• 次のクエリでプラグインを使用します。
  • キューに登録されたインジェストによってソース テーブルが取り込まれる更新ポリシーの一部として定義されます。
  • など.set-or-appendコマンドの一部として実行される。
• ソース テーブルがストリーミング インジェストを使用して取り込まれた更新ポリシーの一部として定義されているクエリでは、このプラグインを使用することはできません。

例

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 

パフォーマンスに関するヒント

• プラグインの入力データセットを、必要な最小量 (列/行) に減らします。
  • 可能な場合は、Kusto のクエリ言語でソース データセットにフィルターを使用します。
  • ソース列のサブセットに対して計算を行うには、プラグインを呼び出す前に、その列だけをプロジェクトに含めます。
• スクリプト内のロジックが配布可能な場合は、hint.distribution = per_nodeを使用します。
  • パーティション演算子を使用して、入力データセットをパーティション分割することもできます。
• Python スクリプトのロジックを実装するときには、可能な限り Kusto のクエリ言語を使用してください。

使用上のヒント

• クエリ エディターで Python スクリプトを含む複数行の文字列を生成するには、お気に入りの Python エディター (Jupyter、 Visual Studio Code、 PyCharm など) から Python スクリプトをコピーし、クエリ エディターに貼り付けて、3 つの連続するバックティックを含む行間で完全なスクリプトを囲みます。 次に例を示します。

  ```
python code
```

• externaldata 演算子を使用して、Azure Blob Storage などの外部の場所に保存したスクリプトの内容を取得します。

Python スクリプトの外部データの読み取りの例

    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 

外部成果物の使用

OneLake ストレージからの外部成果物をスクリプトで使用でき、実行時に使用できます。

成果物は、スクリプトをローカルの一時ディレクトリ ( .\Temp) から読み取るために使用できます。 プロパティ バッグに指定された名前は、ローカル ファイル名として使用されます。 「例」を参照してください。

外部パッケージの参照については、「 Install packages for the Python plugin(Python プラグインのパッケージのインストール)」を参照してください。

外部成果物キャッシュの更新

クエリで使用される外部成果物ファイルは、クラスターにキャッシュされます。 クラウド ストレージ内のファイルを更新し、クラスターとの即時同期が必要な場合は、 .clear クラスター キャッシュの外部成果物コマンドを使用できます。 このコマンドは、キャッシュされたファイルをクリアし、後続のクエリが最新バージョンの成果物で確実に実行されるようにします。

Python プラグインのパッケージをインストールする

パッケージを次のようにインストールします。

前提条件

• パッケージをホストするレイクハウスを作成します。できれば、イベントハウスと同じワークスペースに置きます。

パッケージをインストールする

1. PyPi またはその他のチャネルのパブリック パッケージの場合は、パッケージとその依存関係をダウンロードします。

   • ローカルの Windows Python 環境の cmd ウィンドウで、次のコマンドを実行します。

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

2. 必要なパッケージとその依存関係を含む zip ファイルを作成します。

   • プライベート パッケージの場合は、パッケージのフォルダーとその依存関係のフォルダーを zip 圧縮します。
   • パブリック パッケージの場合は、前の手順でダウンロードしたファイルを zip 圧縮します。

   注

   • Python エンジンとサンドボックス ランタイムのプラットフォーム (Windows では現在 3.10.8 または 3.11.7) と互換性のあるパッケージをダウンロードしてください
   • 親フォルダーではなく、.whl ファイル自体を zip 圧縮してください。
   • ベース サンドボックス イメージに同じバージョンが既に存在するパッケージの .whl ファイルをスキップできます。

3. zip ファイルを lakehouse にアップロードします。

4. OneLake URL をコピーします (zip 形式のファイルのプロパティから)

5. python プラグインを呼び出します。

   • ローカル名のプロパティ バッグと zip ファイルの OneLake URL を使用して、 external_artifacts パラメーターを指定します。
   • インライン Python コードで、Zipackageからsandbox_utilsをインポートし、ZIP ファイルの名前を使用してそのinstall() メソッドを呼び出します。

外部成果物の使用例

偽のデータを生成する Faker パッケージをインストールします。

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

関連するコンテンツ

Python プラグインを使用する UDF 関数のその他の例については、 Functions ライブラリを参照してください。