CREATE FUNCTION （Snowpark Container Services）

サービス関数 を作成します。

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

サービス関数, CREATE EXTERNAL FUNCTION, DESC FUNCTION, DROP FUNCTION, ALTER FUNCTION,

構文

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> ]
  AS '<http_path_to_request_handler>'
Copy

必須パラメーター

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 ]

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

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 ヘッダー値（ただし、これらに限らない）で無効な文字を生成する可能性があります。

  • 改行

  • Ä

  • Î

  • ß

  • ë

  • ¬

  • ±

  • ©

  • ®

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コンテキストヘッダーは送信されません。

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

アクセス制御の要件

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

権限

オブジェクト

メモ

CREATE FUNCTION

スキーマ

USAGE

サービスエンドポイント

サービスエンドポイントでの利用は、サービス仕様で定義されたサービスロールに付与されます。次に、サービス関数を作成するロールにサービス・ロールを付与します。

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

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

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

使用上の注意

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

  • メタデータについて:

    注意

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

例

Tutorial-1 では、以下のサービス関数を作成しています：

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

この関数は、指定された SERVICE の特定の ENDPOINT に接続します。この関数を呼び出すと、Snowflakeはサービスコンテナー内の /echo パスにリクエストを送信します。

次の点に注意してください。

  • my_echo_udf 関数は、入力として文字列を取り、文字列を返します。

  • SERVICE プロパティはサービス（echo_service）を識別し、 ENDPOINT プロパティはユーザーフレンドリーなエンドポイント名（echoendpoint）を識別します。

  • AS '/echo' は、サービスへのパスを指定します。 echo_service.py （サービスコードを参照）では、 @app.post デコレーターがこのパスを echo 関数に関連付けます。

言語: 日本語