Python プラグイン

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

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

構文

T|evaluate [hint.distribution= (single | per_node)] [ (autohint.remote | =local)] python(output_schema,スクリプト [,script_parameters] [,external_artifacts][,spill_to_disk])

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

パラメーター

名前	型	必須	説明
output_schema	`string`	✔️	`type` Python コードによって返される表形式データの出力スキーマを定義するリテラル。形式は `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 パッケージリファレンス」を参照してください。

注意

既定では、プラグインは 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 は、次のようにする必要があります。

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

注意

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

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

外部パッケージの参照については、「 Python プラグインのパッケージをインストールする」を参照してください。

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

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