CREATE EXTERNAL FUNCTION

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

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

ALTER FUNCTION、 SHOW EXTERNAL FUNCTIONS、 DROP FUNCTION、 DESCRIBE FUNCTION、 CREATE 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> ]
  [ REQUEST_TRANSLATOR = <request_translator_udf_name> ]
  [ RESPONSE_TRANSLATOR = <response_translator_udf_name> ]
  AS <url_of_proxy_and_resource>;
Copy

必須パラメーター

name:

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

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

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

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

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

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

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

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

RETURNS result_data_type

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

API_INTEGRATION = api_integration_name

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

AS url_of_proxy_and_resource

Snowflakeがリモートサービスを呼び出すときに使用するプロキシサービス（例: API GatewayまたはAPI管理サービス）とリソースの呼び出し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 = 'string_literal'

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

デフォルト： user-defined function

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

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

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

次に例を示します。

HEADERS = (
    'volume-measure' = 'liters',
    'distance-measure' = 'kilometers'
)
Copy

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

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

  • スペース文字

  • (

  • )

  • ,

  • /

  • :

  • ;

  • <

  • >

  • =

  • "

  • ?

  • @

  • [

  • ]

  • \

  • {

  • }

  • _

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

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

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

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

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

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

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

これは HEADERS に似ていますが、定数文字列を使用する代わりに、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_external_function(1);
Copy

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

select /* */ my_external_function(1);
Copy

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

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

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

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

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

sf-context-<context-function>-base64
Copy

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

sf-context-current-statement-base64
Copy

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

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

MAX_BATCH_ROWS = integer

プロキシサービスに送信される各バッチの 最大 行数を指定します。

このパラメーターの目的は、メモリの制約やその他の制限があるリモートサービスのバッチサイズを制限することです。このパラメーターは、パフォーマンスチューニングパラメーターではありません。このパラメーターは、推奨サイズではなく、最大サイズを指定します。

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

Snowflakeは、リモートサービスで制限が必要な場合を除いて、このパラメーターを未設定のままにしておくことをお勧めします。

COMPRESSION = compression_type

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

有効な値:

  • NONE.

  • GZIP.

  • DEFLATE.

  • AUTO.

    • AWS において、 AUTO は GZIP と同等です。

    • Azureにおいて、 AUTO は NONE と同等です。

    • GCP において、 AUTO は NONE と同等です。

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

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

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

REQUEST_TRANSLATOR = request_translator_udf_name

リクエストトランスレーター関数の名前を指定します。詳細については、 リモートサービスに対するデータのあるリクエストトランスレーターおよび応答トランスレーターの使用 をご参照ください。

RESPONSE_TRANSLATOR = response_translator_udf_name

応答トランスレーター関数の名前を指定します。詳細については、 リモートサービスに対するデータのあるリクエストトランスレーターおよび応答トランスレーターの使用 をご参照ください。

アクセス制御の要件

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

権限

オブジェクト

メモ

CREATE EXTERNAL FUNCTION

スキーマ

Operating on functions also requires the USAGE privilege on the parent database and schema.

OWNERSHIP または USAGE の いずれか

API 統合

API 統合を参照する外部関数を作成するために必要です。

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

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

使用上の注意

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

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

  • メタデータについて。

    注意

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

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

例

次の例は、Amazon 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';
Copy

この例では：

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

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

  • 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 に送信されます。

言語: 日本語