# Amazon Athena DocumentDB コネクタ Amazon Athena DocumentDB コネクタは、Athena と DocumentDB インスタンスとの通信を可能にします。これにより、DocumentDB データを SQL でクエリできるようになります。また、このコネクタは、MongoDB と互換性のある任意のエンドポイントでも機能します。 従来のリレーショナルデータストアとは異なり、Amazon DocumentDB コレクションには設定されたスキーマがありません。DocumentDB にはメタデータストアはありません。DocumentDB コレクションの各エントリには、さまざまな種類のフィールドとデータ型を含めることが可能です。 DocumentDB コネクタは、テーブルのスキーマ情報を生成するための 2 つのメカニズム (基本スキーマ推論と AWS Glue Data Catalog メタデータ) をサポートしています。 デフォルトでは、スキーマ推論が選択されます。このオプションは、コレクション内で少数のドキュメントをスキャンした上で、すべてのフィールドを結合して、重複しないデータ型を持つフィールドのみを選択的に使用します。このオプションは、ほとんどのエントリが同一であるコレクションに適しています。 より多くのデータ型を持つコレクションに対して、このコネクタでは、AWS Glue Data Catalog からのメタデータの取得をサポートします。DocumentDB データベースとコレクションの名前と一致する AWS Glue データベースおよびテーブルを認識した場合、このコネクタは、対応する AWS Glue テーブルからスキーマ情報を取得します。AWS Glue テーブルを作成する際には、DocumentDB コレクションからのアクセス対象となる、すべてのフィールドのスーパーセットを作成することをお勧めします。 アカウントで Lake Formation を有効にしている場合、AWS Serverless Application Repository でデプロイした Athena フェデレーション Lambda コネクタの IAM ロールには、Lake Formation での AWS Glue Data Catalog への読み取りアクセス許可が必要です。 このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。 ## 前提条件 + Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。 ## パラメータ このセクションのパラメータを使用して DocumentDB コネクタを設定します。 **注記** 2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。 以下に示すパラメータ名と定義は、2024 年 12 月 3 日より前に作成された Athena データソースコネクタ用です。これらは、対応する [AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)とは異なる場合があります。2024 年 12 月 3 日以降、以前のバージョンの Athena データソースコネクタを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合にのみ、以下のパラメータを使用します。 ### Glue 接続 (推奨) Glue 接続オブジェクトを使用して DocumentDB コネクタを設定することをお勧めします。そのためには、DocumentDB コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。 **Glue 接続プロパティ** 次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。 ``` aws glue describe-connection-type --connection-type DOCUMENTDB ``` **Lambda 環境プロパティ** + **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。 **注記** Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。 Glue 接続を使用して作成された DocumentDB コネクタは、マルチプレックスハンドラーの使用をサポートしていません。 Glue 接続を使用して作成された DocumentDB コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。 ### レガシー接続 + **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 アカウントからメタデータを取得しようとします。 + **default\$1docdb** – これが存在する場合は、カタログ固有の環境変数が存在しない場合に使用する、DocumentDB の接続文字列を指定します。 + **disable\$1projection\$1and\$1casing** – (オプション) プロジェクションおよび大文字と小文字の区別を無効にします。大文字と小文字が区別される列名を使用する Amazon DocumentDB テーブルをクエリする場合に使用します。`disable_projection_and_casing` パラメータは、次の値を使用して大文字と小文字の区別、および列のマッピングに関する動作を指定します。 + **false** – これは、デフォルトの設定です。プロジェクションが有効になっていて、コネクタはすべての列の名前が小文字であると想定します。 + **true** – プロジェクションおよび大文字と小文字の区別を無効にします。`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/)」を参照してください。 + 転送されるバイト数が増えたため、またバイト数が多いと逆シリアル化により時間がかかるため、全体のレイテンシーが増える可能性があります。 + **enable\$1case\$1insensitive\$1match** – (オプション) `true` の場合、Amazon DocumentDB 内のスキーマ名とテーブル名に対して大文字と小文字を区別する検索を実行します。デフォルトは `false` です。クエリに大文字のスキーマ名またはテーブル名が含まれる場合に使用します。 #### 接続文字列の指定 コネクタで使用する DocumentDB インスタンスの DocumentDB 接続の詳細を定義するために、複数のプロパティを指定できます。そのためには、Athena で使用するカタログ名と対応した Lambda の環境変数を設定します。例えば、2 つの異なる DocumentDB インスタンスに対し、Athena から次のクエリを実行するとします。 ``` SELECT * FROM "docdb_instance_1".database.table ``` ``` SELECT * FROM "docdb_instance_2".database.table ``` これら 2 つの SQL ステートメントを使用する際には、Lambda 関数 (`docdb_instance_1` および `docdb_instance_2`) に、2 つの環境変数を追加しておく必要があります。それぞれの値は、次の形式の DocumentDB 接続文字列にする必要があります。 ``` mongodb://:@:/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0 ``` ##### シークレットの使用 オプションで、接続文字列の詳細の一部またはすべての値について、AWS Secrets Manager を使用できます。Athena フェデレーティッドクエリ機能を Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。 Secrets Manager が提供するシークレット名を接続文字列に入れるために `${my_secret}` 構文を使用する場合、コネクタは `${my_secret}` を Secrets Manager のプレーンテキスト値にそのまま置き換えます。シークレットは、`:` 値付きのプレーンテキストのシークレットとして保存する必要があります。`{username:,password:}` として保存されたシークレットは接続文字列に正しく渡されません。 シークレットは接続文字列全体に使用することもでき、ユーザー名とパスワードはシークレット内で定義できます。 例えば、`docdb_instance_1` で Lambda 環境変数を次の値に設定した場合を考えます。 ``` mongodb://${docdb_instance_1_creds}@myhostname.com:123/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0 ``` Athena Query Federation SDK は、自動的に `docdb_instance_1_creds` という名前のシークレットを Secrets Manager から取得しよう試み、取得した値は `${docdb_instance_1_creds}` の場所に挿入します。接続文字列の中で、`${ }` 文字の組み合わせにより囲まれている任意の部分は、Secrets Manager から提供されたシークレットとして認識されます コネクタにより Secrets Manager 内で検出されないシークレット名を指定した場合、コネクタはテキストを置き換えません。 ## 補足メタデータの取得 補足メタデータを取得するには、以下の手順に従って Glue データベースとテーブルを設定します。 ### Glue データベースをセットアップする 1. DocumentDB コレクションと同じ名前の Glue データベースを作成します。 1. [ロケーション URI] フィールドに「`docdb-metadata-flag`」と入力します。 ### Glue テーブルを設定する Glue テーブルに次のパラメータを追加します。 + `docdb-metadata-flag = true` + `columnMapping = apple=APPLE` この例では、`apple` は Glue 内の小文字の列名を表し、`APPLE` は DocumentDB コレクション内の実際の大文字と小文字が区別される列名を表します。 ### メタデータの取得を検証する 1. クエリを実行します。 1. メタデータの取得が成功したかどうかは、Lambda 関数の CloudWatch ログで確認します。取得に成功すると、次のログエントリが表示されます。 ``` doGetTable: Retrieved schema for table[TableName{schemaName=test, tableName=profiles}] from AWS Glue. ``` **注記** テーブルに既に `columnMapping` フィールドが設定されている場合は、テーブルプロパティに `docdb-metadata-flag = true` パラメータを追加するだけで済みます。 ## AWS Glue でのデータベースとテーブルのセットアップ コネクタに組み込まれているスキーマ推論機能がスキャンするドキュメント数には制限があり、また、データ型のサブセットのみをサポートするため、メタデータ用としては AWS Glue の使用が適しています。 Amazon DocumentDB で使用するために AWS Glue テーブルを有効にするには、DocumentDB データベース向けの AWS Glue データベーステーブルと、補足メタデータを提供する先のコレクションを用意しておく必要があります。 **補足メタデータのために AWS Glue を使用するには** 1. AWS Glue コンソールを使用して、Amazon DocumentDB データベース名と同じ名前の AWS Glue データベースを作成します。 1. **docdb-metadata-flag** が含まれるようにデータベースの URI プロパティを設定します。 1. (オプション) **sourceTable** テーブルプロパティを追加します。このプロパティは、Amazon DocumentDB 内にあるソーステーブル名を定義します。AWS Glue テーブルの名前が Amazon DocumentDB のテーブル名と異なる場合は、このプロパティを使用します。AWS Glue と Amazon DocumentDB の命名規則の違いにより、これが必要になる場合があります。例えば、AWS Glue テーブルの名前には大文字が使用できませんが、Amazon DocumentDB テーブル名としては使用が可能です。 1. (オプション) **columnMapping** テーブルプロパティを正しく追加します。このプロパティは列名のマッピングを定義します。AWS Glue 列の命名規則が原因で、Amazon DocumentDB テーブルと同じ名前の列名を持つ AWS Glue テーブルを作成できない場合は、このプロパティを使用します。Amazon DocumentDB の列名には大文字を使用できますが、AWS Glue 列名には使用できないため、このプロパティは有用です。 `columnMapping` プロパティの値は、`col1=Col1,col2=Col2` 形式のマッピングのセットであることが想定されます。 **注記** 列マッピングは最上位の列名にのみ適用され、ネストされたフィールドには適用されません。 AWS Glue`columnMapping` テーブルプロパティを正しく追加した後に、`disable_projection_and_casing` Lambda 環境変数を削除できます。 1. このドキュメントに記載されているとおり、AWS Glue 用として適切なデータ型を使用しているか確認してください。 ## サポートされるデータ型 このセクションでは、DocumentDB コネクタがスキーマ推論に使用するデータ型と、AWS Glue メタデータが使用されている場合のデータ型を一覧で示します。 ### スキーマ推論のデータ型 DocumentDB コネクタのスキーマ推論機能は、値を次のいずれかのデータ型に属するものとして推測しようとします。この表では、Amazon DocumentDB、Java、および Apache Arrow に対応させてデータ型を示しています。 **** | Apache Arrow | Java または DocDB | | --- | --- | | VARCHAR | String | | INT | 整数 | | BIGINT | Long | | BIT | ブール値 | | FLOAT4 | 浮動小数点数 | | FLOAT8 | Double | | TIMESTAMPSEC | 日付 | | VARCHAR | ObjectId | | LIST | リスト | | STRUCT | ドキュメント | ### AWS Glue データ型 補足的メタデータ用として AWS Glue を使用する場合は、次のデータ型を設定できます。この表では、AWS Glue と Apache Arrow に対応するデータ型を示しています。 **** | AWS Glue | Apache Arrow | | --- | --- | | int | INT | | bigint | BIGINT | | double | FLOAT8 | | float | FLOAT4 | | boolean | BIT | | バイナリ | VARBINARY | | string | VARCHAR | | リスト | LIST | | Struct | STRUCT | ## 必要な許可 このコネクタが必要とする IAM ポリシーの完全な詳細については、[athena-docdb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-docdb/athena-docdb.yaml) ファイルの `Policies` セクションを参照してください。次のリストは、必要なアクセス許可をまとめたものです。 + **Amazon S3 への書き込みアクセス** – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス許可を必要とします。 + **Athena GetQueryExecution** – コネクタはこの許可を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。 + **AWS Glue Data Catalog** – DocumentDB コネクタには、スキーマ情報を取得するために、AWS Glue Data Catalog からの読み込み専用アクセスが必要です。 + **CloudWatch Logs** – コネクタは、ログを保存するために CloudWatch Logs にアクセスする必要があります。 + **AWS Secrets Manager 読み込みアクセス** – DocumentDB エンドポイントの詳細を Secrets Manager に保存する場合は、それらのシークレットに対するアクセス許可をコネクタに付与する必要があります。 + **VPC アクセス** – コネクタには、VPC に接続して DocumentDB インスタンスと通信するために、その VPC に対しインターフェイスをアタッチおよびデタッチする機能が必要です。 ## パフォーマンス Athena Amazon DocumentDB コネクタは現在、並列スキャンをサポートしていませんが、DocumentDB クエリの一部として述語をプッシュダウンしようとし、DocumentDB コレクションへのインデックスに対する述語は、スキャンされるデータが大幅に少なくなります。 Lambda 関数は、クエリがスキャンするデータを削減するために、射影プッシュダウンを実行します。ただし、列のサブセットを選択した場合は、クエリのランタイムが長くなることがあります。`LIMIT` 句はスキャンされるデータ量を削減しますが、述語を提供しない場合、`LIMIT` 句を含む `SELECT` クエリは少なくとも 16 MB のデータをスキャンすることを想定する必要があります。 ## パススルークエリ Athena Amazon DocumentDB コネクタは[パススルークエリ](federated-query-passthrough.md)をサポートしており、NoSQL ベースです。Amazon DocumentDB のクエリについては、「*Amazon DocumentDB 開発者ガイド*」の「[クエリ](https://docs.aws.amazon.com/documentdb/latest/developerguide/querying.html)」を参照してください。 Amazon DocumentDB でパススルークエリを使用するには、次の構文を使用します。 ``` SELECT * FROM TABLE( system.query( database => 'database_name', collection => 'collection_name', filter => '{query_syntax}' )) ``` 次の例は、`TPCDS` コレクション内の `example` データベースをクエリし、「*Bill of Rights*」というタイトルのすべての書籍をフィルタリングします。 ``` SELECT * FROM TABLE( system.query( database => 'example', collection => 'tpcds', filter => '{title: "Bill of Rights"}' )) ``` ## その他のリソース + [Amazon Athena のフェデレーティッドクエリ](federated-queries.md)を使用して、MongoDB データベースを [Quick](https://aws.amazon.com/quicksight/) に接続し、ダッシュボードとビジュアライゼーションを構築する方法の記事については、「*AWS ビッグデータブログ*」の「[Visualize MongoDB data from Quick using Amazon Athena Federated Query](https://aws.amazon.com/blogs/big-data/visualize-mongodb-data-from-amazon-quicksight-using-amazon-athena-federated-query/)」を参照してください。 + このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-docdb)を参照してください。