Javaでのストアドプロシージャの記述¶

前提条件¶

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

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

Snowparkの開発環境の設定¶

Snowparkライブラリを使用するように開発環境を設定します。 Snowpark Javaの開発環境の設定 をご参照ください。

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

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

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

制限事項¶

Snowparkストアドプロシージャには、次の制限があります。

• 同時実行はサポートされていません。たとえば、コード内からは、複数のスレッドからクエリを送信することはできません。複数のクエリを同時に発行するコードはエラーを生成します。

• タスクからストアドプロシージャを実行する場合は、タスクの作成時にウェアハウスを指定する必要があります。（Snowflakeが管理するコンピューティングリソースを使用してタスクを実行することはできません。）

• Javaによるストアドプロシージャハンドラーコードからのファイルの読み取りと書き込みは、まだ完全にはサポートされていません。ファイルを読み書きすると、動作が不安定になる場合があります。これには、引数として InputStream を受け取り、 put や get などの FileOperation クラス（通常は Session.file メソッドを介してアクセス）から利用可能なメソッドを使用することが含まれます。

• ストアドプロシージャでSnowpark APIs を使用する場合は、次の制限に注意してください。

  • PUT および GET コマンドを実行する APIs （Session.sql("PUT ...") および Session.sql("GET ...") を含む）を使用する場合は、プロシージャを呼び出すクエリ用に提供されたメモリバックアップファイルシステムの/tmpディレクトリにのみ書き込むことができます。

  • 非同期アクション用 APIs は使用しないでください。

  • 新しいセッションを作成する APIs （例: Session.builder().configs(...).create()）は使用しないでください。

  • session.jdbcConnection （およびそこから返される接続）の使用は、安全ではない動作を引き起こす可能性があるため、サポートされていません。

• 名前付き仮オブジェクトの作成は、所有者権限のストアドプロシージャではサポートされていません。所有者権限ストアドプロシージャは、ストアドプロシージャ所有者の権限で実行されるストアドプロシージャです。詳細については、 呼び出し元の権限または所有者の権限 をご参照ください。

ストアドプロシージャの記述の計画¶

クラスの記述¶

定義するメソッドは、クラスの一部である必要があります。

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

• クラスとメソッドは保護したり、プライベートにしたりしないでください。

• メソッドが静的ではなく、コンストラクターを定義する場合は、クラスの引数がゼロのコンストラクターを定義します。Snowflakeは、初期化時にこの引数がゼロのコンストラクターを呼び出して、クラスのインスタンスを作成します。

• 同じクラス内の異なるストアドプロシージャに対して異なるメソッドを定義できます。

メソッドの記述¶

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

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

  ストアドプロシージャを呼び出すと、Snowflakeは自動的に Session オブジェクトを作成し、ストアドプロシージャに渡します。（Session オブジェクトを自分で作成することはできません。）

• 残りの引数と戻り値には、 Snowflakeデータ型 に対応する Java型 を使用します。

• メソッドは値を返す必要があります。Javaのストアドプロシージャの場合は、戻り値が必要です。

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

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

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

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

ストアドプロシージャからSnowflakeへのデータのアクセス¶

Snowflakeのデータにアクセスするには、Snowparkライブラリ APIs を使用します。

Javaストアドプロシージャへの呼び出しを処理する場合、Snowflakeは、Snowpark Session オブジェクトを作成し、そのオブジェクトをストアドプロシージャのメソッドに渡します。

他の言語におけるストアドプロシージャの場合と同様に、セッションのコンテキスト（例: 権限、現在のデータベースおよびスキーマ）は、ストアドプロシージャが呼び出し元の権限で実行されるか、所有者の権限で実行されるかによって決まります。詳細については、 セッション状態へのアクセスおよび設定 をご参照ください。

この Session オブジェクトを使用して、 Snowparkライブラリ の APIs を呼び出すことができます。たとえば、 テーブルの DataFrame を作成 したり、 SQL ステートメントを実行したりできます。

詳細については、 Java用Snowpark開発者ガイド をご参照ください。

import com.snowflake.snowpark_java.*;

public class MyClass
{
  public String myMethod(Session session, String fromTable, String toTable, int count)
  {
    session.table(fromTable).limit(count).write().saveAsTable(toTable);
    return "Success";
  }
}

他のクラスとリソースファイルへのアクセス¶

コードがストアドプロシージャの外部で定義されたクラス（例: 別の JAR ファイル内のクラス）またはリソースファイルに依存している場合、それらの依存関係をステージにアップロードすると、ハンドラーはそれらの依存関係を利用できるようになります。詳細については、 コードで依存関係を利用できるようにする方法 をご参照ください。

後で CREATE PROCEDURE ステートメント を実行するときに、 IMPORTS 句を使用してこれらのファイルをポイントします。

Javaコードのコンパイルとパッケージ化¶

ストアドプロシージャの設定を簡単にするために、ストアドプロシージャに必要なすべての依存関係を含む JAR ファイルをビルドします。後で、 JAR ファイルをステージにアップロードし、 CREATE PROCEDURE ステートメントから JAR ファイルをポイントする必要があります。アップロードしてポイントする JAR ファイルが少ない場合、このプロセスは簡単です。

コードの場所の選択に関する詳細は、 ハンドラーコードのインラインまたはステージ上での保持 をご参照ください。

ステージへのファイルのアップロード¶

プロシージャーのロジック（およびその他の依存関係がある場合）をプロシージャーで使用できるようにするには、ステージに必要なファイルをアップロードする必要があります。詳細については、 コードで依存関係を利用できるようにする方法 をご参照ください。

例¶

このセクションの例は、列が文字列と一致する行をフィルターするプロシージャーから表形式の値を返すことを示しています。

CREATE OR REPLACE TABLE employees(id NUMBER, name VARCHAR, role VARCHAR);
INSERT INTO employees (id, name, role) VALUES (1, 'Alice', 'op'), (2, 'Bob', 'dev'), (3, 'Cindy', 'dev');

CREATE OR REPLACE PROCEDURE filter_by_role(table_name VARCHAR, role VARCHAR)
RETURNS TABLE(id NUMBER, name VARCHAR, role VARCHAR)
LANGUAGE JAVA
RUNTIME_VERSION = '11'
PACKAGES = ('com.snowflake:snowpark:latest')
HANDLER = 'Filter.filterByRole'
AS
$$
import com.snowflake.snowpark_java.*;

public class Filter {
  public DataFrame filterByRole(Session session, String tableName, String role) {
    DataFrame table = session.table(tableName);
    DataFrame filteredRows = table.filter(Functions.col("role").equal_to(Functions.lit(role)));
    return filteredRows;
  }
}
$$;

CREATE OR REPLACE PROCEDURE test_return_geography_table_1()
RETURNS TABLE(g GEOGRAPHY)
...

CALL test_return_geography_table_1();

Stored procedure execution error: data type of returned table does not match expected returned table type

CREATE OR REPLACE PROCEDURE test_return_geography_table_1()
RETURNS TABLE()
...

CREATE OR REPLACE PROCEDURE filter_by_role(table_name VARCHAR, role VARCHAR)
RETURNS TABLE()
LANGUAGE JAVA
RUNTIME_VERSION = '11'
PACKAGES = ('com.snowflake:snowpark:latest')
HANDLER = 'FilterClass.filterByRole'
AS
$$
import com.snowflake.snowpark_java.*;

public class FilterClass {
  public DataFrame filterByRole(Session session, String tableName, String role) {
    DataFrame table = session.table(tableName);
    DataFrame filteredRows = table.filter(Functions.col("role").equal_to(Functions.lit(role)));
    return filteredRows;
  }
}
$$;

CALL filter_by_role('employees', 'dev');

+----+-------+------+
| ID | NAME  | ROLE |
+----+-------+------+
| 2  | Bob   | dev  |
| 3  | Cindy | dev  |
+----+-------+------+