UDF の実行

ユーザー定義関数(UDF)やユーザー定義テーブル関数(UDTF)は、他の関数を実行するのと同じように実行することができます。

UDFs 実行ツール

関数を実行するツールを選択します。

言語

アプローチ

SQL

Snowsight などで SQL コマンドを実行。

SQL SELECT コマンド を実行し、 UDF を実行します。

Snowparkを使用したJava、Python、またはScala

サポートされている言語でローカルにコードを記述し、そのコードをSnowflakeで実行します。

Snowpark APIs を使用するクライアントコードを以下のいずれかの言語で実行します。

コマンドライン

コマンドラインからコマンドを実行して、Snowflakeエンティティを作成および管理します。

Snowflake CLI のコマンドを実行します。

Python

クライアント上で、Snowflakeの管理操作を実行するコードを記述します。

Snowflake Python API を使用するコードを実行します。

RESTful APIs (言語にとらわれない)

RESTful エンドポイントにリクエストを行い、Snowflake エンティティを作成および管理します。

Snowflake REST API を使用した関数作成のリクエストを行います。

SQL で UDF を呼び出します。

一般に、他の関数を呼び出すのと同じ方法で UDF を呼び出します。

UDF に引数がある場合は、それらの引数を名前または位置で指定できます。

たとえば、次の UDF は、3つの引数を受け付けます。

CREATE OR REPLACE FUNCTION udf_concatenate_strings(
    first_arg VARCHAR,
    second_arg VARCHAR,
    third_arg VARCHAR)
  RETURNS VARCHAR
  LANGUAGE SQL
  AS
  $$
    SELECT first_arg || second_arg || third_arg
  $$;

UDF の呼び出し時に、引数を名前で指定できます。

SELECT udf_concatenate_strings(
  first_arg => 'one',
  second_arg => 'two',
  third_arg => 'three');

+--------------------------+
| UDF_CONCATENATE_STRINGS( |
|   FIRST_ARG => 'ONE',    |
|   SECOND_ARG => 'TWO',   |
|   THIRD_ARG => 'THREE')  |
|--------------------------|
| onetwothree              |
+--------------------------+

引数を名前で指定する場合は、引数を特定の順序で指定する必要はありません。

SELECT udf_concatenate_strings(
  third_arg => 'three',
  first_arg => 'one',
  second_arg => 'two');

+--------------------------+
| UDF_CONCATENATE_STRINGS( |
|   THIRD_ARG => 'THREE',  |
|   FIRST_ARG => 'ONE',    |
|   SECOND_ARG => 'TWO')   |
|--------------------------|
| onetwothree              |
+--------------------------+

また、引数を位置で指定することもできます。

SELECT udf_concatenate_strings(
  'one',
  'two',
  'three');

+--------------------------+
| UDF_CONCATENATE_STRINGS( |
|   'ONE',                 |
|   'TWO',                 |
|   'THREE')               |
|--------------------------|
| onetwothree              |
+--------------------------+

また、位置と名前の両方で引数を指定することもできます。

SELECT udf_concatenate_strings(
  'one',
  'two',
  third_arg => 'three');

+--------------------------+
| UDF_CONCATENATE_STRINGS( |
|   'ONE',                 |
|   'TWO',                 |
|   THIRD_ARG => 'THREE')  |
|--------------------------|
| onetwothree              |
+--------------------------+

注釈

  • 位置による引数と名前による引数を混在させる場合、すべての位置指定引数はすべての名前指定引数よりも前に記述する必要があります。

  • 引数を名前で指定する場合は、引数名を二重引用符で囲むことはできません。

オプションの引数を持つ UDF の呼び出し

UDF に オプションの引数 がある場合は、呼び出しの際にオプションの引数を省略できます。オプションの引数それぞれには、引数が省略された場合に使用されるデフォルト値があります。

たとえば、次の UDF には、必須引数が1つ、オプションの引数が2つあります。オプションの引数それぞれには、デフォルト値があります。

CREATE OR REPLACE FUNCTION build_string_udf(
    word VARCHAR,
    prefix VARCHAR DEFAULT 'pre-',
    suffix VARCHAR DEFAULT '-post'
  )
  RETURNS VARCHAR
  AS
  $$
    SELECT prefix || word || suffix
  $$
  ;

オプションの引数は省略可能です。引数を省略すると、その引数のデフォルト値が使用されます。

SELECT build_string_udf('hello');

+---------------------------+
| BUILD_STRING_UDF('HELLO') |
|---------------------------|
| pre-hello-post            |
+---------------------------+

SELECT build_string_udf('hello', 'before-');

+--------------------------------------+
| BUILD_STRING_UDF('HELLO', 'BEFORE-') |
|--------------------------------------|
| before-hello-post                    |
+--------------------------------------+

オプションの引数を省略し、署名で省略された引数の後に表示される別のオプションの引数を指定する必要がある場合は、位置引数ではなく名前付き引数を使用します。

たとえば、 prefix 引数を省略し、 suffix 引数を指定するとします。suffix 引数は署名の prefix の後に表示されるため、引数は名前で指定する必要があります。

SELECT build_string_udf(word => 'hello', suffix => '-after');

+-------------------------------------------------------+
| BUILD_STRING_UDF(WORD => 'HELLO', SUFFIX => '-AFTER') |
|-------------------------------------------------------|
| pre-hello-after                                       |
+-------------------------------------------------------+

UDTF の呼び出し

テーブル関数を呼び出すのと同じ方法で UDTF を呼び出すことができます。クエリの FROM 句で UDTF を呼び出す場合は、 組み込まれたテーブル関数の呼び出し 時のように、 TABLE キーワードに続く括弧内に UDTF の名前と引数を指定します。

つまり、 UDTF を呼び出すときは、 TABLE キーワードに次のような形式を使用します。

SELECT ...
  FROM TABLE ( udtf_name (udtf_arguments) )

次の例のコードは、引数 '2021-01-16'::DATE に DATE リテラルを指定して、 my_java_udtf テーブル関数を呼び出します。

SELECT ...
  FROM TABLE(my_java_udtf('2021-01-16'::DATE));

テーブル関数の引数は、リテラルだけでなく、式にすることもできます。たとえば、テーブル関数は、テーブルの列を使用して呼び出すことができます。例のセクション を含め、いくつかの例を以下に示します。

UDFs を呼び出す場合と同様に、引数は名前または位置で指定できます。

一般的なテーブル関数の詳細については、 テーブル関数 をご参照ください。

注釈

CREATE TABLE ステートメントの DEFAULT 句内で UDF を呼び出すことはできません。

UDTF への入力としてのテーブルまたは UDTF の使用

テーブル関数への入力は、 テーブル関数への入力としてテーブルを使用 に記載されているように、テーブルまたは別の UDTF から取得できます。

以下の例は、テーブルを使用して、 UDTF split_file_into_words に入力を提供する方法を示しています。

create table file_names (file_name varchar);
insert into file_names (file_name) values ('sample.txt'),
                                          ('sample_2.txt');

select f.file_name, w.word
   from file_names as f, table(split_file_into_words(f.file_name)) as w;

出力は、次に類似したものになります。

+-------------------+------------+
| FILE_NAME         | WORD       |
+-------------------+------------+
| sample_data.txt   | some       |
| sample_data.txt   | words      |
| sample_data_2.txt | additional |
| sample_data_2.txt | words      |
+-------------------+------------+

UDTF の IMPORTS 句は、 UDTF に渡される 各 ファイルの名前とパスを指定する必要があります。例:

create function split_file_into_words(inputFileName string)
    ...
    imports = ('@inline_jars/sample.txt', '@inline_jars/sample_2.txt')
    ...

UDTF がファイルを読み取る前に、各ファイルは、すでにステージ（この場合は @inline_jars という名前のステージ）にコピーされている必要があります。

別の UDTF への入力として UDTF を使用する例については、 JavaScript UDTF ドキュメントの 入力としてテーブル値とその他の UDTFs を使用した拡張例 をご参照ください。

テーブル関数とパーティション

行がテーブル関数に渡される前に、行を パーティション にグループ化できます。パーティション分割には2つの主な利点があります。

  • パーティション分割は、Snowflakeがワークロードを分割して並列化を改善し、パフォーマンスを向上させられるようにします。

  • パーティション分割により、Snowflakeは共通の特性を持つすべての行をグループとして処理できます。個々の行だけでなく、グループ内のすべての行に基づく結果を返すことができます。

たとえば、株価データを株式ごとに1つのグループに分割できます。個々の会社の株価すべてを同時に分析しながら、各会社の株価を他の会社とは分離して分析することができます。

データは、明示的または暗黙的に分割できます。

明示的なパーティション分割

複数のグループへの明示的なパーティション分割

次のステートメントは、個々のパーティションで my_udtf という名前の UDTF を呼び出します。各パーティションには、 PARTITION BY 式が同じ値（例: 同じ会社または銘柄記号）と評価されるすべての行が含まれます。

SELECT *
    FROM stocks_table AS st,
         TABLE(my_udtf(st.symbol, st.transaction_date, st.price) OVER (PARTITION BY st.symbol))

単一グループへの明示的なパーティション分割

次のステートメントは、1つのパーティションで my_udtf という名前の UDTF を呼び出します。PARTITION BY <定数> 句（この場合は PARTITION BY 1）は、すべての行を同じパーティションに配置します。

SELECT *
    FROM stocks_table AS st,
         TABLE(my_udtf(st.symbol, st.transaction_date, st.price) OVER (PARTITION BY 1))

より包括的で現実的な例については、 クエリでJava UDTFs を呼び出す例、特に 単一のパーティション というタイトルのサブセクションをご参照ください。

パーティションの行の並べ替え

指定した順序で各パーティションの行を処理するには、 ORDER BY 句を含めます。これは、行を指定された順序で行ごとのハンドラーメソッドに渡すよう、Snowflakeに指示します。

たとえば、株価の移動平均を経時的に計算する場合は、タイムスタンプの順に株価を並べます（また、銘柄記号ごとにパーティションします）。次の例は、これを実行する方法を示しています。

SELECT *
     FROM stocks_table AS st,
          TABLE(my_udtf(st.symbol, st.transaction_date, st.price) OVER (PARTITION BY st.symbol ORDER BY st.transaction_date))

OVER 句には、 PARTITION BY 句がない場合でも ORDER BY 句を含めることができます。

OVER 句内に ORDER BY 句を含めることは、クエリの最も外側のレベルに ORDER BY 句を配置することと同じではないことに注意してください。クエリ結果全体を並べ替える場合は、個別の ORDER BY 句が必要です。例:

SELECT *
    FROM stocks_table AS st,
         TABLE(my_udtf(st.symbol, st.transaction_date, st.price) OVER (PARTITION BY st.symbol ORDER BY st.transaction_date))
    ORDER BY st.symbol, st.transaction_date, st.transaction_time;

明示的なパーティション分割の使用上の注意

PARTITION BY 句で UDTF を使用する場合は、 PARTITION BY 句に一般式ではなく、列参照またはリテラルを使用する必要があります。たとえば、次のコマンドは許可されて いません。

SELECT * FROM udtf_table, TABLE(my_func(col1) OVER (PARTITION BY udtf_table.col2 * 2));   -- NO!
暗黙的なパーティション分割

テーブル関数が PARTITION BY 句を使用して行を明示的にパーティションしない場合、Snowflakeは通常、並列処理を使用するために行を暗黙的に分割して、パフォーマンスを向上させます。

パーティションの数は通常、関数を処理するウェアハウスのサイズや入力関係のカーディナリティなどの要因に基づいています。行は通常、行の物理的な場所（例: マイクロパーティションによる）などの要因に基づいて特定のパーティションに割り当てられるため、パーティションのグループ化には意味がありません。