# Amazon Athena DynamoDB コネクタ
Amazon Athena DynamoDB コネクタは、Amazon Athena が DynamoDB とやり取りすることを可能にして、テーブルを SQL でクエリできるようにします。[INSERT INTO](insert-into.md) などの書き込み操作はサポートされていません。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
アカウントで Lake Formation を有効にしている場合、AWS Serverless Application Repository でデプロイした Athena フェデレーション Lambda コネクタの IAM ロールには、Lake Formation での AWS Glue Data Catalog への読み取りアクセス許可が必要です。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
DynamoDB 接続を Glue Catalog と Lake Formation に移行すると、小文字のテーブル名と列名のみが認識されます。
## パラメータ
このセクションのパラメータを使用して DynamoDB コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して DynamoDB コネクタを設定することをお勧めします。そのためには、DynamoDB コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type DYNAMODB
```
**Lambda 環境プロパティ**
**glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された DynamoDB コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された DynamoDB コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、関連付けられた Glue 接続なしで作成された Athena データソースコネクタ用です。次のパラメータは、Athena データソースコネクタの以前のバージョンを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合、または `glue_connection` 環境プロパティが指定されていない場合にのみ使用します。
**Lambda 環境プロパティ**
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (例えば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **disable\$1glue** – (オプション) これが存在し、true に設定されている場合、コネクタは AWS Glue からの補足メタデータ取得は試みません。
+ **glue\$1catalog** – (オプション) [クロスアカウントの AWS Glue カタログ](data-sources-glue-cross-account.md)を指定するために、このオプションを使用します。デフォルトでは、コネクタは自身の AWS Glue アカウントからメタデータを取得しようとします。
+ **disable\$1projection\$1and\$1casing** – (オプション) プロジェクションおよび大文字と小文字の区別を無効にします。列名に大文字と小文字の区別がある DynamoDB テーブルをクエリしたいものの、AWS Glue テーブルで `columnMapping` プロパティを指定したくない場合に使用します。
`disable_projection_and_casing` パラメータは、次の値を使用して大文字と小文字の区別、および列のマッピングに関する動作を指定します。
+ **auto** – これまでサポートされていなかったタイプが検出され、列名のマッピングがテーブルに設定されていない場合、プロジェクション、および大文字と小文の区別を無効にします。これはデフォルトの設定です。
+ **always** – プロジェクション、および大文字と小文字の区別を無条件に無効にします。これは、DynamoDB の列名で大文字と小文字を区別しているものの、列名のマッピングを指定したくない場合に便利です。
`disable_projection_and_casing` パラメータを使用する場合は、次の点に注意してください。
+ このパラメータを使用すると、帯域幅の使用量が増加する可能性があります。さらに、Lambda 関数がデータソースと同じ AWS リージョン にない場合、帯域幅の使用量が増えるため、標準の AWS クロスリージョン転送コストが高くなります。クロスリージョン転送コストの詳細については、「AWS Partner Network ブログ」の「[サーバーアーキテクチャおよびサーバーレスアーキテクチャの AWS データ転送料金](https://aws.amazon.com/blogs/apn/aws-data-transfer-charges-for-server-and-serverless-architectures/)」を参照してください。
+ 転送されるバイト数が増え、またバイト数が多いと逆シリアル化により時間がかかるため、全体のレイテンシが長くなる可能性があります。
## AWS Glueでのデータベースとテーブルのセットアップ
コネクタに組み込まれたスキーマ推論機能には制限があるため、メタデータ用としては AWS Glue の使用が適しています。これを行うには、AWS Glue にデータベースとテーブルが必要です。DynamoDB で使用できるようにするには、そのプロパティを編集する必要があります。
**AWS Glue コンソールでデータベースプロパティを編集するには**
1. AWS マネジメントコンソール にサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)) を開きます。
1. ナビゲーションペインで、**[データカタログ]** を展開し、**[データベース]** を選択します。
**[Databases]** (データベース) ページでは、既存のデータベースを編集するか、**[Add database]** (データベースを追加) を選択してデータベースを作成できます。
1. データベースのリストで、編集するデータベース用リンクを選択します。
1. **[編集]** を選択します。
1. **[Update a database]** ページの **[データベース設定]** の下で、**[ロケーション]** に、文字列 **dynamo-db-flag** を追加します。このキーワードは、Athena DynamoDB コネクタが補足メタデータに使用しているテーブルがデータベースに含まれており、`default` 以外の AWS Glue データベースに必要であることを示します。`dynamo-db-flag` プロパティは、多数のデータベースを持つアカウントのデータベースを除外する場合に便利です。
1. **[Update Database]** (データベースの更新) を選択します。
**AWS Glue コンソールでテーブルプロパティを編集するには**
1. AWS マネジメントコンソール にサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)) を開きます。
1. ナビゲーションペインで、**[データカタログ]** を展開し、**[テーブル]** を選択します。
1. **[テーブル]** ページのテーブルのリストで、編集するテーブルのリンク名を選択します。
1. **[Actions]** (アクション)、**[Edit table]** (テーブルの編集) の順に選択します。
1. **[Edit table]** (テーブルの編集) ページの **[Table properties]** (テーブルプロパティ) セクションで、必要に応じて次のテーブルプロパティを追加します。AWS Glue DynamoDB クローラーを使用する場合、これらのプロパティは自動的に設定されます。
+ **dynamodb** – テーブルを補足メタデータとして使用できることを Athena DynamoDB コネクタに示す文字列。**[Classification]** (分類) (完全一致) と呼ばれるフィールドにある、テーブルプロパティの `dynamodb` 文字列を入力します。
**注記**
AWS Glue コンソールのテーブル作成プロセスの一部である **[テーブルプロパティの設定]** ページには、**[分類]** フィールドを含む **[データ形式]** セクションがあります。ここでは `dynamodb` を入力も選択もできません。代わりに、テーブルを作成した後、手順に従ってテーブルを編集し、**[テーブルプロパティ]** セクションにキー値のペアとして `classification` および `dynamodb` を入力します。
+ **sourceTable** – DynamoDB 内にあるソーステーブル名を定義するオプションのテーブルプロパティ。AWS Glue テーブルの命名規則が原因で、DynamoDB テーブルと同じ名前で AWS Glue テーブルが作成できない場合に使用します。例えば、AWS Glue テーブルの名前に大文字は許可されていませんが、DynamoDB テーブル名としては使用が可能です。
+ **columnMapping** – カラム名のマッピングを定義するオプションのテーブルプロパティ。AWS Glue 列の命名規則が原因で、DynamoDB テーブルと同じ名前の列を持つ AWS Glue テーブルを作成できない場合に使用します。例えば、AWS Glue では列名として大文字は許可されていませんが、DynamoDB の列名では使用が可能です。このプロパティ値の形式は、col1=Col1、col2=Col2 のようにします。列マッピングは最上位の列名にのみ適用され、ネストされたフィールドには適用されないことに注意してください。
+ **defaultTimeZone** – 明示的なタイムゾーンが含まれない `date` 値、および `datetime` 値に適用される、オプションのテーブルプロパティ。データソースのデフォルトタイムゾーンと Athena セッションのタイムゾーンの間に不一致が生じないようにするためには、この値を設定することが適切です。
+ **datetimeFormatMapping** – AWS Glue `date` または `timestamp` データ型の列のデータを解析する際に、`date` または `datetime` 形式が使用されること指定する、オプションのテーブルプロパティ。このプロパティが指定されていない場合、コネクタは ISO-8601 形式が使用されるものと[推定](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/time/DateFormatUtils.html)します。コネクタが `date` または `datetime` 形式を推定できない、あるいは未加工の文字列を解析できない場合、この値は結果から除外されます。
`datetimeFormatMapping` 値は、`col1=someformat1,col2=someformat2` 形式である必要があります。次に形式の例をいくつか示します。
```
yyyyMMdd'T'HHmmss
ddMMyyyy'T'HH:mm:ss
```
列にタイムゾーンのない `date` または `datetime` 値が含まれており、その列を `WHERE` 句で使用したい場合には、対象の列で `datetimeFormatMapping` プロパティを設定します。
1. 手動で列を定義する場合は、適切なデータ型を使用するように注意してください。クローラーを使用している場合は、クローラーが検出した列とタイプを確認します。
1. **[保存]** を選択します。
## 必要な許可
このコネクタが必要とする IAM ポリシーの完全な詳細については、[athena-dynamodb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-dynamodb/athena-dynamodb.yaml) ファイルの `Policies` セクションを参照してください。次のリストは、必要なアクセス許可をまとめたものです。
+ **Amazon S3 への書き込みアクセス** – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス許可を必要とします。
+ **Athena GetQueryExecution** – コネクタはこの許可を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。
+ **AWS Glue Data Catalog** – DynamoDB コネクタには、スキーマ情報を取得するために、AWS Glue Data Catalog に対する読み込み専用アクセスが必要です。
+ **CloudWatch Logs** – コネクタは、ログを保存するために CloudWatch Logs にアクセスする必要があります。
+ **DynamoDB 読み込みアクセス** – このコネクタでは、`DescribeTable`、`ListSchemas`、`ListTables`、`Query`、および `Scan` のAPI オペレーションを使用します。
## パフォーマンス
Athena DynamoDB コネクタは並列スキャンをサポートしており、DynamoDB クエリの一部として述語のプッシュダウンを試みます。`X` が異なる値を持つハッシュキー述語を使用すると、DynamoDB に対する `X` クエリ呼び出しが発生します。他のすべての述語シナリオでは、スキャン呼び出しの数が `Y` となります。この際 `Y` は、テーブルのサイズとプロビジョニングされたスループットに基づいて、ヒューリスティックに決定されます。ただし、列のサブセットを選択すると、クエリのランタイムが長くなる場合があります。
`LIMIT` 句と単純な述語がプッシュダウンされるため、スキャンされるデータの量が減少し、クエリ実行のランタイムの短縮につながります。
### LIMIT 句
`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。機能を強化し、スキャンされるデータの量を減らすために、Athena DynamoDB コネクタはこれらの式を組み合わせて、DynamoDB に直接プッシュできます。
次の Athena DynamoDB コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10 and col_b < 10
LIMIT 10
```
DynamoDB などのフェデレーテッドクエリのパフォーマンスを向上させるために述語プッシュダウンを使用する方法の記事については、「*AWS Big Data Blog*」の「[Improve federated queries with predicate pushdown in Amazon Athena](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)」を参照してください。
## パススルークエリ
DynamoDB コネクタは[パススルークエリ](federated-query-passthrough.md)をサポートし、PartiQL 構文を使用します。DynamoDB [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html) API オペレーションはサポートされません。PartiQL を使用した DynamoDB のクエリに関する詳細については、「*Amazon DynamoDB デベロッパーガイド*」の「[PartiQL select statements for DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html)」を参照してください。
DynamoDB でパススルークエリを使用するには、次の構文を使用します。
```
SELECT * FROM TABLE(
system.query(
query => 'query_string'
))
```
次の DynamoDB パススルークエリ例は、PartiQL を使用して、2022 年 12 月 24 日より後の `DateWatched` プロパティを持つ Fire TV Stick デバイスのリストを返します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT Devices
FROM WatchList
WHERE Devices.FireStick.DateWatched[0] > '12/24/22''
))
```
## トラブルシューティング
### ソートキー列上の複数フィルター
**エラーメッセージ**: KeyConditionExpression にはキーごとに 1 つの条件のみを含める必要があります
**原因**: この問題は、Athena エンジンバージョン 3 で、DynamoDB ソートキー列上に下限フィルターと上限フィルターの両方があるクエリで発生する可能性があります。DynamoDB はソートキー上で複数のフィルター条件をサポートしていないため、両方の条件が適用されたクエリをコネクタがプッシュダウンしようとするとエラーが発生します。
**解決策**: コネクタをバージョン 2023.11.1 以降に更新します。コネクタを更新する手順については、「[データソースコネクタを更新する](connectors-updating.md)」を参照してください。
## コスト
コネクタの使用料金は、基礎として使用されている AWS リソースによって異なります。スキャンを使用するクエリでは、大量の[リードキャパシティーユニット (RCU)](https://aws.amazon.com/dynamodb/pricing/provisioned/) を利用することがあるため、「[Amazon DynamoDB pricing」](https://aws.amazon.com/dynamodb/pricing/) (Amazon DynamoDB の料金) に記載された情報を慎重に検討してください。
## その他のリソース
+ Amazon Athena DynamoDB コネクタの使用方法の概要については、「*AWS Prescriptive Guidance Patterns*」ガイドの「[Access, query, and join Amazon DynamoDB tables using Athena](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/access-query-and-join-amazon-dynamodb-tables-using-athena.html)」を参照してください。
+ Athena DynamoDB コネクタを使用して SQL で DynamoDB 内のデータをクエリし、Quick 内のインサイトを視覚化する方法については、AWS Big Data Blog 記事「[Visualize Amazon DynamoDB insights in Quick using the Amazon Athena DynamoDB connector and AWS Glue](https://aws.amazon.com/blogs/big-data/visualize-amazon-dynamodb-insights-in-amazon-quicksight-using-the-amazon-athena-dynamodb-connector-and-aws-glue/)」を参照してください。
+ Amazon Athena DynamoDB コネクタを、Amazon DynamoDB、Athena、Quick と共に使用して、シンプルなガバナンスダッシュボードを作成する方法については、「*AWS Big Data Blog*」の記事「[Query cross-account Amazon DynamoDB tables using Amazon Athena Federated Query](https://aws.amazon.com/blogs/big-data/query-cross-account-amazon-dynamodb-tables-using-amazon-athena-federated-query/)」を参照してください。
+ このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-dynamodb)を参照してください。