Python プラグイン

[アーティクル]
10/15/2024

適用対象: ✅Microsoft Fabric✅Azure データエクスプローラー

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

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

パラメーター

件名	タイプ	Required	説明
output_schema	`string`	✔️	Python コードによって返される表形式データの出力スキーマを定義する `type` リテラル。形式は `typeof(`ColumnName`:` ColumnType[, ...]`)`です。たとえば、 `typeof(col1:string, col2:long)`。入力スキーマを拡張するには、`typeof(*, col1:string, col2:long)` という構文を使用します。
script	`string`	✔️	実行する有効な Python スクリプト。複数行の文字列を生成するには、使用のヒントを参照してください。
script_parameters	`dynamic`		予約された `kargs` ディクショナリとして Python スクリプトに渡される名前と値のペアのプロパティバッグ。詳しくは、「予約済み Python 変数」を参照してください。
hint.distribution	`string`		プラグインの実行を複数のクラスターノードに分散するためのヒント。既定値は `single` です。 `single` は、スクリプトの 1 つのインスタンスがクエリデータ全体に対して実行されることを意味します。 `per_node` は、Python ブロックの前のクエリが分散されている場合、スクリプトのインスタンスは、含まれているデータ上の各ノードで実行されることを意味します。
hint.remote	`string`		このヒントは、クロスクラスタークエリにのみ関連します。既定値は `auto` です。 `auto` は、サーバーが Python コードを実行するクラスターを自動的に決定することを意味します。値を `local` に設定すると、ローカルクラスターで Python コードが強制的に実行されます。リモートクラスターで Python プラグインが無効になっている場合に使用します。
external_artifacts	`dynamic`		クラウドストレージからアクセスできる成果物の名前と URL のペアのプロパティバッグ。詳細については、「外部成果物の使用を参照してください。
spill_to_disk	`bool`		入力テーブルを Python サンドボックスにシリアル化するための別の方法を指定します。大きなテーブルをシリアル化する場合は、シリアル化を高速化し、サンドボックスのメモリ消費量を大幅に削減するため、`true` に設定します。既定値は `true` です。

予約済み Python 変数

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

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

プラグインの有効化

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

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

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

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

Note

既定では、プラグインは numpy np pandas pd としてインポートします。必要に応じて、必要に応じて他のモジュールをインポートできます。
一部のパッケージは、プラグインが実行されるサンドボックスによって適用される制限と互換性がない可能性があります。

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

次のクエリでプラグインを使用します。
- 非ストリーミング インジェストを使用してソーステーブルが取り込まれた更新ポリシーの一部として定義されている。
- .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

クエリ結果を示すサインデモのスクリーンショット。

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"})
)

ファイル	サイズ
this_is_a_script	120
this_is_my_first_file	105

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

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

使用上のヒント

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

```
python code
```
externaldata 演算子を使用して、Azure BLOB Storage などの外部の場所に格納したスクリプトの内容を取得します。

例

    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 は次の値である必要があります。

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

Note

マネージド ID を使用して外部成果物を認証する場合、 SandboxArtifacts の使用状況は、管理 ID ポリシークラスターレベルで定義する必要があります。

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

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

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

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