表形式のJava UDFs （UDTFs）¶

パーティション分割の使用上の注意¶

• Snowflakeによって暗黙的にパーティション分割された行を受け取ると、ハンドラーコードはパーティションについて何も仮定できません。明示的なパーティション分割の実行は、 UDTF が出力を生成するために行を分離して見るだけで、行間でステージを集約しない場合に最も役立ちます。この場合、コードには大抵、コンストラクターや endPartition メソッドを必要としません。

• パフォーマンスを向上させるために、Snowflakeは通常、 UDTF ハンドラーコードの複数のインスタンスを並行して実行します。行の各パーティションは、 UDTF の単一のインスタンスに渡されます。

• 各パーティションは1つの UDTF インスタンスのみで処理されますが、逆も当てはまるとは限りません。単一の UDTF インスタンスは、複数のパーティションを順に処理できます。したがって、初期化子とファイナライザーを使用して各パーティションの初期化とクリーンアップを行い、累積値が、1つのパーティションの処理から別のパーティションの処理に持ち越されないようにすることが重要です。

ハンドラークラス¶

Snowflakeは、主にハンドラークラスの次のメソッドを呼び出すことによって UDTF と対話します。

• 初期化子（コンストラクター）。

• 行ごとの方法（process）。

• ファイナライザーメソッド（endPartition）。

ハンドラークラスには、これら3つのメソッドをサポートするために必要な追加のメソッドを含めることができます。

ハンドラークラスには、後で説明するメソッド getOutputClass も含まれています。

ハンドラークラス（または 出力行クラス）の任意のメソッドから例外をスローすると、処理が停止します。UDTF を呼び出したクエリは、エラーメッセージを表示して失敗します。

import java.util.stream.Stream;

...

public Stream<OutputRow> process(String v) {
  return Stream.of(new OutputRow(v));
}

...

public Stream<OutputRow> process(int number) {
  if (inputNumber < 1) {
    return Stream.empty();
  }
  return Stream.of(new OutputRow(number));
}

出力行クラス¶

Snowflakeは、出力行クラスを使用して、Javaデータ型と SQL データ型の間の変換を指定します。

Java UDTF が行を返す場合、行の各列の値をJavaデータ型から対応する SQL データ型に変換する必要があります。SQL データ型は、 CREATE FUNCTION ステートメントの RETURNS 句で指定されます。ただし、Javaと SQL のデータ型間のマッピングは1対1ではないため、Snowflakeは返された各列のJavaデータ型を知る必要があります。（マッピング SQL およびJavaデータ型の詳細については、 SQL-Javaデータ型マッピング をご参照ください。）

Java UDTF は、出力行クラスを定義することにより、出力列のJavaデータ型を指定します。UDTF から返される各行は、出力行クラスのインスタンスとして返されます。出力行クラスの各インスタンスには、出力列ごとに1つのパブリックフィールドが含まれます。Snowflakeは、出力行クラスの各インスタンスからパブリックフィールドの値を読み取り、Java値を SQL 値に変換し、それらの値を含む SQL 出力行を作成します。

出力行クラスの各インスタンスの値は、出力行クラスのコンストラクターを呼び出すことによって設定されます。コンストラクターは、出力列に対応するパラメーターを受け入れ、パブリックフィールドをそれらのパラメーターに設定します。

以下のコードは、サンプルの出力行クラスを定義しています。

class OutputRow {

  public String name;
  public int id;

  public OutputRow(String pName, int pId) {
    this.name = pName;
    this.id = pId
  }

}

このクラスで指定されるパブリック変数は、 CREATE FUNCTION ステートメントの RETURNS TABLE (...) 句で指定された列と一致する必要があります。たとえば、上記の OutputRow クラスは、以下の RETURNS 句に対応します。

CREATE FUNCTION F(...)
    RETURNS TABLE(NAME VARCHAR, ID INTEGER)
    ...

出力行クラスは次のように使用されます。

• ハンドラークラスは、出力行クラスを使用して、 process メソッドと endPartition メソッドの戻り値の型を指定します。ハンドラークラスは、出力行クラスも使用して戻り値を作成します。例:

  public Stream<OutputRow> process(String v) {
    ...
    return Stream.of(new OutputRow(...));
  }
  
  public Stream<OutputRow> endPartition() {
    ...
    return Stream.of(new OutputRow(...));
  }
  

  Copy

• 出力行クラスは、ハンドラークラスの getOutputClass メソッドでも使用されます。これは、Snowflakeが出力のJavaデータ型を学習するために呼び出す静的メソッドです。

  public static Class getOutputClass() {
    return OutputRow.class;
  }
  

  Copy

出力行クラス（またはハンドラークラス）の任意のメソッドから例外をスローすると、処理が停止します。UDTF を呼び出したクエリは、エラーメッセージを表示して失敗します。

要件の概要¶

UDTF のJavaコードは、次の要件を満たしている必要があります。

• コードは、 出力行クラス を定義する必要があります。

• UDTF ハンドラークラスには、 <出力行クラス> のStream（Streamはjava.util.stream.Streamで定義）を返す、 process という名前のパブリックメソッドが含まれている必要があります。

• UDTF ハンドラークラスは、 getOutputClass という名前のパブリック静的メソッドを定義する必要があります。このメソッドは、 <出力行クラス>.class を返す必要があります。

Javaコードがこれらの要件を満たしていない場合は、 UDTF の作成または実行に失敗します。

• CREATE FUNCTION ステートメントの実行時にセッションにアクティブなウェアハウスがある場合、Snowflakeは関数の作成時に違反を検出します。

• CREATE FUNCTION ステートメントの実行時にセッションにアクティブなウェアハウスがない場合、Snowflakeは関数が呼び出されたときに違反を検出します。

明示的なパーティション分割を使用しない呼び出し¶

次の例は、 UDTF の作成方法を示しています。この例では、各入力の2つのコピーを返し、パーティションごとに1つの追加行を返します。

create function return_two_copies(v varchar)
returns table(output_value varchar)
language java
handler='TestFunction'
target_path='@~/TestFunction.jar'
as
$$

  import java.util.stream.Stream;

  class OutputRow {

    public String output_value;

    public OutputRow(String outputValue) {
      this.output_value = outputValue;
    }

  }


  class TestFunction {

    String myString;

    public TestFunction()  {
      myString = "Created in constructor and output from endPartition()";
    }

    public static Class getOutputClass() {
      return OutputRow.class;
    }

    public Stream<OutputRow> process(String inputValue) {
      // Return two rows with the same value.
      return Stream.of(new OutputRow(inputValue), new OutputRow(inputValue));
    }

    public Stream<OutputRow> endPartition() {
      // Returns the value we initialized in the constructor.
      return Stream.of(new OutputRow(myString));
    }

  }

$$;

この例は、 UDTF を呼び出す方法を示しています。この例を単純にするために、ステートメントは列ではなくリテラル値を渡し、 OVER() 句を省略します。

SELECT output_value
   FROM TABLE(return_two_copies('Input string'));
+-------------------------------------------------------+
| OUTPUT_VALUE                                          |
|-------------------------------------------------------|
| Input string                                          |
| Input string                                          |
| Created in constructor and output from endPartition() |
+-------------------------------------------------------+

この例では、別のテーブルから読み取った値を使用して UDTF を呼び出します。 process メソッドが呼び出されるたびに、 cities_of_interest テーブルにある現在の行の city_name 列から値が渡されます。上記のように、 UDTF は明示的な OVER() 句なしで呼び出されます。

入力のソースとして使用する簡単なテーブルを作成します。

CREATE TABLE cities_of_interest (city_name VARCHAR);
INSERT INTO cities_of_interest (city_name) VALUES
    ('Toronto'),
    ('Warsaw'),
    ('Kyoto');

Java UDTF を呼び出します。

SELECT city_name, output_value
   FROM cities_of_interest,
       TABLE(return_two_copies(city_name))
   ORDER BY city_name, output_value;
+-----------+-------------------------------------------------------+
| CITY_NAME | OUTPUT_VALUE                                          |
|-----------+-------------------------------------------------------|
| Kyoto     | Kyoto                                                 |
| Kyoto     | Kyoto                                                 |
| Toronto   | Toronto                                               |
| Toronto   | Toronto                                               |
| Warsaw    | Warsaw                                                |
| Warsaw    | Warsaw                                                |
| NULL      | Created in constructor and output from endPartition() |
+-----------+-------------------------------------------------------+

JavaScript UDTFs ドキュメントにある例セクション には、テーブルからの値を使用して UDTFs を呼び出すクエリのより複雑な例が含まれています。

ステートメントがパーティション分割を明示的に指定しない場合、Snowflake実行エンジンは 暗黙的なパーティション分割 を使用します。

パーティションが1つしかない場合、 endPartition メソッドは1回だけ呼び出され、クエリの出力には、値 Created in constructor and output from endPartition() を含む1つの行のみが含まれます。ステートメントのさまざまな実行の間に、異なる数のパーティションにデータがグループ化されている場合、 endPartition メソッドは、異なる回数で呼び出され、出力にはこの行の異なる数のコピーが含まれます。

詳細については、 暗黙的なパーティション分割 をご参照ください。

明示的なパーティション分割を使用した呼び出し¶

Java UDTFs は、明示的なパーティション分割を使用して呼び出すこともできます。

SELECT city_name, output_value
   FROM cities_of_interest,
       TABLE(return_two_copies(city_name) OVER (PARTITION BY city_name))
   ORDER BY city_name, output_value;
+-----------+-------------------------------------------------------+
| CITY_NAME | OUTPUT_VALUE                                          |
|-----------+-------------------------------------------------------|
| Kyoto     | Created in constructor and output from endPartition() |
| Kyoto     | Kyoto                                                 |
| Kyoto     | Kyoto                                                 |
| Toronto   | Created in constructor and output from endPartition() |
| Toronto   | Toronto                                               |
| Toronto   | Toronto                                               |
| Warsaw    | Created in constructor and output from endPartition() |
| Warsaw    | Warsaw                                                |
| Warsaw    | Warsaw                                                |
+-----------+-------------------------------------------------------+

SELECT city_name, output_value
   FROM cities_of_interest,
       TABLE(return_two_copies(city_name) OVER (PARTITION BY 1))
   ORDER BY city_name, output_value;
+-----------+-------------------------------------------------------+
| CITY_NAME | OUTPUT_VALUE                                          |
|-----------+-------------------------------------------------------|
| Kyoto     | Kyoto                                                 |
| Kyoto     | Kyoto                                                 |
| Toronto   | Toronto                                               |
| Toronto   | Toronto                                               |
| Warsaw    | Warsaw                                                |
| Warsaw    | Warsaw                                                |
| NULL      | Created in constructor and output from endPartition() |
+-----------+-------------------------------------------------------+

非常に大きな入力（例: 大きなファイル）の処理¶

場合によっては、 UDTF は各入力行を処理するため、非常に大量のメモリを必要とします。たとえば、 UDTF は、メモリに収まらないほど大きいファイルを読み取って処理する場合があります。

UDF または UDTF の大きなファイルを処理するには、 SnowflakeFile または InputStream クラスを使用します。詳細については、 UDF およびプロシージャハンドラーを使用した非構造化データの処理 をご参照ください。