CREATE FUNCTION （Snowpark Container Services）¶

構文¶

CREATE [ OR REPLACE ] FUNCTION <name> ( [ <arg_name> <arg_data_type> ] [ , ... ] )
  RETURNS <result_data_type>
  [ [ NOT ] NULL ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  SERVICE = <service_name>
  ENDPOINT = <endpoint_name>
  [ COMMENT = '<string_literal>' ]
  [ CONTEXT_HEADERS = ( <context_function_1> [ , <context_function_2> ...] ) ]
  [ MAX_BATCH_ROWS = <integer> ]
  [ MAX_BATCH_RETRIES = <integer> ]
  [ ON_BATCH_FAILURE = { ABORT | RETURN_NULL } ]
  [ BATCH_TIMEOUT_SECS = <integer> ]
  AS '<http_path_to_request_handler>'

バリアント構文¶

CREATE [ OR ALTER ] FUNCTION ...

必須パラメーター¶

name

識別子（name）と入力引数を指定します。

• 関数は 名前と引数の型の組み合わせによって識別および解決される ため、識別子は、関数が作成されるスキーマに対して一意である必要はありません。

• 識別子はアルファベットで始まる必要があり、識別子の文字列全体が二重引用符で囲まれている場合を除き、スペースや特殊文字を含めることはできません（例: "My object"）。二重引用符で囲まれた識別子も大文字と小文字が区別されます。識別子の要件 をご参照ください。

( [ arg_name arg_data_type ] [ , ... ] )

サービス関数の引数/入力を指定します。これらは、サービスが期待する引数に対応している必要があります。

引数がない場合は、引数名とデータ型なしで括弧を含めます。

RETURNS result_data_type

関数によって返される結果のデータ型を指定します。

SERVICE = service_name

Snowpark Container Servicesサービスの名前を指定します。

ENDPOINT = endpoint_name

サービス仕様で定義されているエンドポイント名を指定します。

AS http_path_to_request_handler

関数が呼び出されたときに実行されるサービスコードへの HTTP パスを指定します。

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

[ [ NOT ] NULL ]

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

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

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

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

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

デフォルト: CALLED ON NULL INPUT

{ VOLATILE | IMMUTABLE }

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

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

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

デフォルト: VOLATILE

MAX_BATCH_ROWS = integer

サービスにデータを送信する際に、 バッチサイズ を指定し、同時実行性を高めます。

MAX_BATCH_RETRIES = integer

失敗したバッチをSnowflakeが再試行する回数を指定します。

デフォルト:3

ON_BATCH_FAILURE = { ABORT | RETURN_NULL }

Snowflakeがバッチ処理の最大再試行回数に達した後の関数の動作を指定します。

• ABORT: サービス関数が実行を中断します。残りの行のバッチは処理されません。

• RETURN_NULL: サービス関数は、失敗したバッチ内の各行に対して NULL を返し、残りのバッチの処理を続行します。このオプションを選択する場合は、以下の点に注意してください。

  • これらのバッチが互いに依存関係にあり、1つのバッチが失敗すると、予期しない結果につながる可能性があります

  • サービスが有効な応答として NULL を返すことができる場合、Snowflakeがバッチの失敗によって返した NULL と、サービスが返した NULL を区別することはできません。

デフォルト: ABORT

BATCH_TIMEOUT_SECS = integer

再試行（および非同期関数リクエストのポーリング）を含む、1つの行のバッチ処理にかかる最大時間を指定します。その後Snowflakeはバッチリクエストを終了します。

許容値:0より大きく604,800秒（7日）以下。

デフォルト:604800秒（7日間）

COMMENT = 'string_literal'

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

デフォルト: user-defined function

CONTEXT_HEADERS = ( context_function_1 [ , context_function_2 ...] )

これは、Snowflake コンテキスト関数の結果を HTTP ヘッダーにバインドします。（Snowflakeコンテキスト関数の詳細については、 コンテキスト関数 を参照。）

すべてのコンテキスト関数がコンテキストヘッダーでサポートされているわけではありません。以下がサポートされています。

• CURRENT_ACCOUNT()

• CURRENT_CLIENT()

• CURRENT_DATABASE()

• CURRENT_DATE()

• CURRENT_IP_ADDRESS()

• CURRENT_REGION()

• CURRENT_ROLE()

• CURRENT_SCHEMA()

• CURRENT_SCHEMAS()

• CURRENT_SESSION()

• CURRENT_STATEMENT()

• CURRENT_TIME()

• CURRENT_TIMESTAMP()

• CURRENT_TRANSACTION()

• CURRENT_USER()

• CURRENT_VERSION()

• CURRENT_WAREHOUSE()

• LAST_QUERY_ID()

• LAST_TRANSACTION()

• LOCALTIME()

• LOCALTIMESTAMP()

関数名が CONTEXT_HEADERS 句にリストされている場合、関数名は引用符で囲まないでください。

Snowflakeは、ヘッダーを HTTP リクエストに書き込む前に、 sf-context を付加します。

例:

CONTEXT_HEADERS = (current_timestamp)

Copy

この例では、Snowflakeはヘッダー sf-context-current-timestamp を HTTP リクエストに書き込みます。

コンテキスト関数は、次のような HTTP ヘッダー値（ただし、これらに限らない）で無効な文字を生成する可能性があります。

• newline

• Ä

• Î

• ß

• ë

• ¬

• ±

• ©

• ®

Snowflakeは、1つ以上の無効な文字の各シーケンスを1つのスペース文字に置き換えます。（置換は、文字ごとではなくシーケンスごと。）

たとえば、コンテキスト関数 CURRENT_STATEMENT() が次を返すとします。

select
  /*ÄÎß묱©®*/
  my_service_function(1);

Copy

sf-context-current-statement で送信される値は次のとおりです。

select /* */ my_service_function(1);

Copy

不正な文字が置き換えられた場合でも、サービスがコンテキスト関数から元の結果（不正な文字を含む）にアクセスできるようにするために、Snowflakeは Base64 でエンコードされたコンテキスト関数結果を含むバイナリコンテキストヘッダーも送信します。

上記の例では、Base64でエンコードされたヘッダーで送信される値は、次の呼び出しの結果です。

base64_encode('select\n/ÄÎß묱©®/\nmy_service_function(1)')

Copy

リモートサービスは、必要に応じてBase64値のデコードを担当します。

このような各Base64ヘッダーは、次の規則に従って名前が付けられています。

sf-context-<context-function>-base64

Copy

上記の例では、ヘッダーの名前は次のようになります。

sf-context-current-statement-base64

Copy

コンテキストヘッダーが送信されない場合、Base64コンテキストヘッダーは送信されません。

外部関数に送信された行が複数のバッチに分割されている場合は、すべてのバッチに同じコンテキストヘッダーと同じバイナリコンテキストヘッダーが含まれます。

アクセス制御の要件¶

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

Operating on an object in a schema requires at least one privilege on the parent database and at least one privilege on the parent schema.

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

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

一般的な使用上の注意¶

• CREATE OR REPLACE <オブジェクト> ステートメントはアトミックです。つまり、オブジェクトが置き換えられると、単一のトランザクションで、古いオブジェクトが削除されて新しいオブジェクトが作成されます。

• メタデータについて:

  注意

  Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールド をご参照ください。

CREATE OR ALTER FUNCTION （Snowpark Container Services）の使用上の注意¶

以下の変更はサポートされていません。

• RETURNS

• ボラティリティ（VOLATILE/IMMUTABLE）

• Null処理（CALLED ON NULL INPUT/RETURNS NULL ON NULL）

例¶

CREATE FUNCTION my_echo_udf (InputText VARCHAR)
  RETURNS VARCHAR
  SERVICE=echo_service
  ENDPOINT=echoendpoint
  AS '/echo';

CREATE OR ALTER FUNCTION my_echo_udf (InputText VARCHAR)
  RETURNS VARCHAR
  SERVICE = echo_service
  ENDPOINT = reverse_echoendpoint
  CONTEXT_HEADERS = (current_account)
  MAX_BATCH_ROWS = 100
  AS '/echo';