外部関数の紹介¶

このトピックでは、Snowflakeの外部で開発、保守、保存、実行される、実行可能コードを呼び出す外部関数について説明します。

このトピックは、次の助けになります。

外部関数とは何かを理解。
UDF （ユーザー定義関数）を実装するための最良の方法が外部関数であるかどうかを判断。
外部関数用のクラウドプラットフォームを選択。

このトピックの内容:

外部関数とは
外部関数のしくみ
外部関数の利点
外部関数の制限
- 作成時の制限と要件
- 実行時の制限と問題
外部関数の使用に対する請求
サポートされているプラットフォーム

外部関数とは¶

外部関数 は、Snowflakeの外部で実行されるコードを呼び出します。

リモートで実行されるコードは、 リモートサービス と呼ばれます。

リモートサービスに送信される情報は、通常 プロキシサービス を介して中継されます。

Snowflakeは、セキュリティ関連の外部機能情報を API 統合 に保存します。

次の図は、クライアントプログラムからSnowflakeを経由してリモートサービスに至る、基本的な情報の流れを示しています。

../_images/external-functions-overview-07.png

各主要コンポーネントについては、以下で詳しく説明します。

外部関数:

外部関数は UDF 型です。他の UDFs とは異なり、外部関数には独自のコードが含まれていません。代わりに、外部関数はSnowflakeの外部に保存および実行されるコードを呼び出します。

Snowflake内では、外部関数は、Snowflakeがリモートサービスを呼び出すために使用する情報を含むデータベースオブジェクトとして保存されます。この保存された情報には、リモートサービスとの間で情報を中継するプロキシサービスの URL が含まれます。この情報は、 CREATE EXTERNAL FUNCTION コマンドの一部として指定されます。

外部関数を表すデータベースオブジェクトは、特定のデータベースとスキーマで作成されます。外部関数は、完全修飾名を表すためにドット表記を使用して呼び出すことができます。例:

select my_database.my_schema.my_external_function(col1) from table1;

リモートサービス:

リモートで実行されるコードは、リモートサービスと呼ばれます。

リモートサービスは関数のように機能する必要があります。たとえば、値を返す必要があります。

Snowflakeは スカラー 外部関数をサポートしています。リモートサービスは、受信した行ごとに正確に1つの行を返す必要があります。

Snowflakeの外部関数機能から呼び出されるには、リモートサービスは次の条件を満たしている必要があります。

JSON 入力を受け入れ、 JSON 出力を返します。（Snowflake互換の HTTP ヘッダーと JSON 形式のデータの詳細については、リモートサービスの入力および出力データ形式を参照。）
HTTPS エンドポイントを公開します。

たとえば、リモートサービスは次のように実装できます。

AWS Lambda関数。
Microsoft Azure Function。
EC2 インスタンスで実行されている HTTPS サーバー（例: Node.js）。

プロキシサービス:

Snowflakeは通常、リモートサービスを直接呼び出しません。代わりに、Snowflakeはプロキシサービスを呼び出します。プロキシサービスは、データをリモートサービスに中継します。

プロキシサービスは、リモートサービスへのコンシューマーを認証することにより、セキュリティを強化できます。

プロキシサービスは、リモートサービスのサブスクリプションベースの課金をサポートできます。たとえば、プロキシサービスは、リモートサービスへの発信者が有料サブスクライバーであることを確認できます。

また、プロキシサービスは、リモートサービスからの応答をSnowflakeに中継します。

プロキシサービスの例は次のとおりです。

Amazon API Gateway。
Microsoft Azure API Managementサービス。

API 統合:

統合は、Snowflakeとサードパーティサービス間のインターフェイスを提供するSnowflakeオブジェクトです。API 統合は、プロキシサービスまたはリモートサービスと連携するために必要なセキュリティ情報などの情報を保存します。

API 統合は、 CREATE API INTEGRATION コマンドで作成されます。

ユーザーは、自分のリモートサービスを作成して呼び出すか、サードパーティが作成したリモートサービスを呼び出すことができます。これらのリモートサービスは、 AWS Lambdaなどのクラウドサーバーレスコンピューティングサービスを含む、任意の HTTP サーバースタックを使用して記述できます。

SQL ステートメントを実行するユーザーの観点からすると、外部関数は他の UDF と同様に動作します。外部関数は次の規則に従います。

外部関数は値を返します。
外部関数はパラメータを受け入れることができます。

外部関数は、 UDF の他の型が表示される可能性のある SQL ステートメントの任意の句で表示することができます。例:

select my_external_function_2(column_1, column_2)
    from table_1;

select col1
    from table_1
    where my_external_function_3(col2) < 0;

create view view1 (col1) as
    select my_external_function_5(col1)
        from table9;

外部関数は、より複雑な式の一部にすることができます。

select upper(zipcode_to_city_external_function(zipcode))
  from address_table;

戻り値は、 JSON を含む VARIANT などの複合値にすることができます。
外部関数はオーバーロードされる可能性があります。2つの異なる関数に同じ名前を付けることができますが、署名の異なる（入力パラメーターの異なる数値またはデータ型）場合があります。

外部関数のしくみ¶

Snowflakeはリモートサービスを直接呼び出しません。代わりに、Snowflakeは、クラウドプロバイダーのネイティブ HTTPS プロキシサービス（たとえば、AWS 上の API Gateway）を介してリモートサービスを呼び出します。

外部関数を呼び出す主なステップは次のとおりです。

ユーザーのクライアントプログラムは、Snowflakeに外部関数を呼び出す SQL ステートメントを渡します。
クエリ実行の一部として外部関数を評価する場合、Snowflakeは外部関数の定義と対応する API 統合情報を読み取ります。
- 外部関数定義からの情報は次のとおりです。
  - プロキシサービスの URL。
  - 対応する API 統合の名前。
- API 統合からの情報は次のとおりです。
  - 使用するプロキシサービスリソース。リソースには、そのサービスの場所など、リモートサービスに関する情報が含まれています。
  - そのプロキシサービスリソースの認証情報。
次に、Snowflakeは以下を含む HTTP POST コマンドを作成します。
- 処理するデータ。このデータは JSON 形式です。
- HTTP ヘッダー情報。（詳細は、 CREATE EXTERNAL FUNCTION に記載。）
- API 統合からの認証情報。
次に、Snowflakeは POST リクエストをプロキシサービスに送信します。
プロキシサービスは POST を受信し、リクエストを処理して実際のリモートサービスに転送します。プロキシサービスとリソースは、リモートサービスを呼び出す「リレー機能」と大まかに考えることができます。
リモートサービスはデータを処理し、結果を返します。その結果は、チェーンを介して元のSQLステートメントに渡されます。
リモートサービスがHTTPコードで応答して非同期処理を通知する場合、Snowflakeは1つ以上のHTTP GETリクエストを送信して、リモートサービスから結果を取得します。Snowflakeは、リクエストを継続するための応答コードを受信する限り、または外部関数がタイムアウトするかエラーを返すまで、 GET リクエストを送信し続けます。

通常、リモートサービスに送信する行がクエリに多数ある場合、行はバッチに分割されます。バッチは通常、より多くの並列処理とより高速なクエリを可能にします。場合によっては、バッチによりリモートサービスの過負荷が軽減されます。

リモートサービスは、受信したバッチごとに行のバッチを1つを返します。スカラー外部関数の場合、返されるバッチの行数は、受信したバッチの行数と同じです。

各バッチには一意のバッチIDがあり、Snowflakeからリモートサービスに送信される各リクエストに含まれています。

再試行操作（例: タイムアウトのため）は、通常、バッチレベルで実行されます。

外部関数の利点¶

外部関数には、他の UDFs に比べて次の利点があります。

リモートサービスのコードは、他の UDFs を記述できない言語で記述できます。
- Go
- C#
リモートサービスでは、内部 UDFs によってアクセスできない関数とライブラリを使用できます。たとえば、リモートサービスは、機械学習スコアリングライブラリなどの市販のサードパーティライブラリとインターフェイスにより接続できます。
開発者は、Snowflake、および同じインターフェイスを使用するように作成された他のソフトウェアの両方から呼び出すことができる、リモートサービスを作成できます。

外部関数の制限¶

外部関数には次の制限があり、大まかに作成時の制限と実行時の制限に分類できます。

作成時の制限と要件¶

外部関数を初めて呼び出す前に、管理者は設定作業を行う必要があります。この作業には、特にセキュリティに関するクラウドプラットフォーム（例: AWS またはMicrosoft Azure）の知識が必要です。
Snowflakeは、クラウド HTTP プロキシサービス（Amazon API Gatewayなど）を介して間接的にリモートサービスを呼び出すため、外部関数のリモートサービスは、プロキシサービスから呼び出し可能である必要があります。さいわい、 HTTPS エンドポイントとして機能できるほとんどすべての関数は、プロキシサービスを介して外部関数としてアクセスできます。関数の作成者は、リモートサービスを呼び出すようにプロキシサービスをプログラムする必要があります（例: AWS Lambdaで実行される関数）。
一部のクラウドプラットフォームには特定の要件がある場合があります。たとえば、 AWS では、外部関数に地域エンドポイント、またはプライベートエンドポイントが必要です。詳細については、サポートされているプラットフォームをご参照ください。Amazon API Gatewayのリージョンエンドポイントとプライベートエンドポイントの詳細については、エンドポイントの選択: リージョンエンドポイントとプライベートエンドポイントをご参照ください。
外部関数機能を使用して記述できるのは、ストアドプロシージャではなく、関数のみです。

実行時の制限と問題¶

リモートサービスはSnowflakeに対して不透明であるため、オプティマイザーは、同等の内部関数に対して実行できるはずの最適化のいくつかを実行できない場合があります。
外部関数は、内部関数（組み込み関数と内部 UDFs の両方）よりもオーバーヘッドが大きく、通常は実行速度が遅くなります。
現在、外部関数はスカラー関数でなければなりません。スカラー外部関数は、各入力行に対して単一の値を返します。
現在、外部関数は、 Secure Data Sharing を介してデータコンシューマーと共有することはできません。
バッチあたりの最大応答サイズは 10MB です。
以下の状況では、外部関数を使用できません。
- Secure Data Sharing を介して共有される、データベースオブジェクトの一部として（テーブル、ビュー、UDF、マスキングポリシーなど）。たとえば、外部関数を使用する共有ビューを作成することはできません。次はサポートされていません。
```
CREATE VIEW my_shared_view AS SELECT my_external_function(x) ...;
CREATE SHARE things_to_share;
...
GRANT SELECT ON VIEW my_shared_view TO SHARE things_to_share;
...
```
- CREATE TABLE ステートメントの DEFAULT 句。つまり、列のデフォルト値は、外部関数を呼び出す式にすることができません。 DEFAULT 句に外部関数を含めようとすると、 CREATE TABLE ステートメントは失敗します。
- COPY 変換。
外部関数は、追加のセキュリティ問題を引き起こす可能性があります。たとえば、サードパーティの関数を呼び出すと、そのパーティは関数に渡されたデータのコピーを保持する可能性があります。

外部関数の使用に対する請求¶

外部関数を使用すると、以下に関連する通常のコストが発生します。

さらに、間接的な使用料またはサードパーティの使用料を支払う必要がある可能性があります。

リモートサービスのプロバイダーからの請求などです。

料金はベンダーによって異なります。

サポートされているプラットフォーム¶

外部関数の呼び出しをサポートするプラットフォーム¶

通常、外部関数は、Snowflakeがサポートする任意のクラウドプラットフォーム上のSnowflakeアカウントから呼び出すことができます。

Amazon Web Services（AWS）
Microsoft Azure
Google Cloud Platform（GCP）

例外は以下のとおりです。

AWS API Gatewayプライベートエンドポイントを介してアクセスする外部機能には、 AWS 上の同じ AWS リージョン内にあるSnowflake VPC （仮想プライベートクラウド）からのみアクセスできます。AWS のプライベートエンドポイントの詳細については、エンドポイントの選択: リージョンエンドポイントとプライベートエンドポイントをご参照ください。

外部関数を呼び出すための SQL 構文は、すべてのプラットフォームで同じです。

これらのサービスへのアクセスを構成する SQL ステートメント（ CREATE EXTERNAL FUNCTION および CREATE API INTEGRATION）は、すべてのプラットフォームで同じです。ただし、これらのステートメント内の句は、プロキシサービスとリモートサービスをホストしているプラットフォームによって異なります。

外部関数のリモートサービスとプロキシサービスの作成をサポートするプラットフォーム¶

外部関数はどのプラットフォームからも呼び出すことができますが、外部関数のリモートサービスとプロキシサービスは、それぞれ特定のサポートされているプラットフォームで作成する必要があります。

多くの場合、リモートサービスのプラットフォームおよびアカウントは、プロキシサービスのプラットフォームおよびアカウントと同じです。ただし、必須ではありません。たとえば、 SQL クエリは AWS API Gateway（プロキシサービス）を介してAzure Function（リモートサービス）を呼び出すことができます。SQL クエリ自体が、 GCP で実行されているSnowflakeインスタンスで実行されている可能性があります。

リモートサービスをサポートするプラットフォーム¶

リモートサービスをホストするには、 HTTP サーバースタックが必要です。リモートサービスをサポートできるすべての HTTP サーバースタックでは、外部関数との互換性が必要です。

リモートサービスを作成するには、通常、次のものが必要です。

クラウドプラットフォームのプロバイダーを持つアカウント（たとえば、Azure Functionを作成するためのMicrosoft Azureアカウント）。このアカウントは、リモートサービスのストレージサービスとコンピューティングサービスを提供します。このアカウントは、Snowflakeアカウントとは別です。

Snowflakeは、リモートサービスを作成するための手順を次のように提供します。

AWS Lambda関数。
Microsoft Azureの関数。
Google Cloud関数。

プロキシサービスをサポートするプラットフォーム¶

クラウドプラットフォーム上のネイティブ HTTP プロキシサービスのインスタンスが必要です。

プロキシサービスを構成するには、通常、次が必要です。

クラウドプラットフォームのプロバイダーのアカウント（例: AWS を使用するためのAmazonアカウント）。このアカウントは、プロキシサービスのストレージサービスとコンピューティングサービスを提供します。このアカウントは、Snowflakeアカウントとは別です。
プロキシサービスの構成に必要な権限を持つクラウドプラットフォームのロール。このクラウドプラットフォームのロールは、Snowflakeのロールとは別です。

次の HTTPS プロキシサービスがサポートされています。

Amazon API Gateway。
Microsoft Azure API Managementサービス。
Google Cloud API Gateway。

以下のセクションには、プラットフォームを選択する前にユーザーが知っておくべきプラットフォーム固有の情報が含まれています。

プラットフォーム固有の制限¶

AWS

Amazon API Gatewayのリージョンおよびプライベートエンドポイントのみをサポートしています。（エンドポイントのさまざまなタイプの説明については、エンドポイントを参照。）
Snowflake外部関数と API 統合は、 AWS カスタムドメインをサポートしていません。SnowflakeからAmazon API Gatewayにアクセスするには、 AWS によって生成されたデフォルトの URL を使用します。これは次のようになります。
```
https://api-id.execute-api.region.amazonaws.com/stage
```