# Snowflake 接続
AWS Glue for Spark を使用して、AWS Glue 4.0 以降のバージョンの Snowflake のテーブルからの読み込みとテーブルへの書き込みを行うことができます。Snowflake からの読み込みは SQL クエリで行うことができます。基本認証 (ユーザー名とパスワードを使用)、OAuth 認証、またはキーペア認証の 3 つの方法のいずれかを使用して Snowflake に接続できます。AWS Glue データ接続を使用して AWS Secrets Manager に保存された Snowflake 認証情報を参照できます。AWS Glue for Spark のデータ接続 Snowflake 認証情報は、クローラー用のデータカタログ Snowflake 認証情報とは別に保存されます。Snowflake に接続するように設定された `JDBC` タイプの接続ではなく、`SNOWFLAKE` タイプの接続を選択する必要があります。
Snowflake の詳細については、「[Snowflake ウェブサイト](https://www.snowflake.com/)」を参照してください。AWS 上の Snowflake の詳細については、「[Snowflake Data Warehouse on Amazon Web Services](https://aws.amazon.com/financial-services/partner-solutions/snowflake/)」を参照してください。
## Snowflake 接続の設定
インターネット経由で利用できる Snowflake データベースに接続するための AWS の前提条件はありません。
オプションで、次の設定を実行して AWS Glue で接続認証情報を管理できます。
**AWS Glue で接続認証情報を管理するには**
1. AWS Secrets Manager で、Snowflake の認証情報を使用してシークレットを作成します。Secrets Manager でシークレットを作成するには、AWS Secrets Manager ドキュメントの「[AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html#create_secret_cli)」にあるチュートリアルに従ってください。シークレットを作成したら、次のステップのためにシークレット名 {{secretName}} を保存しておきます。
+ OAuth 認証の場合:
+ **[キー/値のペア]** をクリックし、`sfUser` キーを使用して {{snowflakeUser}} のペアを作成します
+ **[キー/値のペア]** をクリックし、`USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` キーを使用して {{OAUTH\_CLIENT\_SECRET}} のペアを作成します
+ キーペア認証の場合:
+ **[キー/値のペア]** をクリックし、`sfUser` キーを使用して {{snowflakeUser}} のペアを作成します
+ **[キー/値のペア]** をクリックし、`pem_private_key` キーを使用して{{プライベートキー}}のペアを作成します
+ 基本認証の場合:
+ **[キー/値のペア]** をクリックし、`USERNAME` キーを使用して {{snowflakeUser}} のペアを作成します
+ **[キー/値のペア]** をクリックし、`PASSWORD` キーを使用して {{snowflakePassword}} のペアを作成します
+ **キーと値のペア**を選択するときに、Snowflake ウェアハウスにキー `sfWarehouse` を提供できます。
+ **[キーと値のペア]** を選択する際、対応する Spark プロパティ名をキーとして使用し、追加の Snowflake 接続プロパティを指定できます。サポートされているプロパティには、次のものが含まれます。
+ `sfDatabase` – Snowflake データベース名
+ `sfSchema` – Snowflake スキーマ名
+ `sfRole` – Snowflake ロール名
1. AWS Glue Studio Console で、**[データ接続]**、**[接続を作成]** の順に選択して、接続を作成します。次の接続ウィザードの手順に従って、プロセスを完了します。
+ **[データソース]** を選択する際には、[Snowflake] を選択し、**[次へ]** を選択します。
+ ホストやポートなどの接続の詳細を入力します。ホストである **[Snowflake URL]** を入力して、Snowflake インスタンスの URL を指定します。通常、URL では `{{account_identifier}}.snowflakecomputing.com` という形式のホスト名を使用します。ただし、URL 形式は Snowflake アカウントタイプ (AWS、Azure、Snowflake-hosted など) によって異なる場合があります。
+ IAM サービスロールを選択する際には、ドロップダウンメニューから 選択します。これは、VPC が指定されている場合、AWS Secrets Manager にアクセスして IP を割り当てるために使用されるアカウントの IAM ロールです。
+ **[AWS Secret]** をクリックして、{{secretName}} を入力します。
1. ウィザードの次のステップで、Snowflake 接続のプロパティを設定します。
1. ウィザードの最後のステップで、設定を確認し、接続を作成するプロセスを完了します。
Amazon VPC の AWS で でホストされている Snowflake では、次が必要になる場合があります。
+ Snowflake には適切な Amazon VPC 設定が必要です。Amazon VPC の設定方法の詳細については、Snowflake ドキュメントの「[AWS PrivateLink & Snowflake](https://docs.snowflake.com/en/user-guide/admin-security-privatelink)」を参照してください。
+ AWS Glue には適切な Amazon VPC 設定が必要です。[AWS Glue (AWS PrivateLink) のインターフェイス VPC エンドポイントの設定 (AWS PrivateLink)](vpc-interface-endpoints.md)。
+ (Snowflake のセキュリティ認証情報を定義する AWS Secrets Manager シークレットの ID に加えて) Amazon VPC 接続情報を提供する AWS Glue データカタログ接続を作成する必要があります。前の項目でリンクされている Snowflake ドキュメントで説明されているように、AWS PrivateLink の使用時に URL が変更されます。
+ ジョブ設定には、データカタログ接続を**追加ネットワーク接続**として含める必要があります。
## Snowflake テーブルからの読み込み
**前提条件:** 読み込む目的の Snowflake テーブルがあること。Snowflake のテーブル名 {{tableName}} が必要になります。Snowflake ユーザーにデフォルトの名前空間が設定されていない場合は、Snowflake データベース名 {{databaseName}}、スキーマ名 {{schemaName}} が必要になります。さらに、Snowflake ユーザーにデフォルトのウェアハウスセットがない場合は、ウェアハウス名 {{warehouseName}} が必要になります。接続する**その他のネットワーク接続**を選択するには、`connectionName` パラメータを使用します。
```
snowflake_read = glueContext.create_dynamic_frame.from_options(
connection_type="snowflake",
connection_options={
"connectionName": "{{connectionName}}",
"dbtable": "{{tableName}}",
"sfDatabase": "{{databaseName}}",
"sfSchema": "{{schemaName}}",
"sfWarehouse": "{{warehouseName}}",
}
)
```
さらに、`autopushdown` および `query` パラメータを使用して Snowflake テーブルの一部を読み込むことができます。これは、Spark に読み込まれた後に結果をフィルタリングするよりもはるかに効率的です。すべての売上が同じテーブルに格納されているが、分析する必要があるのは休日の特定の店舗の売上だけだという例を考えてみましょう。その情報がテーブルに格納されている場合は、述語プッシュダウンを使用して次のように結果を取得できます。
```
snowflake_node = glueContext.create_dynamic_frame.from_options(
connection_type="snowflake",
connection_options={
"autopushdown": "on",
"query": "select * from sales where store='1' and IsHoliday='TRUE'",
"connectionName": "snowflake-glue-conn",
"sfDatabase": "{{databaseName}}",
"sfSchema": "{{schemaName}}",
"sfWarehouse": "{{warehouseName}}",
}
)
```
## Snowflake テーブルへの書き込み
**前提条件:** 書き込み先の Snowflake データベース。現在の、または希望するテーブル名 {{tableName}} が必要です。Snowflake ユーザーにデフォルトの名前空間が設定されていない場合は、Snowflake データベース名 {{databaseName}}、スキーマ名 {{schemaName}} が必要になります。さらに、Snowflake ユーザーにデフォルトのウェアハウスセットがない場合は、ウェアハウス名 {{warehouseName}} が必要になります。接続する**その他のネットワーク接続**を選択するには、`connectionName` パラメータを使用します。
```
glueContext.write_dynamic_frame.from_options(
connection_type="snowflake",
connection_options={
"connectionName": "{{connectionName}}",
"dbtable": "{{tableName}}",
"sfDatabase": "{{databaseName}}",
"sfSchema": "{{schemaName}}",
"sfWarehouse": "{{warehouseName}}",
},
)
```
## Snowflake 接続オプションのリファレンス
Snowflake 接続タイプには次の接続オプションがあります。
このセクションのパラメータの一部は AWS Glue 接続 (`sfUrl`、`sfUser`、`sfPassword`) から取得できます。その場合は指定する必要はありません。これを行うには、`connectionName` パラメータを含めます。
`secretId` パラメータを使用して、AWS Secrets Manager シークレットから接続パラメータを取得できます。Secrets Manager を使用する際、次の Spark プロパティがシークレットに存在する場合、自動的に取得できます。
+ `sfUser` (`USERNAME` または `sfUser` キーを使用)
+ `sfPassword` (基本認証を使用する場合、キー `PASSWORD` または `sfPassword` を使用)
+ `sfWarehouse` (`sfWarehouse` キーを使用)
+ `sfDatabase` (`sfDatabase` キーを使用)
+ `sfSchema` (`sfSchema` キーを使用)
+ `sfRole` (`sfRole` キーを使用)
+ `pem_private_key` (キーペア認証を使用する場合、キー `pem_private_key` を使用)
+ `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` (OAuth 認証を使用する場合)
**プロパティの優先順位:** 同じプロパティが複数の場所で指定されている場合、AWS Glue によって次の優先順位 (最高から最低) が使用されます。
1. ジョブコードで明示的に提供される接続オプション
1. Glue 接続プロパティ
1. AWS Secrets Manager シークレット値 (`secretId` が指定されている場合)
1. Snowflake ユーザーのデフォルト
以下のパラメータは、Snowflake に接続する際に一般的に使用されます。
+ `sfDatabase` — Snowflake でユーザーデフォルトが設定されていない場合は必須です。読み込み/書き込みに使用されます。接続後にセッションに使用するデータベース。
+ `sfSchema` — Snowflake でユーザーデフォルトが設定されていない場合は必須です。読み込み/書き込みに使用されます。接続後にセッションに使用するスキーマ。
+ `sfWarehouse` — Snowflake でユーザーデフォルトが設定されていない場合は必須です。読み込み/書き込みに使用されます。接続後にセッションに使用するデフォルトの仮想ウェアハウス。
+ `sfRole` — Snowflake でユーザーデフォルトが設定されていない場合は必須です。読み込み/書き込みに使用されます。接続後にセッションに使用するデフォルトのセキュリティロール。
+ `sfUrl` — (必須) 読み込み/書き込みに使用されます。アカウントのホスト名を `{{account_identifier}}.snowflakecomputing.com` の形式で指定します。アカウント識別子の詳細については、Snowflake ドキュメントの「[アカウント識別子](https://docs.snowflake.com/en/user-guide/admin-account-identifier)」を参照してください。
+ `sfUser` — (必須) 読み込み/書き込みに使用されます。Snowflake ユーザーのログイン名。
+ `sfPassword` — (基本的な認証を使用する場合に必須) 読み取り/書き込みに使用されます。Snowflake ユーザーのパスワード。
+ `dbtable` — フルテーブルで作業する場合は必須です。読み込み/書き込みに使用されます。読み込まれるテーブルまたはデータが書き込まれるテーブルの名前。読み込み時には、すべての列とレコードが取得されます。
+ `pem_private_key` — (キーペア認証を使用する場合に必須) 読み取り/書き込みに使用されます。暗号化されていない b64 でエンコードされたプライベートキーの文字列。Snowflake ユーザーのプライベートキー。 これを PEM ファイルからコピーするのが一般的です。詳細については、Snowflake ドキュメントの「[キーペア認証とキーペアローテーション](https://docs.snowflake.com/en/user-guide/key-pair-auth)」を参照してください。
+ `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` — (OAuth 認証を使用する場合に必須) 読み取りオペレーションと書き込みオペレーションの両方に使用されます。この値は OAUTH\_CLIENT\_SECRET に対応します。OAUTH\_CLIENT\_SECRET は、アカウントの OAuth ベースの認証を有効化するように設定された Snowflake セキュリティ統合から取得できます。詳細については、Snowflake OAuth セキュリティ統合セットアップドキュメント「[カスタムクライアント用に Snowflake OAuth を設定する](https://docs.snowflake.com/en/user-guide/oauth-custom)」を参照してください。
+ `query` — クエリで読み込みを行う場合は必須です。読み込みに使用されます。実行する正確なクエリ (`SELECT` ステートメント)
以下のオプションを使用して、Snowflake への接続プロセス中の特定の動作を設定します。
+ `preactions` — 読み込み/書き込みに使用されます。有効値: セミコロンで区切られた文字列形式の SQL ステートメントのリスト。SQL ステートメントは、AWS Glue と Snowflake の間でデータが転送される前に実行されます。ステートメントに `%s` が含まれる場合、`%s` は操作で参照されるテーブル名に置き換えられます。
+ `postactions` — 読み込み/書き込みに使用されます。SQL ステートメントは、AWS Glue と Snowflake 間でデータが転送された後に実行されます。ステートメントに `%s` が含まれる場合、`%s` は操作で参照されるテーブル名に置き換えられます。
+ `autopushdown` - デフォルト: `"on"`。有効な値: `"on"`、`"off"`。このパラメータは、自動クエリプッシュダウンを有効にするかどうかを制御します。プッシュダウンが有効になっている場合、Spark でクエリを実行すると、クエリの一部が Snowflake サーバーに「プッシュダウン」できる場合にクエリがプッシュダウンされます。これにより、一部のクエリのパフォーマンスが向上します。クエリをプッシュダウンできるかどうかについては、Snowflake ドキュメントの「[プッシュダウン](https://docs.snowflake.com/en/user-guide/spark-connector-use#pushdown)」を参照してください。
さらに、Snowflake Spark コネクタで使用できるオプションの一部が AWS Glue でサポートされている場合があります。Snowflake Spark コネクタで使用できるオプションの詳細については、Snowflake ドキュメントの「[コネクタの構成オプションの設定](https://docs.snowflake.com/en/user-guide/spark-connector-use#setting-configuration-options-for-the-connector)」を参照してください。
## Snowflake 認証方法
AWS Glue は、Snowflake に接続するために次の認証方法をサポートしています。
+ **基本認証:** `sfUser` および `sfPassword` パラメータを指定します。
+ **キーペア認証:** `sfUser` および `pem_private_key` パラメータを指定します。キーペア認証を使用する際、`sfPassword` パラメータは必要ありません。
+ **OAuth 認証:** Snowflake Connector は、Snowflake データへのアクセスをリクエストするための AUTHORIZATION\_CODE 許可タイプをサポートしています。この許可タイプは「3-legged OAuth (3 者間 OAuth)」と呼ばれます。アクセスを認証および承認できるサードパーティーの認可サーバーにユーザーをリダイレクトするためです。この方法は、AWS Glue コンソールを介して接続を作成するときに使用されます。
+ **前提条件:** この認証方法を使用するには、次の設定が完了していることを確認してください。
+ Snowflake の公式ドキュメント「[Configure Snowflake OAuth for custom clients (カスタムクライアント用に Snowflake OAuthを設定する)](https://docs.snowflake.com/en/user-guide/oauth-custom)」に従って、**カスタムクライアント用に Snowflake OAuth を設定**します。
+ Snowflake セキュリティ統合を作成するときに、**正しいリダイレクト URI を設定**します。例: DUB (eu-west-1) リージョンで接続を作成する場合、リダイレクト URI は次のようになります: `https://eu-west-1.console.aws.amazon.com/gluestudio/oauth`
+ セキュリティ統合を作成したら、Glue 接続の作成時に使用する次の情報を保持します。
+ OAUTH\_CLIENT\_ID: この値は、Glue 接続作成ページでユーザーマネージドクライアントアプリケーションクライアント ID として指定する必要があります。
+ OAUTH\_CLIENT\_SECRET: この値は、接続に使用される AWS シークレットのキー USER\_MANAGED\_CLIENT\_APPLICATION\_CLIENT\_SECRET に保存する必要があります。
+ OAuth スコープ — (オプション) Snowflake アカウントからリクエストされた特定のアクセス許可またはアクセスレベルを定義します。例えば、スコープは特定のリソースまたはオペレーションへのアクセスを制限する場合があります。
+ この値は、次の形式で指定できます: `session:role:Snowflake_Role_Name`
+ 例:`session:role:ANALYST_ROLE`
+ 認可コード URL — (必須) ユーザーがログインして認可を付与するようにリダイレクトされるエンドポイント。
+ 例:`https://host/oauth/authorize`
+ 認可トークン URL — (必須) 認可コードをアクセストークンと交換するために使用されるエンドポイント。
+ 例:`https://host/oauth/token-request`
+ ユーザーマネージドクライアントアプリケーションクライアント ID — (必須) Snowflake に登録された OAuth クライアントアプリケーションの一意の識別子
+ AWS シークレット — (必須) 次のキーと値のペアを含む AWS Secrets Manager シークレットを参照します:
+ sfUser - Snowflake ユーザー名
+ USER\_MANAGED\_CLIENT\_APPLICATION\_CLIENT\_SECRET - OAuth クライアントアプリケーションに関連付けられたクライアントシークレット
3 つの認証方法はすべて完全にサポートされており、接続オプション、Glue 接続、または AWS Secrets Manager シークレットの任意の組み合わせを使用して設定できます。
## Snowflake コネクタの制限事項
AWS Glue for Spark を使用してスノーフレークに接続することには、以下の制限があります。
+ このコネクタはジョブブックマークをサポートしていません。ブックマークの詳細については、「[ジョブのブックマークを使用した処理済みデータの追跡](monitor-continuations.md)」を参照してください。
+ このコネクタは、`create_dynamic_frame.from_catalog` および `write_dynamic_frame.from_catalog` メソッドを使用した AWS Glue データカタログのテーブルを介した Snowflake の読み込みと書き込みをサポートしていません。
+ このコネクタは、基本認証、キーペア認証、OAuth 認証をサポートしています。他の認証方法 (SAML など) は現在サポートされていません。
+ このコネクタはストリーミングジョブではサポートされていません。
+ このコネクタは、情報を取得する (`query` パラメータを使用してなど) 際の `SELECT` ステートメントベースのクエリをサポートします。他の種類のクエリ (`SHOW`、`DESC`、DML ステートメントなど) はサポートされていません。
+ Snowflake は、Snowflake クライアントを介して送信されるクエリテキスト (つまり、SQL ステートメント) のサイズをステートメントあたり 1 MB に制限しています。詳細については、「[クエリテキストサイズの制限](https://docs.snowflake.com/en/user-guide/query-size-limits)」を参照してください。