CREATE FUNCTION¶

新しい UDF （ユーザー定義関数）を作成します。この関数は、スカラー結果（UDFとして）または表形式の結果（UDTFとして）のいずれかを返すことができます。

UDFを作成するときは、サポートされている言語の1つでコードが記述されているハンドラーを指定します。ハンドラーの言語に応じて、ハンドラーソースコードをCREATE FUNCTIONステートメントにインラインするか、ハンドラーがプリコンパイルされている、またはステージのソースコードであるハンドラーの場所をCREATE FUNCTIONから参照することができます。

次のテーブルに、サポートされている各言語と、そのコードを CREATE FUNCTION でインラインに保持できるか、ステージに保持できるかをリストします。詳細については、ハンドラーコードのインラインまたはステージ上での保持をご参照ください。

言語	ハンドラーの場所
Java	インラインまたはステージング
JavaScript	インライン
Python	インラインまたはステージング
Scala	インラインまたはステージング
SQL	インライン

こちらもご参照ください。: ALTER FUNCTION、 DROP FUNCTION、 SHOW USER FUNCTIONS、 DESCRIBE FUNCTION

構文¶

CREATE FUNCTION の構文は、 UDF ハンドラーとして使用している言語によって異なります。

Javaハンドラー¶

ソースコードがインラインの場合は、以下の構文を使用します。

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION [ IF NOT EXISTS ] <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( <col_name> <col_data_type> [ , ... ] ) }
  [ [ NOT ] NULL ]
  LANGUAGE JAVA
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  [ RUNTIME_VERSION = <java_jdk_version> ]
  [ COMMENT = '<string_literal>' ]
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [ , ... ] ) ]
  [ PACKAGES = ( '<package_name_and_version>' [ , ... ] ) ]
  HANDLER = '<path_to_method>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
  [ TARGET_PATH = '<stage_path_and_file_name_to_write>' ]
  AS '<function_definition>'

Copy

ハンドラーコードがステージで参照される場合（JAR 内など）は、次の構文を使用します。

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION [ IF NOT EXISTS ] <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( <col_name> <col_data_type> [ , ... ] ) }
  [ [ NOT ] NULL ]
  LANGUAGE JAVA
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  [ RUNTIME_VERSION = <java_jdk_version> ]
  [ COMMENT = '<string_literal>' ]
  IMPORTS = ( '<stage_path_and_file_name_to_read>' [ , ... ] )
  HANDLER = '<path_to_method>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]

Copy

JavaScript ハンドラー¶

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  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>'

Copy

Pythonハンドラー¶

ソースコードがインラインの場合は、以下の構文を使用します。

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION [ IF NOT EXISTS ] <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( <col_name> <col_data_type> [ , ... ] ) }
  [ [ NOT ] NULL ]
  LANGUAGE PYTHON
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  RUNTIME_VERSION = <python_version>
  [ COMMENT = '<string_literal>' ]
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [ , ... ] ) ]
  [ PACKAGES = ( '<package_name>[==<version>]' [ , ... ] ) ]
  HANDLER = '<function_name>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
  AS '<function_definition>'

Copy

ハンドラーコードがステージで参照される場合（モジュール内など）は、次の構文を使用します。

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION [ IF NOT EXISTS ] <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( <col_name> <col_data_type> [ , ... ] ) }
  [ [ NOT ] NULL ]
  LANGUAGE PYTHON
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  RUNTIME_VERSION = <python_version>
  [ COMMENT = '<string_literal>' ]
  IMPORTS = ( '<stage_path_and_file_name_to_read>' [ , ... ] )
  [ PACKAGES = ( '<package_name>[==<version>]' [ , ... ] ) ]
  HANDLER = '<module_file_name>.<function_name>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]

Copy

Scalaハンドラー¶

ソースコードがインラインの場合は、以下の構文を使用します。

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION [ IF NOT EXISTS ] <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS <result_data_type>
  [ [ NOT ] NULL ]
  LANGUAGE SCALA
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  [ RUNTIME_VERSION = <scala_version> ]
  [ COMMENT = '<string_literal>' ]
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [ , ... ] ) ]
  [ PACKAGES = ( '<package_name_and_version>' [ , ... ] ) ]
  HANDLER = '<path_to_method>'
  [ TARGET_PATH = '<stage_path_and_file_name_to_write>' ]
  AS '<function_definition>'

Copy

ハンドラーコードがステージで参照される場合（JAR 内など）は、次の構文を使用します。

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION [ IF NOT EXISTS ] <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS <result_data_type>
  [ [ NOT ] NULL ]
  LANGUAGE SCALA
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  [ RUNTIME_VERSION = <scala_version> ]
  [ COMMENT = '<string_literal>' ]
  IMPORTS = ( '<stage_path_and_file_name_to_read>' [ , ... ] )
  HANDLER = '<path_to_method>'

Copy

SQL ハンドラー¶

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( <col_name> <col_data_type> [ , ... ] ) }
  [ [ NOT ] NULL ]
  [ { VOLATILE | IMMUTABLE } ]
  [ MEMOIZABLE ]
  [ COMMENT = '<string_literal>' ]
  AS '<function_definition>'

Copy

必須パラメーター¶

すべての言語¶

name ( [ arg_name arg_data_type [ DEFAULT default_value ] ] [ , ... ] )

識別子（name）、入力引数、および UDF のオプション引数のデフォルト値を指定します。

識別子用:
- UDFs は名前と引数の型の組み合わせによって識別および解決されるため、識別子は、関数が作成されるスキーマに対して一意である必要はありません。
- 識別子はアルファベットで始まる必要があり、識別子の文字列全体が二重引用符で囲まれている場合を除き、スペースや特殊文字を含めることはできません（例: "My object"）。二重引用符で囲まれた識別子も大文字と小文字が区別されます。識別子の要件をご参照ください。
入力引数の場合、
- arg_name には、入力引数の名前を指定します。
- arg_data_type には、使用しているハンドラー言語に対応するSnowflakeデータ型を使用します。
  - Javaハンドラーについては、 SQL-Javaデータ型マッピングをご参照ください。
  - JavaScript ハンドラーについては、 SQL および JavaScript データ型マッピングをご参照ください。
  - Pythonハンドラーについては、 SQL-Pythonデータ型マッピングをご参照ください。
  - Scalaハンドラーについては、 SQL-Scalaデータ型マッピングをご参照ください。
- 引数が省略可能であることを示すには、 DEFAULT default_value を使用して引数のデフォルト値を指定します。デフォルト値には、リテラルまたは式を使用できます。
  
  オプションの引数を指定する場合は、必須引数の後に配置する必要があります。
  
  関数にオプションの引数がある場合は、同じ名前で異なる署名を持つ関数を追加で定義することはできません。
  
  詳細については、引数をオプションに指定するをご参照ください。

RETURNS ...

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

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

注釈

Java、Python、またはScalaで記述された UDF ハンドラーの場合、 result_data_type は、ハンドラー言語に対応する次のテーブルの SQL Data Type 列になければなりません。

SQL-Java型マッピングテーブル

SQL-Python型マッピングテーブル

SQL-Scala型マッピングテーブル

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

注釈

Scala UDFs の場合、戻り型 TABLE はサポートされていません。

AS function_definition

UDFが呼び出されたときに実行されるハンドラーコードを定義します。 function_definition 値は、ハンドラーでサポートされている言語の1つのソースコードである必要があります。コードは次の場合があります。

Java。詳細については、 Java UDFs の紹介をご参照ください。
JavaScript。詳細については、 JavaScript UDFs の紹介をご参照ください。
Python。詳細については、 Python UDFsの紹介をご参照ください。
Scala。詳細については、 Scala UDFs の紹介をご参照ください。
SQL 式。詳細については、 SQL UDFs の紹介をご参照ください。

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

注釈

UDF ハンドラーコードが IMPORTS 句を含むステージで参照される場合、 AS 句は必要ありません。

Java¶

LANGUAGE JAVA

コードはJava言語であることを指定します。

RUNTIME_VERSION = java_jdk_version

使用するJava JDK ランタイムバージョンを指定します。サポートされているJavaのバージョンは次のとおりです。

11.x

RUNTIME_VERSION が設定されていない場合は、Java JDK 11が使用されます。

IMPORTS = ( 'stage_path_and_file_name_to_read' [ , ... ] )

インポートするファイルの場所（ステージ）、パス、および名前。

ファイルは、 JAR ファイルまたは別の型のファイルにすることができます。

ファイルが JAR ファイルの場合は、1個以上の.classファイルと0個以上のリソースファイルを含めることができます。

JNI （Java Native Interface）はサポートされていません。Snowflakeは、（Javaバイトコードではなく）ネイティブコードを含むライブラリのロードを禁止しています。

Java UDFs は、 JAR 以外のファイルも読み取ることができます。例については、 IMPORTS で静的に指定されたファイルの読み取りをご参照ください。

ファイル（JAR ファイルまたは他のファイル）をステージにコピーする場合、 PUT コマンドは名前付き内部ステージへのファイルのコピーをサポートしており、通常は JAR ファイルをステージに移動する最も簡単な方法であるため、Snowflakeは PUT 名前付き内部ステージを使用することをお勧めします。

外部ステージは許可されていますが、 PUT ではサポートされていません。

IMPORTS 句の各ファイルは、ファイルが異なるサブディレクトリまたは異なるステージにある場合でも、一意の名前を持っている必要があります。

IMPORTS 句と TARGET_PATH 句の両方が存在する場合、ファイルが異なるサブディレクトリまたは異なるステージにあっても、 TARGET_PATH 句のファイル名は IMPORTS 句の各ファイル名とは異なる必要があります。

TARGET_PATH が既存のファイルと一致する場合、Snowflakeはエラーを返します。 TARGET_PATH を使用して既存のファイルを上書きすることはできません。

ハンドラーがステージにある UDF の場合は、 UDF を含む JAR ファイルの場所を指定するために IMPORTS 句が必要です。

ハンドラーコードがインラインの UDF の場合、 IMPORTS 句は、インライン UDF によって、ライブラリやテキストファイルなどの他のファイルにアクセスする必要がある場合にのみ必要です。

SnowparkパッケージなどのSnowflakeシステムパッケージの場合、 JAR ファイルを IMPORTS で指定するのではなく、 PACKAGES 句でパッケージを指定できます。その場合は、パッケージ JAR ファイルを IMPORTS 値に含める必要はありません。

インラインJava

AS function_definition: インラインJava UDFs には、関数定義が必要です。

HANDLER = handler_name

ハンドラーメソッドまたはクラスの名前。

ハンドラーがスカラー UDF 用であり、表形式ではない値を返す場合、 HANDLER 値は MyClass.myMethod のような形式のメソッド名である必要があります。
ハンドラーが表形式のUDF用である場合、HANDLER値はハンドラークラスの名前である必要があります。

JavaScript¶

LANGUAGE JAVASCRIPT: コードは JavaScript 言語であることを指定します。

Python¶

LANGUAGE PYTHON

コードはPython言語であることを指定します。

RUNTIME_VERSION = python_version

使用するPythonのバージョンを指定します。サポートされているPythonのバージョンは次のとおりです。

3.8
3.9
3.10
3.11

IMPORTS = ( 'stage_path_and_file_name_to_read' [ , ... ] )

インポートするファイルの場所（ステージ）、パス、および名前。

ファイルは、 .py ファイルまたは別の型のファイルにすることができます。

Python UDFsは、テキストファイルなどのPython以外のファイルも読み取ることができます。例については、ファイルの読み取りをご参照ください。

ファイルをステージにコピーする場合、 PUT コマンドは名前付き内部ステージへのファイルのコピーをサポートしており、通常は PUT コマンドはファイルをステージに移動する最も簡単な方法であるため、Snowflakeは名前付き内部ステージを使用することをお勧めします。

外部ステージは許可されていますが、 PUT ではサポートされていません。

IMPORTS 句の各ファイルは、ファイルが異なるサブディレクトリまたは異なるステージにある場合でも、一意の名前を持っている必要があります。

ハンドラーコードがステージに格納されている場合は、 IMPORTS 句を使用してハンドラーコードの場所を指定する必要があります。

インラインPython UDFの場合、 IMPORTS 句はUDFハンドラーがライブラリやテキストファイルなどの他のファイルにアクセスする必要がある場合にのみ必要です。

numpy などのSnowflakeシステムに含まれるパッケージの場合は、 PACKAGES 句のみでパッケージを指定し、パッケージのソースを IMPORTS 値として省略できます。

HANDLER = handler_name

ハンドラー関数またはクラスの名前。

ハンドラーがスカラーUDF用であり、表形式ではない値を返す場合、HANDLER値は関数名である必要があります。ハンドラーコードがCREATE FUNCTIONステートメントにインラインの場合、関数名のみを使用できます。ハンドラーコードがステージで参照される場合、この値は次の形式のようにモジュール名で修飾する必要があります: my_module.my_function。
ハンドラーが表形式のUDF用である場合、HANDLER値はハンドラークラスの名前である必要があります。

Scala¶

LANGUAGE SCALA

コードにはScala言語を指定します。

RUNTIME_VERSION = scala_version

使用するScalaランタイムのバージョンを指定します。サポートされているScalaのバージョンは次のとおりです。

2.12

RUNTIME_VERSION が設定されていない場合は、Scala 2.12が使用されます。

IMPORTS = ( 'stage_path_and_file_name_to_read' [ , ... ] )

場所（ステージ）、パス、および JAR またはその他の種類のファイルなど、インポートするファイルの名前。

JAR ファイルには、ハンドラーの依存関係ライブラリが含まれている場合があります。これには、1個以上の.classファイルと0個以上のリソースファイルが含まれている可能性があります。

JNI （Java Native Interface）はサポートされていません。Snowflakeは、（Javaバイトコードではなく）ネイティブコードを含むライブラリのロードを禁止しています。
JAR 以外のファイルは、ハンドラーコードによって読み取られるファイルである可能性があります。例については、 IMPORTS で静的に指定されたファイルの読み取りをご参照ください。

ファイルをステージにコピーする場合、 PUT コマンドは名前付き内部ステージへのファイルのコピーをサポートしており、通常 PUT コマンドは JAR ファイルをステージに移動する最も簡単な方法であるため、Snowflakeは名前付き内部ステージを使用することをお勧めします。外部ステージは許可されていますが、 PUT ではサポートされていません。

IMPORTS 句の各ファイルは、ファイルが異なるステージサブディレクトリまたは異なるステージにある場合でも、一意の名前を持っている必要があります。

IMPORTS 句と TARGET_PATH 句の両方が存在する場合、ファイルが異なるステージサブディレクトリまたは異なるステージにあっても、 TARGET_PATH 句のファイル名は IMPORTS 句でリストされたいずれのファイル名とも異なっている必要があります。

ハンドラーがステージにある UDF の場合は、 UDF を含む JAR ファイルの場所を指定するために IMPORTS 句が必要です。

インラインScala

AS function_definition: UDFs インラインScalaハンドラーコードを使用するには、関数定義が必要です。

HANDLER = handler_name

ハンドラーメソッドまたはクラスの名前。

ハンドラーがスカラー UDF 用であり、表形式ではない値を返す場合、 HANDLER 値は MyClass.myMethod のような形式のメソッド名である必要があります。

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

すべての言語¶

SECURE

関数が安全であることを指定します。セキュア関数の詳細については、セキュア UDFs とストアドプロシージャの使用による機密情報の保護をご参照ください。

{ TEMP | TEMPORARY }

関数を作成したセッションの間だけ持続するように指定します。セッション終了時に仮関数をドロップします。

デフォルト：値なし。関数が TEMPORARY として宣言されていない場合、その関数は永続的です。

スキーマに既存の関数と同じ名前の仮ユーザー定義関数を作成することはできません。

[ [ NOT ] NULL ]

関数は NULL 値を返すことができるか、 NON-NULL 値のみを返す必要があるかを指定します。デフォルトは NULL です（つまり、関数は NULL を返すことができます）。

注釈

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

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を返す場合があります。

注釈

SQLUDFs では RETURNS NULL ON NULL INPUT （STRICT）はサポートされていませんSQLUDFs は事実上 CALLED ON NULL INPUT を使用します。SQL UDFs では、NULLの入力値を処理する必要があります。

デフォルト: CALLED ON NULL INPUT

{ VOLATILE | IMMUTABLE }

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

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

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

デフォルト: VOLATILE

COMMENT = 'string_literal'

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

デフォルト: user-defined function

COPY GRANTS

CREATE OR REPLACE FUNCTION を使用して新しい関数を作成するときに、元の関数のアクセス権限を保持することを指定します。

このパラメーターは、既存の関数から新しい関数に、 OWNERSHIP を除くすべての権限をコピーします。新しい関数は、スキーマ内のオブジェクト型に定義された将来の付与を継承します。デフォルトでは、 CREATE FUNCTION ステートメントを実行するロールが新しい関数を所有します。

注意:

データ共有では、既存の関数が別のアカウントと共有されていた場合に、代替関数も共有されます。
置換関数の SHOW GRANTS 出力には、ステートメントが実行されたときの現在のタイムスタンプとともに、コピーされた権限の被付与者が CREATE FUNCTION ステートメントを実行したロールとしてリストされます。
付与をコピーする操作は、 CREATE FUNCTION コマンドで（つまり、同じトランザクション内で）アトミックに発生します。

Java¶

PACKAGES = ( 'package_name_and_version' [ , ... ] )

依存関係として必要なSnowflakeシステムパッケージの名前とバージョン番号。値は、 package_name:version_number の形式にする必要があります。ここで、 package_name は、 snowflake_domain:package です。Snowflakeにシステムで利用可能な最新バージョンを使用させるために、バージョン番号として latest を指定できることに注意してください。

例:

-- Use version 1.2.0 of the Snowpark package.
PACKAGES=('com.snowflake:snowpark:1.2.0')

-- Use the latest version of the Snowpark package.
PACKAGES=('com.snowflake:snowpark:latest')

Copy

Snowflakeで次の SQL を実行すると、サポートされているシステムパッケージのリストを見つけることができます。

SELECT * FROM INFORMATION_SCHEMA.PACKAGES WHERE LANGUAGE = 'java';

Copy

PACKAGES で指定する依存関係の場合は、 IMPORTS 句でその JAR ファイルを指定する必要はありません。

インラインJava

TARGET_PATH = stage_path_and_file_name_to_write

TARGET_PATH 句は、 function_definition で指定されたソースコードをコンパイルした後、Snowflakeがコンパイルされたコード（JAR ファイル）を書き込む場所を指定します。

この句が含まれている場合、ユーザーは JAR ファイルが不要になったとき（通常はJava UDF がドロップされたとき）に手動で削除する必要があります。

この句を省略すると、Snowflakeはコードが必要になるたびにソースコードを再コンパイルします。JAR ファイルは永続的には保存されないため、ユーザーは JAR ファイルをクリーンアップする必要はありません。

TARGET_PATH が既存のファイルと一致する場合、Snowflakeはエラーを返します。 TARGET_PATH を使用して既存のファイルを上書きすることはできません。

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

この関数のハンドラーコードが外部ネットワークにアクセスするために必要な外部アクセス統合の名前。

外部アクセス統合には、ネットワークルールとシークレットが含まれ、ハンドラーコードが外部 REST API のような外部ネットワークにリクエストするために必要な外部ロケーションと認証情報（ある場合）を指定します。

詳細については、外部ネットワークアクセスの概要をご参照ください。

SECRETS = ( 'secret_variable_name' = secret_name [ , ... ] )

シークレットの名前を変数に代入し、ハンドラーコードでシークレットから情報を取得する際に、変数を使用してシークレットを参照できるようにします。

このパラメーターの値は、次の部分からなる代入式のカンマ区切りのリストです。

secret_name を、外部アクセス統合の ALLOWED_AUTHENTICATION_SECRETS パラメーター値で指定されたシークレットの名前にします。その外部アクセス統合の名前は、この CREATE FUNCTION 呼び出しの EXTERNAL_ACCESS_INTEGRATIONS パラメーターの値として指定する必要があります。

EXTERNAL_ACCESS_INTEGRATIONS パラメーターで指定された統合にもシークレットが含まれていない SECRETS 値を指定すると、エラーが発生します。
'secret_variable_name' を、シークレットから情報を取得する際にハンドラーコードで使用する変数にします。

例などの詳細については、関数またはプロシージャでの外部アクセス統合の使用をご参照ください。

Python¶

PACKAGES = ( 'package_name_and_version' [ , ... ] )

依存関係として必要なパッケージの名前とバージョン番号。値は、 package_name==version_number の形式にする必要があります。バージョン番号を省略すると、Snowflakeはシステムで利用可能な最新のパッケージを使用します。

例:

-- Use version 1.2.2 of the NumPy package.
PACKAGES=('numpy==1.2.2')

-- Use the latest version of the NumPy package.
PACKAGES=('numpy')

Copy

Snowflakeで次の SQL を実行すると、サポートされているシステムパッケージのリストを見つけることができます。

SELECT * FROM INFORMATION_SCHEMA.PACKAGES WHERE LANGUAGE = 'python';

Copy

含まれているパッケージの詳細については、サードパーティパッケージの使用をご参照ください。

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

この関数のハンドラーコードが外部ネットワークにアクセスするために必要な外部アクセス統合の名前。

詳細については、外部ネットワークアクセスの概要をご参照ください。

SECRETS = ( 'secret_variable_name' = secret_name [ , ... ])

このパラメーターの値は、次の部分からなる代入式のカンマ区切りのリストです。

secret_name を、外部アクセス統合の ALLOWED_AUTHENTICATION_SECRETS パラメーター値で指定されたシークレットの名前にします。その外部アクセス統合の名前は、この CREATE FUNCTION 呼び出しの EXTERNAL_ACCESS_INTEGRATIONS パラメーターの値として指定する必要があります。

EXTERNAL_ACCESS_INTEGRATIONS パラメーターで指定された統合にもシークレットが含まれていない SECRETS 値を指定すると、エラーが発生します。
'secret_variable_name' を、シークレットから情報を取得する際にハンドラーコードで使用する変数にします。

例などの詳細については、関数またはプロシージャでの外部アクセス統合の使用をご参照ください。

SQL¶

MEMOIZABLE

関数がメモ化可能であることを指定します。

詳細については、メモ化可能 UDFs をご参照ください。

Scala¶

PACKAGES = ( 'package_name_and_version' [ , ... ] )

例:

-- Use version 1.7.0 of the Snowpark package.
PACKAGES=('com.snowflake:snowpark:1.7.0')

-- Use the latest version of the Snowpark package.
PACKAGES=('com.snowflake:snowpark:latest')

Copy

Snowflakeで次の SQL を実行すると、サポートされているシステムパッケージのリストを見つけることができます。

SELECT * FROM INFORMATION_SCHEMA.PACKAGES WHERE LANGUAGE = 'scala';

Copy

PACKAGES で指定する依存関係の場合は、 IMPORTS 句でその JAR ファイルを指定する必要はありません。

インラインScala

TARGET_PATH = stage_path_and_file_name_to_write

この句が含まれている場合は、不要になったとき（通常は UDF がドロップされたとき）に JAR ファイルを手動で削除する必要があります。

この句を省略すると、Snowflakeはコードが必要になるたびにソースコードを再コンパイルします。JAR ファイルは永続的には格納されないため、 JAR ファイルをクリーンアップする必要はありません。

TARGET_PATH が既存のファイルと一致する場合、Snowflakeはエラーを返します。 TARGET_PATH を使用して既存のファイルを上書きすることはできません。

アクセス制御の要件¶

この SQL コマンドの実行に使用されるロールには、少なくとも次の権限が必要です。

権限	オブジェクト	メモ
CREATE FUNCTION	スキーマ
USAGE	関数	新しく作成された関数の USAGE 権限をロールに付与すると、そのロールを持つユーザーは、Snowflakeの他の場所でその関数を呼び出すことができます（例: 外部トークン化のマスキングポリシーの所有者ロール）。
USAGE	外部アクセス統合	統合（ある場合）に必要。 EXTERNAL_ACCESS_INTEGRATIONS パラメーターで指定。詳細については、 CREATE EXTERNAL ACCESS INTEGRATION をご参照ください。
READ	シークレット	シークレット（ある場合）に必要。 SECRETS パラメーターで指定。詳細については、認証情報を表すシークレットの作成および関数またはプロシージャでの外部アクセス統合の使用をご参照ください。
USAGE	スキーマ	シークレットを含むスキーマ（ある場合）に必要。 SECRETS パラメーターで指定。詳細については、認証情報を表すシークレットの作成および関数またはプロシージャでの外部アクセス統合の使用をご参照ください。

スキーマ内の任意のオブジェクトを操作するには、親データベースとスキーマに対する USAGE 権限も必要であることに注意してください。

指定された権限のセットを使用してカスタムロールを作成する手順については、カスタムロールの作成をご参照ください。

セキュリティ保護可能なオブジェクトに対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、アクセス制御の概要をご参照ください。

使用上の注意¶

すべての言語¶

function_definition にはサイズ制限があります。最大許容サイズは変更される可能性があります。
function_definition を囲む区切り文字は、一重引用符またはドル記号のペアのいずれかです。

区切り文字として $$ を使用すると、一重引用符を含む関数の記述が簡単になります。

関数の本体の区切り文字が一重引用符文字である場合、 function_definition （例: 文字列リテラル）内の一重引用符は一重引用符でエスケープする必要があります。
マスキングポリシーで UDF を使用する場合は、列、 UDF、およびマスキングポリシーのデータ型が一致していることを確認します。詳細については、マスキングポリシー内のユーザー定義関数をご参照ください。
メタデータについて。

注意

Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールドをご参照ください。
CREATE OR REPLACE <オブジェクト> ステートメントはアトミックです。つまり、オブジェクトが置き換えられると、単一のトランザクションで、古いオブジェクトが削除されて新しいオブジェクトが作成されます。

Java¶

Javaでは、プリミティブデータ型は NULL 値を許可しないため、そのような型の引数に NULL を渡すと、エラーが発生します。
HANDLER 句では、メソッド名で大文字と小文字が区別されます。
IMPORTS および TARGET_PATH 句の場合、
- パッケージ、クラス、およびファイル名では大文字と小文字が区別されます。
- ステージ名では大文字と小文字が区別されません。
PACKAGES 句を使用して、Snowparkの依存関係など、Snowflakeシステム定義の依存関係のパッケージ名とバージョン番号を指定できます。その他の依存関係については、 IMPORTS 句を使用して依存関係 JAR ファイルを指定します。
Snowflakeは次を検証します。
- CREATE FUNCTION ステートメントの HANDLER で指定された JAR ファイルが存在し、指定されたクラスとメソッドが含まれていること。
- UDF 宣言で指定された入力および出力タイプは、Javaメソッドの入力および出力タイプと互換性があること。
検証は、作成時または実行時に実行できます。
- CREATE FUNCTION ステートメントの実行時に、ユーザーがアクティブなSnowflakeウェアハウスに接続している場合、 UDF は作成時に検証されます。
- それ以外の場合、 UDF は作成されますが、すぐには検証されず、Snowflakeは次のメッセージを返します。 Function <名前> created successfully, but could not be validated since there is no active warehouse。

JavaScript¶

Snowflakeは UDF 作成時に JavaScript コードを検証しません（つまり、コードが有効かどうかに関係なく UDF の作成は成功します）。コードが有効でない場合は、クエリ時にUDFが呼び出されるとエラーが返されます。

Python¶

HANDLER 句では、ハンドラー関数名で大文字と小文字が区別されます。
IMPORTS 句で、
- ファイル名は大文字と小文字が区別されます。
- ステージ名では大文字と小文字が区別されません。
PACKAGES 句を使用して、Snowparkの依存関係など、依存関係のパッケージ名とバージョン番号を指定できます。その他の依存関係については、 IMPORTS 句を使用して依存関係ファイルを指定します。
Snowflakeは次を検証します。
- CREATE FUNCTION ステートメントの HANDLER で指定された関数またはクラスが存在します。
- UDF宣言で指定された入力および出力タイプは、ハンドラーの入力および出力タイプと互換性があること。

Scala¶

HANDLER 句では、メソッド名で大文字と小文字が区別されます。
IMPORTS および TARGET_PATH 句の場合、
- パッケージ、クラス、およびファイル名では大文字と小文字が区別されます。
- ステージ名では大文字と小文字が区別されません。
PACKAGES 句を使用して、Snowparkの依存関係など、Snowflakeシステム定義の依存関係のパッケージ名とバージョン番号を指定できます。その他の依存関係については、 IMPORTS 句を使用して依存関係 JAR ファイルを指定します。
Snowflakeは次を検証します。
- CREATE FUNCTION ステートメントの HANDLER で指定された JAR ファイルが存在し、指定されたクラスとメソッドが含まれていること。
- UDF 宣言で指定された入力および出力タイプは、Scalaメソッドの入力および出力タイプと互換性があること。
検証は、作成時または実行時に実行できます。
- CREATE FUNCTION ステートメントの実行時に、ユーザーがアクティブなSnowflakeウェアハウスに接続している場合、 UDF は作成時に検証されます。
- それ以外の場合、 UDF は作成されますが、すぐには検証されず、Snowflakeは次のメッセージを返します。 Function <名前> created successfully, but could not be validated since there is no active warehouse。

SQL¶

現在、 SQL UDFs には NOT NULL 句は適用されていません。

例¶

Java¶

インラインハンドラーを使用した CREATE FUNCTION の基本的な例を次に示します。

create or replace function echo_varchar(x varchar)
returns varchar
language java
called on null input
handler='TestFunc.echoVarchar'
target_path='@~/testfunc.jar'
as
'class TestFunc {
  public static String echoVarchar(String x) {
    return x;
  }
}';

Copy

ステージングされたハンドラーへの参照を使用した CREATE FUNCTION の基本的な例を次に示します。

create function my_decrement_udf(i numeric(9, 0))
    returns numeric
    language java
    imports = ('@~/my_decrement_udf_package_dir/my_decrement_udf_jar.jar')
    handler = 'my_decrement_udf_package.my_decrement_udf_class.my_decrement_udf_method'
    ;

Copy

Java UDFs のさらなる例については、例をご参照ください。

JavaScript¶

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

Copy

Python¶

次の例のコードは、ハンドラーコードが udf としてインラインの py_udf 関数を作成します。

CREATE OR REPLACE FUNCTION py_udf()
  RETURNS VARIANT
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.8'
  PACKAGES = ('numpy','pandas','xgboost==1.5.0')
  HANDLER = 'udf'
AS $$
import numpy as np
import pandas as pd
import xgboost as xgb
def udf():
    return [np.__version__, pd.__version__, xgb.__version__]
$$;

Copy

次の例のコードは、ハンドラーが @my_stage ステージにある sleepy.py ファイル内の dream 関数を作成します。

CREATE OR REPLACE FUNCTION dream(i int)
  RETURNS VARIANT
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.8'
  HANDLER = 'sleepy.snore'
  IMPORTS = ('@my_stage/sleepy.py')

Copy

Scala¶

インラインハンドラーを使用した CREATE FUNCTION の基本的な例を次に示します。

CREATE OR REPLACE FUNCTION echo_varchar(x VARCHAR)
  RETURNS VARCHAR
  LANGUAGE SCALA
  RUNTIME_VERSION = 2.12
  HANDLER='Echo.echoVarchar'
  AS
  $$
  class Echo {
    def echoVarchar(x : String): String = {
      return x
    }
  }
  $$;

Copy

ステージングされたハンドラーへの参照を使用した CREATE FUNCTION の基本的な例を次に示します。

CREATE OR REPLACE FUNCTION echo_varchar(x VARCHAR)
  RETURNS VARCHAR
  LANGUAGE SCALA
  RUNTIME_VERSION = 2.12
  IMPORTS = ('@udf_libs/echohandler.jar')
  HANDLER='Echo.echoVarchar';

Copy

Scala UDFs のその他の例については、 Scala UDF ハンドラーの例をご参照ください。

SQL¶

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

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

Copy

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

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

Copy

SELECT * FROM TABLE(simple_table_function());

Copy

出力:

SELECT * FROM TABLE(simple_table_function());
+---+---+
| X | Y |
|---+---|
| 1 | 2 |
| 3 | 4 |
+---+---+

Copy

複数のパラメーターを受け入れる UDF を作成します。

CREATE FUNCTION multiply1 (a number, b number)
  RETURNS number
  COMMENT='multiply two numbers'
  AS 'a * b';

Copy

クエリの結果を返す 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';

Copy