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

前提条件¶

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

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

Snowparkの開発環境の設定¶

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

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

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

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

プロシージャの作成と呼び出し¶

プロシージャのハンドラーを記述すると、 SQL を使ってそのハンドラーを作成し、呼び出すことができます。

• ストアドプロシージャの作成

  SQL を使用してストアドプロシージャを作成する方法については、 ストアドプロシージャの作成 をご参照ください。

  SQL を使った匿名プロシージャの作成については、 CALL （匿名プロシージャの場合） をご参照ください。

• ストアドプロシージャの呼び出し

  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は、必要なメモリ量に関してメソッドに制限を設けています。過度の消費を回避する方法の詳細については、 Snowflakeが課す制約内でのハンドラーの設計 をご参照ください。

• スレッドセーフなコードを記述する。

  ハンドラーメソッドまたは関数がスレッドセーフであることを確認してください。

• セキュリティ制限を理解する。

  ハンドラーコードは制限されたエンジン内で実行されるため、 UDFs とプロシージャのセキュリティプラクティス で説明されているルールに従ってください。

• 所有者の権限または呼び出し元の権限の使用を決定する。

  ストアドプロシージャの記述を計画するときは、ストアドプロシージャを 呼び出し元の権限または所有者の権限 で実行するかどうかを検討します。

• ストアドプロシージャのタイムアウト動作に注意してください。

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

クラスの記述¶

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

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

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

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

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

メソッドの記述¶

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

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

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

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

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

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

エラーの処理¶

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

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

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

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

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

データアクセスの例¶

以下は、指定された数の行を1つのテーブルから別のテーブルにコピーするJavaメソッドの例です。このメソッドは次の引数を取ります。

• Snowpark Session オブジェクト

• 行をコピーするテーブルの名前

• 行を保存するテーブルの名前

• コピーする行の数。

この例のメソッドは文字列を返します。

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

SnowflakeFile を使用した動的に指定されたファイルの読み取り¶

次の例のコードには、 String を受け取り、ファイルの内容を含む String を返す、ハンドラー関数 execute があります。実行時に、Snowflakeはプロシージャの input 変数にある受信ファイルパスからのハンドラーの fileName 変数を初期化します。ハンドラーコードは、 SnowflakeFile インスタンスを使用してファイルを読み取ります。

CREATE OR REPLACE PROCEDURE file_reader_java_proc_snowflakefile(input VARCHAR)
RETURNS VARCHAR
LANGUAGE JAVA
RUNTIME_VERSION = 11
HANDLER = 'FileReader.execute'
PACKAGES=('com.snowflake:snowpark:latest')
AS $$
import java.io.InputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import com.snowflake.snowpark_java.types.SnowflakeFile;
import com.snowflake.snowpark_java.Session;

class FileReader {
  public String execute(Session session, String fileName) throws IOException {
    InputStream input = SnowflakeFile.newInstance(fileName).getInputStream();
    return new String(input.readAllBytes(), StandardCharsets.UTF_8);
  }
}
$$;

次の CALL の例にあるコードは、ファイルをポイントするスコープ付きファイル URL を作成します。これは、ステージ自体に権限を付与することなく、ステージングされたファイルへの仮アクセスを許可するエンコードされた URL です。

CALL file_reader_java_proc_snowflakefile(BUILD_SCOPED_FILE_URL('@sales_data_stage', '/car_sales.json'));

String filename = "@my_stage/filename.txt";
String sfFile = SnowflakeFile.newInstance(filename, false);

InputStream を使用した動的に指定されたファイルの読み取り¶

次の例のコードには、 InputStream を受け取り、ファイルの内容を含む String を返す、ハンドラー関数 execute があります。実行時に、Snowflakeはプロシージャの input 引数にある受信ファイルパスからのハンドラーの stream 変数を初期化します。ハンドラーコードは、 InputStream を使用してファイルを読み取ります。

CREATE OR REPLACE PROCEDURE file_reader_java_proc_input(input VARCHAR)
RETURNS VARCHAR
LANGUAGE JAVA
RUNTIME_VERSION = 11
HANDLER = 'FileReader.execute'
PACKAGES=('com.snowflake:snowpark:latest')
AS $$
import java.io.InputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import com.snowflake.snowpark.Session;

class FileReader {
  public String execute(Session session, InputStream stream) throws IOException {
    String contents = new String(stream.readAllBytes(), StandardCharsets.UTF_8);
    return contents;
  }
}
$$;

次の CALL の例にあるコードは、ファイルをポイントするスコープ付きファイル URL を作成します。これは、ステージ自体に権限を付与することなく、ステージングされたファイルへの仮アクセスを許可するエンコードされた URL です。

CALL file_reader_java_proc_input(BUILD_SCOPED_FILE_URL('@sales_data_stage', '/car_sales.json'));

例¶

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

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

WITH test_return_geography_table_1() AS PROCEDURE
  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()
  ...

WITH test_return_geography_table_1() AS PROCEDURE
  RETURNS TABLE()
  ...
CALL test_return_geography_table_1();

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  |
+----+-------+------+