カテゴリ:

ユーザー定義関数、外部関数、およびストアドプロシージャ用の DDL

CREATE FUNCTION

新しい UDF (ユーザー定義関数) を作成します。 UDF には SQL 式または JavaScript コードを含めることができ、スカラーまたは表形式の結果を返すことができます。

こちらもご参照ください:

ALTER FUNCTION , SHOW USER FUNCTIONS

構文

CREATE [ OR REPLACE ] [ SECURE ] FUNCTION <name> ( [ <arg_name> <arg_data_type> ] [ , ... ] )
  RETURNS { <result_data_type> | TABLE ( <col_name> <col_data_type> [ , ... ] ) }
  [ [ NOT ] NULL ]
  [ LANGUAGE JAVASCRIPT ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ VOLATILE | IMMUTABLE ]
  [ COMMENT = '<string_literal>' ]
  AS '<function_definition>'

必須パラメーター

名前 ( [ 引数名 引数データ型 ] [ , ... ] )

UDFの識別子(およびオプションで1つ以上の引数/入力)を指定します。 UDFs は名前と引数のタイプによって識別および解決されるため、 UDF が作成されるスキーマに対して識別子は一意である必要はありません。

ただし、識別子はアルファベットで始まる必要があり、識別子文字列全体が二重引用符で囲まれていない限り、スペースや特殊文字を含めることはできません(例: "My object")。二重引用符で囲まれた識別子も大文字と小文字が区別されます。

詳細については、 識別子の要件 をご参照ください。

RETURNS ...

UDFタイプを決定する UDF によって返される結果を指定します。

  • 結果データ型:指定されたデータ型の単一の値を返すスカラー UDF を作成します。

  • TABLE ( 列名 列データ型 , ... ):指定したテーブル列と列タイプで表形式の結果を返すテーブル UDF を作成します。

AS 関数定義

UDFによって実行されるコードを定義します。内容は、作成される UDF のタイプによって異なります。

  • SQL UDF:有効な SQL 式。例など、 SQL UDFsの詳細については、 UDFsの概要 をご参照ください。

  • JavaScript UDF:有効な JavaScript。例など、 JavaScript UDFsの詳細については、 JavaScript UDFs をご参照ください。

詳細については、 使用上の注意 (このトピック)をご参照ください。

オプションのパラメーター

SECURE

関数が安全であることを指定します。セキュア関数の詳細については、 安全な UDFs をご参照ください。

LANGUAGE JAVASCRIPT

関数定義 に JavaScript コードが含まれることを指定します。それ以外の場合、 関数定義 には SQL 式が含まれている必要があります。

デフォルト:値なし(つまり SQL UDF が作成されます)

CALLED ON NULL INPUT または . RETURNS NULL ON NULL INPUT | STRICT

null入力で呼び出されたときの UDF の動作を指定します。入力がnullの場合は常にnullを返すシステム定義関数とは対照的に、 UDFs はnull入力を処理でき、入力がnullの場合でもnull以外の値を返します。

  • CALLED ON NULL INPUT 常にnull入力で UDF を呼び出します。そのような値を適切に処理するのは UDF 次第です。

  • RETURNS NULL ON NULL INPUT (またはその同義語 STRICT)は、入力がnullの場合、 UDF を呼び出しません。代わりに、その行に対して常にnull値が返されます。 UDF はnull以外の入力に対してもnullを返す場合があります。

デフォルト: CALLED ON NULL INPUT

VOLATILE | IMMUTABLE

結果を返すときの UDF の動作を指定します。

  • VOLATILE:UDF は、同じ入力でも(例えば、非決定性とステートフルネスのため)、異なる行に対して異なる値を返す場合があります。

  • IMMUTABLE:UDF は、関が同じ入力で呼び出された場合、常に同じ結果を返すと想定しています。この保証はチェックされません。同じ入力に対して異なる値を返す UDF に IMMUTABLE を指定すると、未定義の動作が発生します。

デフォルト: VOLATILE

COMMENT = '文字列リテラル'

SHOW FUNCTIONS および SHOW USER FUNCTIONS 出力の DESCRIPTION 列に表示される UDFのコメントを指定します。

デフォルト: user-defined function

使用上の注意

  • 1つの単一引用符以外の文字シーケンスを使用して、 UDFの本文を区切ることができます。例えば、2つのドル記号(「$$」)のシーケンスを使用できます。以下のいくつかの例では、区切り文字として「$$」を使用しています。

  • 関数の本体の区切り文字が一重引用符文字である場合、 関数定義 (例:文字列リテラル)内の一重引用符は一重引用符でエスケープする 必要があります

  • 関数定義 にはサイズ制限があります。最大許容サイズは変更される可能性があります。

  • Snowflakeは UDF 作成時に JavaScript コードを検証しません(つまり、コードが有効かどうかに関係なく UDF の作成は成功します)。コードが有効でない場合、クエリ時に UDF が呼び出されたときにエラーが返されます。詳細については、 JavaScript UDFs をご参照ください。

  • オプションの [ [ NOT ] NULL ] 句は、関数が NULL 値を返すことができるか、または NON-NULL 値のみを返す必要があるかを示します。デフォルトは NULLです。つまり、関数は NULLを返すことができます。

    注釈

    現在、 SQL UDFsではなく JavaScript UDFsにの みNOT NULL 句が適用されています。 NOT NULL として宣言されたSQL UDFs は、 NULL値を返すことができます。関数のコードに NULL 値が返されないように記述されていない限り、 SQL UDFs に NOT NULL を使用しないことをSnowflakeはお勧めします。

数学定数piのハードコーディングされた近似値を返す単純な SQL スカラー UDF を作成します。

CREATE FUNCTION pi_udf()
  RETURNS FLOAT
  AS '3.141592654::FLOAT'
  ;

ハードコードされた値を返す単純な SQL テーブル UDF を作成します。

CREATE FUNCTION simple_table_function ()
  RETURNS TABLE (x INTEGER, y INTEGER)
  AS
  $$
    SELECT 1, 2
    UNION ALL
    SELECT 3, 4
  $$
  ;
SELECT * FROM TABLE(simple_table_function());

出力:

+---+---+
| X | Y |
|---+---|
| 1 | 2 |
| 3 | 4 |
+---+---+

クエリの結果を返す get_countries_for_user という名前の SQL テーブル UDF を作成します。

CREATE OR REPLACE FUNCTION get_countries_for_user ( id number )
  RETURNS TABLE (country_code char, country_name varchar)
  AS 'select distinct c.country_code, c.country_name
      from user_addresses a, countries c
      where a.user_id = id
      and c.country_code = a.country_code';

js_factorial という名前の JavaScript UDF を作成します。

CREATE OR REPLACE FUNCTION js_factorial(d double)
  RETURNS double
  LANGUAGE JAVASCRIPT
  STRICT
  AS '
  if (D <= 0) {
    return 1;
  } else {
    var result = 1;
    for (var i = 2; i <= D; i++) {
      result = result * i;
    }
    return result;
  }
  ';