SQL で作成されたストアドプロシージャの Java ハンドラーを記述します。¶

ハンドラーが Java で記述されたストアドプロシージャを作成できます。ストアドプロシージャ内で Snowparkライブラリを使用して、Snowflakeのテーブルに対してクエリ、更新、およびその他の作業を実行できます。

ストアドプロシージャを使用すると、Snowflakeウェアハウスをコンピュートフレームワークとして使用して、Snowflake内でデータパイプラインを構築して実行できます。データパイプラインのコードでは、JavaのSnowpark API を使用してストアドプロシージャを記述します。これらのストアドプロシージャの実行をスケジュールするには、タスクを使用します。

ハンドラーコードの実行時にログをキャプチャし、データをトレースできます。詳細については、ロギング、トレース、メトリクスをご参照ください。

ストアドプロシージャのJavaハンドラーの書き方¶

お使いの環境が前提条件を満たしていることを確認してください。
ローカルで開発している場合は、 Snowparkを使用するように環境をセットアップしてください。
ハンドラーインラインに配置するか、ステージに配置するかを選択します。
ハンドラークラス、メソッド、パフォーマンスのガイドラインに従ってください。
データアクセス、データファイル読み取り、テーブル形式データを返す、ログとトレースなどの機能のサポートを実装します。
コードの依存関係を Snowflake で利用可能にします。
ストアドプロシージャを作成する際に、ハンドラーコードをインラインで含めるか、ステージからインポートしてください。

注釈

匿名プロシージャの作成と呼び出しの両方を実行するには、 CALL （匿名プロシージャでの場合）を使用します。匿名プロシージャの作成と呼び出しには、 CREATE PROCEDURE スキーマ権限を持つロールは必要ありません。

前提条件¶

バージョン1.3.0または最新バージョンのSnowparkライブラリを使用する必要があります。

ストアドプロシージャを記述している場合は、以下のJavaバージョンのいずれかで実行するようにクラスをコンパイルする必要があります。

11.x
17.x

Snowparkの開発環境の設定¶

ローカルでコードを開発している場合は、Snowparkライブラリを使用するように開発環境をセットアップしてください。 Snowpark Javaの開発環境の設定をご参照ください。

ハンドラーコードの構造化とビルド¶

プロシージャを作成する SQL とインラインでハンドラーソースコードを保持するか、別の場所にハンドラーのコンパイル結果を保持して SQL から参照することができます。詳細については、ハンドラーコードのインラインまたはステージ上での保持をご参照ください。

プロシージャで使用するハンドラーソースコードのビルドの詳細については、ハンドラーコードのパッケージ化をご参照ください。

ハンドラー・クラスのガイドライン¶

クラスを記述するときは、次の点に注意してください。

クラスとメソッドは保護したり、プライベートにしたりしないでください。
メソッドが静的ではなく、コンストラクターを定義する場合は、クラスの引数がゼロのコンストラクターを定義します。Snowflakeは、初期化時にこの引数がゼロのコンストラクターを呼び出して、クラスのインスタンスを作成します。
同じクラス内の異なるストアドプロシージャに対して異なるメソッドを定義できます。

ハンドラーメソッドのガイドライン¶

ストアドプロシージャのメソッドを記述するときは、次の点に注意してください。

メソッドの最初の引数としてSnowpark Session オブジェクトを指定します。

ストアドプロシージャを呼び出すと、Snowflakeは自動的に Session オブジェクトを作成し、ストアドプロシージャに渡します。（Session オブジェクトを自分で作成することはできません。）
残りの引数と戻り値には、 Snowflakeデータ型に対応する Java型を使用します。
メソッドは値を返す必要があります。Javaのストアドプロシージャの場合は、戻り値が必要です。
コードのアクティビティによってタイマーがリセットされない限り、ストアドプロシージャの実行はタイムアウトになります。特に、タイムアウトタイマーは、ファイル操作、クエリ、結果セットの反復など、コードとデータの相互作用によってリセットされます。
プロシージャのハンドラー内から非同期子ジョブを実行する場合、"fire and forget"（ファイアアンドフォーゲット）はサポートされていません。

言い換えると、親プロシージャのジョブが完了したときに、ハンドラーがまだ実行中の子クエリを実行した場合、子ジョブは自動的にキャンセルされます。

エラーの処理¶

通常のJava例外処理テクニックを使って、ハンドラーコード内のエラーをキャッチできます。

メソッド内でキャッチされない例外が発生した場合、Snowflakeは例外のスタックトレースを含むエラーを発生させます。未処理の例外のログを有効にすると、Snowflakeは未処理の例外に関するデータをイベントテーブルに記録します。

ハンドラーのパフォーマンスとセキュリティに関するガイドライン¶

Snowflake上でコードを確実に実行するには、以下のガイドラインに従ってください。

消費されるメモリの量を制限する

Snowflakeは、必要なメモリ量に関してメソッドに制限を設けています。過度の消費を回避する方法の詳細については、 Snowflakeが課す制約内でのハンドラーの設計をご参照ください。
スレッドセーフなコードを記述する。

ハンドラーメソッドまたは関数がスレッドセーフであることを確認してください。
セキュリティ制限を理解する。

ハンドラーコードは制限されたエンジン内で実行されるため、 UDFs とプロシージャのセキュリティプラクティスで説明されているルールに従ってください。
所有者の権限または呼び出し元の権限の使用を決定する。

ストアドプロシージャの記述を計画するときは、ストアドプロシージャを呼び出し元の権限または所有者の権限で実行するかどうかを検討します。
ストアドプロシージャのタイムアウト動作に注意してください。

コードのアクティビティによってタイマーがリセットされない限り、ストアドプロシージャの実行はタイムアウトになります。特に、タイムアウトタイマーは、ファイル操作、クエリ、結果セットの反復など、コードとデータの相互作用によってリセットされます。

コードで依存関係を利用できるようにする方法¶

ハンドラーコードがハンドラー自体の外部で定義されたコード（JAR ファイル内のクラスなど）またはリソースファイルに依存している場合は、それらの依存関係をステージにアップロードすると、それらの依存関係をコードで使用できるようにすることができます。プロシージャを作成するときに、 IMPORTS 句を使用してこれらの依存関係を参照できます。

詳細については、コードで依存関係を利用できるようにする方法をご参照ください。