Amazon Athena Snowflake コネクタ

Snowflake 用の Amazon Athena コネクタを使用すると、Amazon Athena で Snowflake SQL または RDS インスタンスに保存されたデータに対して JDBC を使用して SQL クエリを実行できます。

このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。

前提条件

• Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「データソース接続を作成する」または「AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする」を参照してください。

制限

• DDL の書き込みオペレーションはサポートされていません。

• マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。

• 関連性のある Lambda 上限値。詳細については、AWS Lambda デベロッパーガイドの Lambda のクォータを参照してください。

• 現在、単一スプリットの Snowflake ビューがサポートされています。

• Snowflake では、オブジェクト名は大文字と小文字が区別されるため、2 つのテーブルに同じ名前が小文字と大文字で存在する場合があります (たとえば、EMPLOYEE と employee)。Athena のフェデレーティッドクエリでは、スキーマのテーブル名が小文字で Lambda 関数に渡されます。この問題を回避するには、クエリヒント @schemaCase を指定して、大文字と小文字が区別される名前のテーブルからデータを取得します。クエリヒントを含む 2 つのサンプルクエリを次に示します。

  SELECT *
                      FROM "lambda:snowflakeconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=upper"     

  SELECT *
                      FROM "lambda:snowflakeconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=lower"     

• Snowflake 接続を Glue Catalog と Lake Formation に移行する場合、Athena はすべてのリクエストをデフォルトで大文字にしたり、注釈をサポートしたりすることはありません。Glue 接続のデフォルトの動作では、大文字と小文字はそのまま維持されます。

  Snowflake は、次の大文字と小文字のモードをサポートしています。

  • NONE (Glue 接続のコネクタのデフォルト）

  • CASE_INSENSITIVE_SEARCH

  • ANNOTATION (Glue 接続のないコネクタのデフォルト）

用語

Snowflake コネクタに関連する用語を次に示します。

• データベースインスタンス – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。

• ハンドラー – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。

• メタデータハンドラー – データベースインスタンスからメタデータを取得する Lambda ハンドラー。

• レコードハンドラー – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。

• 複合ハンドラー — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。

• プロパティまたはパラメータ – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。

• 接続文字列 – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。

• カタログ – Athena に登録された AWS Glue ではないカタログ。これは、connection_string プロパティに必須のプレフィックスです。

• マルチプレックスハンドラー – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。

パラメータ

このセクションのパラメータを使用して Snowflake コネクタを設定します。

Glue connections (recommended)

Glue 接続オブジェクトを使用して Snowflake コネクタを設定することをお勧めします。そのためには、Snowflake コネクタ Lambda の glue_connection 環境変数を、使用する Glue 接続の名前に設定します。

Glue 接続プロパティ

次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。

aws glue describe-connection-type --connection-type SNOWFLAKE

Lambda 環境プロパティ

• glue_connection – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。

• casing_mode – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。casing_mode パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。

  • none – 指定されたスキーマ名とテーブル名の大文字と小文字は変更しないでください。これは、グルー接続が関連付けられているコネクタのデフォルトです。

  • annotation – 注釈が存在する場合、テーブル名を調整します。これは、グルー接続が関連付けられていないコネクタのデフォルトです。

  • case_insensitive_search – Snowflake のスキーマ名とテーブル名に対して大文字と小文字を区別しない検索を実行します。クエリにコネクタのデフォルトの大文字と小文字に一致しないスキーマ名またはテーブル名が含まれている場合は、この値を使用します。

  • upper – 指定されたすべてのスキーマ名とテーブル名を大文字にします。

  • lower – 指定されたすべてのスキーマ名とテーブル名を小文字にします。

注記

Glue 接続を使用して作成された Snowflake コネクタは、マルチプレックスハンドラーの使用をサポートしていません。

Legacy connections

注記

2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。

以下に示すパラメータ名と定義は、関連付けられた Glue 接続なしで作成された Athena データソースコネクタ用です。以下のパラメータは、Athena データソースコネクタの以前のバージョンを手動でデプロイする場合、または glue_connection 環境プロパティが指定されていない場合にのみ使用します。

Lambda 環境プロパティ

• default – Snowflake データベースインスタンスへの接続に使用する JDBC 接続文字列。例: snowflake://${jdbc_connection_string}

• catalog_connection_string – マルチプレックスハンドラーによって使用されます (Glue 接続を使用する場合はサポートされていません)。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mysnowflakecatalog の場合、環境変数の名前は mysnowflakecatalog_connection_string になります。

• spill_bucket – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。

• spill_prefix – (オプション) 指定された athena-federation-spill という spill_bucket の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 のストレージライフサイクルを設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。

• spill_put_request_headers – (オプション) スピリングに使用されるAmazon S3 の putObject リクエスト (例:{"x-amz-server-side-encryption" : "AES256"}) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「PutObject」を参照してください。

• kms_key_id – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば a7e63k4b-8loc-40db-a2a1-4d0en2cd8331) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。

• disable_spill_encryption – (オプション) True に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は False です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先でサーバー側の暗号化を使用している場合に、パフォーマンスが向上します。

接続文字列

次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。

snowflake://${jdbc_connection_string}

マルチプレックスハンドラーの使用

マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。

Handler	Class
複合ハンドラー	SnowflakeMuxCompositeHandler
メタデータハンドラー	SnowflakeMuxMetadataHandler
レコードハンドラー	SnowflakeMuxRecordHandler

マルチプレックスハンドラーのパラメータ

パラメータ	説明
$catalog_connection_string	必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mysnowflakecatalog の場合、環境変数の名前は mysnowflakecatalog_connection_string になります。
default	必須。デフォルトの接続文字列。この文字列は、カタログが lambda:${AWS_LAMBDA_FUNCTION_NAME} の場合に使用されます。

snowflake1 (デフォルト) と snowflake2 の 2 つのデータベースインスタンスをサポートする Snowflake MUX Lambda 関数用のプロパティを次に示します。

プロパティ	値
default	snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1&${Test/RDS/Snowflake1}
snowflake_catalog1_connection_string	snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1${Test/RDS/Snowflake1}
snowflake_catalog2_connection_string	snowflake://jdbc:snowflake://snowflake2.host:port/?warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2

認証情報の提供

JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。

• 接続文字列 – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。

  重要

  セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「AWS Secrets Manager ユーザーガイド」の「ハードコードされたシークレットを AWS Secrets Manager に移動する」を参照してください。

• AWS Secrets Manager – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するためのインターネットアクセスまたは VPC エンドポイントが、Lambda 関数に接続されている VPC に必要です。

  JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の username および password の値に置き換えます。

  Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。

  {"username": "${username}", "password": "${password}"}

シークレット名を含む接続文字列の例

次の文字列には、シークレット名 ${Test/RDS/Snowflake1} が含まれています。

snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1${Test/RDS/Snowflake1}&... 

次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。

snowflake://jdbc:snowflake://snowflake1.host:port/warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2&... 

現在、Snowflake は user と password の JDBC プロパティを認識します。また、ユーザー名とパスワードを、user や password のキーなしで、ユーザー名/パスワードの形式で受け付けます。

単一接続ハンドラーの使用

次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の Snowflake インスタンスに接続できます。

ハンドラーのタイプ	Class
複合ハンドラー	SnowflakeCompositeHandler
メタデータハンドラー	SnowflakeMetadataHandler
レコードハンドラー	SnowflakeRecordHandler

単一接続ハンドラーのパラメータ

パラメータ	説明
default	必須。デフォルトの接続文字列。

単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、default 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。

Lambda 関数でサポートされる単一の Snowflake インスタンス用のプロパティ例を次に示します。

プロパティ	値
default	snowflake://jdbc:snowflake://snowflake1.host:port/?secret=Test/RDS/Snowflake1

スピルパラメータ

Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。

パラメータ	説明
spill_bucket	必須。スピルバケット名。
spill_prefix	必須。スピルバケットのキープレフィックス
spill_put_request_headers	(オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:{"x-amz-server-side-encryption" : "AES256"}) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「PutObject」を参照してください。

サポートされるデータ型

次の表に、JDBC と Apache Arrow に対応するデータ型を示します。

JDBC	Arrow
ブール値	Bit
整数	Tiny
ショート	Smallint
整数	Int
Long	Bigint
フロート	Float4
ダブル	Float8
日付	DateDay
Timestamp	DateMilli
String	Varchar
バイト	Varbinary
BigDecimal	10 進数
配列	リスト

データ型変換

JDBC から Arrow への変換に加えて、コネクタは特定の別の変換を実行して Snowflake ソースと Athena データ型との互換性を保ちます。これらの変換は、クエリを正常に実行するのに役立ちます。次の表に、これらの変換を示します。

ソースデータ型 (Snowflake)	変換されたデータ型 (Athena)
TIMESTAMP	TIMESTAMPMILLI
DATE	TIMESTAMPMILLI
INTEGER	INT
DECIMAL	BIGINT
TIMESTAMP_NTZ	TIMESTAMPMILLI

その他のサポートされていないデータ型はすべて VARCHAR に変換されます。

パーティションと分割

パーティションは、コネクタを分割する方法を決定するために使用されます。Athena は varchar 型の合成列を作成し、コネクタが分割を生成できるようにするために、テーブルに対するパーティションのスキームを示します。コネクタは実際のテーブル定義を変更しません。

この合成列とパーティションを作成するには、Athena がプライマリキーの定義を要求します。ただし、Snowflake はプライマリキーの制約を強制しないため、ユーザー自身が一意性を強制する必要があります。これを行わなければ、Athena がデフォルトの単一分割を実行することになります。

パフォーマンス

最適なパフォーマンスを得るには、可能な限りクエリでフィルターを使用します。さらに、パーティション分散が均一な巨大なデータセットを取得するには、ネイティブパーティションを強くお勧めします。列のサブセットを選択すると、クエリランタイムが大幅に短縮され、スキャンされるデータが減ります。Snowflake コネクタは、同時実行によるスロットリングに強いです。

Athena Snowflake コネクタは述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。スキャンされるデータ量を削減し、クエリ実行のランタイムを短縮するために、LIMIT 句、単純な述語、および複雑な式はコネクタにプッシュダウンされます。

LIMIT 句

LIMIT N ステートメントにより、クエリによってスキャンされるデータが削減されます。LIMIT N プッシュダウンを使用すると、コネクタは N 行のみを Athena に返します。

述語

述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの WHERE 句内の式です。Athena Snowflake コネクタは、これらの式を組み合わせて Snowflake に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。

次の Athena Snowflake コネクタ演算子は、述語のプッシュダウンをサポートしています。

• ブーリアン: AND、OR、NOT

• 等値: EQUAL、NOT_EQUAL、LESS_THAN、LESS_THAN_OR_EQUAL、GREATER_THAN、GREATER_THAN_OR_EQUAL、IS_DISTINCT_FROM、NULL_IF、IS_NULL

• Arithmetic: ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE

• その他: LIKE_PATTERN、IN

組み合わせたプッシュダウンの例

クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。

SELECT * 
FROM my_table 
WHERE col_a > 10 
    AND ((col_a + col_b) > (col_c % col_d))
    AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%') 
LIMIT 10;

パススルークエリ

Snowflake コネクタは、パススルークエリをサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。

Snowflake でパススルークエリを使用するには、以下の構文を使用できます。

SELECT * FROM TABLE(
        system.query(
            query => 'query string'
        ))

以下のクエリ例は、Snowflake 内のデータソースにクエリをプッシュダウンします。クエリは customer テーブル内のすべての列を選択し、結果を 10 個に制限します。

SELECT * FROM TABLE(
        system.query(
            query => 'SELECT * FROM customer LIMIT 10'
        ))

ライセンス情報

このコネクタを使用することにより、pom.xml ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある LICENSE.txt ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。

追加リソース

最新の JDBC ドライバーのバージョン情報については、GitHub.com の Snowflake コネクタ用の pom.xml ファイルを参照してください。

このコネクタに関するその他の情報については、GitHub.com で対応するサイトを参照してください。