カテゴリ:

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

CREATE EXTERNAL FUNCTION

新しい 外部関数 を作成します。

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

ALTER EXTERNAL FUNCTIONSHOW EXTERNAL FUNCTIONSDROP FUNCTIONDESCRIBE FUNCTIONCREATE API INTEGRATION

構文

CREATE [ OR REPLACE ] [ SECURE ] EXTERNAL 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 ]
  [ COMMENT = '<string_literal>' ]
  API_INTEGRATION = <api_integration_name>
  [ HEADERS = ( '<header_1>' = '<value_1>' [ , '<header_2>' = '<value_2>' ... ] ) ]
  [ CONTEXT_HEADERS = ( <context_function_1> [ , context_function_2> ...] ) ]
  [ MAX_BATCH_ROWS = <integer> ]
  [ COMPRESSION = <compression_type> ]
  AS <url_of_proxy_and_resource>;

必須パラメーター

名前

関数の識別子を指定します。

識別子には、スキーマ名、データベース名、および関数名を含めることができます。

関数は名前と引数のタイプによって識別および解決されるため、識別子は、関数が作成されるスキーマに対して一意である必要はありません。ただし、署名(名前と引数のデータ型)はスキーマ内で一意である必要があります。

名前 は、Snowflake 識別子 のルールに従う必要があります。詳細については、 識別子の要件 をご参照ください。

名前 をリモートサービス名と同じに設定すると、関係がより明確になります。ただし、これは必須ではありません。

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

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

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

RETURNS ...

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

API統合名

これは、プロキシサービスへの呼び出しを認証するために使用する必要がある API 統合オブジェクトの名前です。

プロキシとリソースのURL

Snowflakeがリモートサービスを呼び出すときに使用するプロキシサービス(例: API Gateway)とリソースの呼び出し URL です。

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

SECURE

関数が安全であることを指定します。関数がセキュアな場合、 URL、 HTTP ヘッダー、およびコンテキストヘッダーは、関数の所有者ではないすべてのユーザーに対して非表示になります。

[ [ NOT ] NULL ]

この句は、関数が NULL 値を返すことができるか、または NON-NULL 値のみを返す必要があるかを示します。 NOT NULL が指定されている場合、関数は NULL 以外の値のみを返す必要があります。 NULL が指定されている場合、関数は 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 :同じ入力で呼び出された場合、関数は常に同じ結果を返します。Snowflakeは、これに対するチェックと保証をしません。リモートサービスは、このように動作するように設計する必要があります。同じ入力に対して実際に異なる値を返す関数に IMMUTABLE を指定すると、未定義の動作が発生します。

デフォルト: VOLATILE

Snowflakeは、デフォルトを受け入れるのではなく、これを明示的に設定することをお勧めします。これを明示的に設定すると、エラーの可能性が減り、関数の動作がユーザーにわかります。(SHOW EXTERNAL FUNCTIONS コマンドは、関数が可変か不変かを表示。)

VOLATILE と IMMUTABLE の外部関数の比較に関する重要な追加情報については、 関数を揮発性または不変として分類 をご参照ください。

COMMENT = '文字列リテラル'

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

[ HEADERS = ( '<header_1>' = '<value_1>' [ , '<header_2>' = '<value_2>' ... ] ) ]

この句を使用すると、ユーザーはすべてのリクエストで送信されるキー値メタデータを指定できます。外部関数の作成者はヘッダーに何を入れるかを決定し、呼び出し元はそれを制御できません。Snowflakeは、指定されたすべてのヘッダー名に「sf-custom-」というプレフィックスを付加し、それらを HTTP ヘッダーとして送信します。

値は、式ではなく定数文字列でなければなりません。

次に例を示します。

headers = (
    'volume-measure' = 'liters',
    'distance-measure' = 'kilometers'
)

これにより、Snowflakeは各 HTTPS リクエストに HTTP ヘッダーを2つ追加します。 sf-custom-volume-measuresf-custom-distance-measure、および対応する値。

ヘッダー名のルールは、Snowflakeデータベース識別子のルールとは異なります。ヘッダー名は、次の場合を除き、最も見やすい標準の ASCII 文字(小数点32~126)で構成できます。

  • `` `` (スペース文字)

  • (

  • )

  • ,

  • /

  • :

  • ;

  • <

  • >

  • =

  • "

  • ?

  • @

  • [

  • ]

  • \

  • {

  • }

  • _

特に、アンダースコア文字はヘッダー名に使用できないことに注意してください。

ヘッダー名と値は一重引用符で区切られているため、ヘッダー名または値内の単一引用符はバックスラッシュ文字でエスケープする必要があります。

バックスラッシュ文字をヘッダー値内のリテラル文字として使用する場合は、エスケープする必要があります。

ヘッダー値では、スペースとタブの両方を使用できますが、ヘッダー値には、1行に複数の空白文字を含めることはできません。この制限は、空白文字(例:スペースの後にタブが続く場合)と個々の空白文字(例:2つのスペースが連続している場合)の組み合わせに適用されます。

関数の作成者が( CREATE SECURE EXTERNAL FUNCTION... を使用して)関数をセキュアとしてマークすると、ヘッダー、コンテキストヘッダー、バイナリコンテキストヘッダー、および URL は関数ユーザーには表示されません。

外部関数のヘッダー名とヘッダー値のサイズの合計は、8 KB 以下でなければなりません。

CONTEXT_HEADERS ...

これは headers に似ていますが、定数文字列を使用する代わりに、Snowflakeコンテキスト関数の結果を HTTP ヘッダーにバインドします。(Snowflakeコンテキスト関数のリストについては、 コンテキスト関数 を参照。)

関数名は引用符で囲まないでください。

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

例:

context_headers = (current_timestamp)

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

コンテキストヘッダーの名前と値で使用できる文字は、 カスタムヘッダーの名前と値 で使用できる文字と同じです。

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

  • 改行

  • Ä

  • Î

  • ß

  • ë

  • ¬

  • ±

  • ©

  • ®

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

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

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

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

select /* */ my_external_function(1);

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

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

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

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

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

sf-context-<context-function>-base64

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

sf-context-current-statement-base64

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

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

MAX_BATCH_ROWS = <integer>

プロキシサービスに送信される各バッチの最大行数を指定します。送信される行の総数がバッチサイズの倍数でない限り、バッチサイズは小さくすることができ、通常、クエリの最後のバッチは小さくなります。

MAX_BATCH_ROWS を指定しない場合、Snowflakeは最適なバッチサイズを推定し、使用します。

値は1から2147483647までの正の整数でなければなりません。

COMPRESSION = <compression_type>

この句が指定されている場合、 JSON ペイロードは、Snowflakeからプロキシサービスに送信されるとき、およびプロキシサービスからSnowflakeに送り返されるときに圧縮されます。

有効な値:

  • NONE.

  • AUTO.(AWS では、これは GZIP と同等です。)

  • GZIP.

  • DEFLATE.

Amazon AWS API Gatewayは、リクエストを自動的に圧縮/解凍します。Amazon API Gatewayの圧縮と解凍の詳細については、https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-gzip-compression-decompression.html をご参照ください。

他のクラウドプラットフォームプロキシサービスの圧縮と解凍については、各クラウドプラットフォームのドキュメントをご覧ください。

デフォルト:デフォルトは AUTO です。

使用上の注意

  • 外部関数を実行するには、外部関数に対する USAGE または OWNERSHIP 権限がロールに必要です。

  • 圧縮を使用すると、Snowflakeは HTTP ヘッダーに「Content-Encoding」と「Accept-Encoding」を設定します。

  • AWS では、外部関数に地域エンドポイントが必要です。詳細については、 Amazon AWS API Gateway をご参照ください。

  • 引数の型と戻り値の型を GEOGRAPHY にすることはできません。

次の例は、Amazon AWS API Gatewayプロキシサービスを介して呼び出される CREATE EXTERNAL FUNCTION ステートメントを示しています。

create or replace external function local_echo(string_col VARCHAR)
    returns variant
    api_integration = demonstration_external_api_integration_01
    as 'https://xyz.execute-api.us-west-2.amazonaws.com/prod/remote_echo';

この例では、

  • local_echo は、 SQL ステートメントから呼び出される名前です。(例: SELECT local_echo(varchar_column) ...; を実行できます。)

  • string_col VARCHAR には、入力パラメーターの名前とデータ型が含まれます。外部関数は、0、1、または複数の入力パラメーターを持つことができます。

  • variant は、外部関数によって返される値のデータ型です。

  • 名前 demonstration_external_api_integration_01 は、以前に CREATE API INTEGRATION ステートメントで作成された API 統合の名前です。

  • URL 「https://xyz.execute-api.us-west-2.amazonaws.com/prod/remote_echo」は、プロキシサービスとリソースを識別する文字列です。HTTP POST コマンドがこの URL に送信されます。