クエリ結果の場所の指定 Athena コンソールを使用したクエリ結果ファイルのダウンロード最近のクエリの表示 Simple Storage Service (Amazon S3) でのクエリ出力ファイルの検索

クエリ結果、最近のクエリ、および出力ファイルの使用

Amazon Athena は、Amazon S3 で指定できるクエリ結果の場所に、実行される各クエリのクエリ結果とメタデータ情報を自動的に保存します。必要に応じて、この場所にあるファイルにアクセスして操作できます。Athena コンソールからクエリ結果ファイルを直接ダウンロードすることもできます。

Amazon S3 にクエリ結果の場所を初めてセットアップするときは、「Athena コンソールを使用したクエリ結果の場所の指定」を参照してください。

出力ファイルは、実行されるすべてのクエリに対して自動的に保存されます。クエリ出力ファイルにアクセスして表示するには、IAM プリンシパル (ユーザーとロール) に、クエリ結果の場所に対する Amazon S3 の GetObject アクションの許可と、Athenaの GetQueryResults アクションの許可が必要です。クエリの結果の場所は暗号化できます。場所が暗号化されている場合、ユーザーには、クエリ結果の場所を暗号化および復号するための適切なキーアクセス許可が必要です。

重要

クエリ結果の場所に対する Amazon S3 の GetObject アクションの許可を持つ IAM プリンシパルは、Athena の GetQueryResults アクションの許可が拒否された場合でも、Amazon S3 からクエリ結果を取得できます。

クエリ結果の場所の指定

Athena が使用するクエリ結果の場所は、ワークグループの設定とクライアント側の設定の組み合わせによって決定されます。クライアント側の設定は、クエリの実行方法に基づいています。

Athena コンソールを使用してクエリを実行する場合は、ナビゲーションバーの [Settings] (設定) で入力した [Query result location] (クエリ結果の場所) がクライアント側の設定を決定します。
Athena API を使用してクエリを実行する場合は、StartQueryExecution アクションの OutputLocation パラメータがクライアント側の設定を決定します。
ODBC または JDBC ドライバーを使用してクエリを実行する場合、接続 URL で指定された S3OutputLocation プロパティによってクライアント側の設定が決まります。

重要

API または ODBC または JDBC ドライバーを使用してクエリを実行する場合、コンソールの設定は適用されません。

各ワークグループ設定には、[Override client-side settings (クライアント側設定の上書き)] オプションがあり、有効にできます。このオプションを有効にすると、そのワークグループに関連付けられている IAM プリンシパルがクエリを実行するときに、適切なクライアント側の設定よりもワークグループの設定が優先されます。

Athena コンソールを使用したクエリ結果の場所の指定

クエリを実行する前に、Amazon S3 のクエリ結果バケットの場所を指定しておく、または指定されたバケットがあり、その設定がクライアント設定を上書きするワークグループを使用する必要があります。

Athena コンソールを使用してクライアント側の設定のクエリ結果の場所を指定する

クエリ結果の場所を指定するワークグループに切り替えます。デフォルトのワークグループの名前は primary です。
ナビゲーションバーから [Settings] (設定) を選択します。
ナビゲーションバーで [Manage] (管理) を選択します。
[Manage settings] (設定の管理) で、以下のいずれかを実行します。
- [Location of query result] (クエリ結果の場所) ボックスで、クエリ結果のために Amazon S3 に作成したバケットへのパスを入力します。パスの先頭に s3:// を付けます。
- [Browse S3] (S3 をブラウズ) をクリックし、現在のリージョンで作成した Amazon S3 バケットを選択した上で、[Choose] (選択) をクリックします。
注記
ワークグループのすべてのユーザーに対してクエリ結果の場所を指定するワークグループを使用している場合、クエリ結果の場所を変更するオプションは使用できません。
(オプション) [View lifecycle configuration] (ライフサイクル設定を表示) を選択すると、クエリ結果バケットの [Amazon S3 lifecycle rules] (Amazon S3 ライフサイクルルール) を表示および設定できます。作成する Amazon S3 ライフサイクルルールは、有効期限ルールまたは移行ルールのいずれでも可能です。有効期限ルールでは、一定の時間が経過するとクエリ結果は自動的に削除されます。移行ルールは別の Amazon S3 ストレージ階層に移動します。詳細については、Amazon Simple Storage Service ユーザーガイドの「バケットのライフサイクル設定の指定」を参照してください。
(オプション) [Expected bucket owner] (想定されるバケット所有者) に、出力ロケーションバケットの所有者になると想定されている AWS アカウントの ID を入力します。これは追加のセキュリティ対策です。バケット所有者のアカウント ID がここで指定した ID と一致しない場合、バケットに出力できません。詳細については、「Amazon S3 ユーザーガイド」の「バケット所有者条件によるバケット所有者の確認」を参照してください。

注記
予期されるバケット所有者の設定は、Athena クエリの結果の出力先として指定した Amazon S3 内の場所にのみ適用されます。これは、外部 Simple Storage Service (Amazon S3) バケット内のデータソースの場所、CTAS や INSERT INTO の書き込み先のテーブルの場所、UNLOAD ステートメントの出力場所、串刺検索のバケットのスピルオペレーション、別のアカウントのテーブルに対して実行される SELECT クエリなど、他の Amazon S3 ロケーションには適用されません。
(オプション) Simple Storage Service (Amazon S3) に保存されているクエリ結果を暗号化するには、[Encrypt query results] (クエリ結果の暗号化) を選択します。Athena の暗号化に関する詳細については、保管中の暗号化を参照してください。
(オプション) クエリ結果バケットの ACL が有効になっているときに、バケット所有者にクエリ結果に対するフルコントロールアクセスを割り当てるには、[Assign bucket owner full control over query results] (クエリ結果に対する完全なコントロールをバケット所有者に付与する) を選択します。たとえば、クエリ結果の場所を別のアカウントが所有している場合に、クエリ結果の所有権とフルコントロールを他のアカウントに付与することができます。詳細については、Simple Storage Service (Amazon S3) ユーザーガイドのオブジェクトの所有権のコントロールとバケットに対する ACL の無効化を参照してください。
[Save] (保存) を選択します。

以前に作成されたデフォルトの場所

これまで Athena では、クエリ結果の場所の値を指定せずにクエリを実行し、クエリ結果の場所の設定がワークグループによって上書きされなかった場合は、Athena がデフォルトの場所を作成していました。デフォルトの場所は aws-athena-query-results-MyAcctID-MyRegion でした。MyAcctID はクエリを実行した IAM プリンシパルの Amazon Web Services アカウント ID で、MyRegion はクエリが実行されたリージョン (us-west-1 など) です。

今後は、以前に Athena を使用したことがないアカウントがあるリージョンで Athena クエリを実行する前に、クエリ結果の場所を指定するか、クエリ結果の場所の設定を上書きするワークグループを使用しなければならなくなります。Athena はデフォルトのクエリ結果の場所を作成しなくなりましたが、以前に作成されたデフォルトの aws-athena-query-results-MyAcctID-MyRegion の場所は引き続き有効で、使用を継続できます。

ワークグループを使用したクエリ結果の場所の指定

AWS Management Console、AWS CLI、または Athena API を使用して、ワークグループ設定でクエリ結果の場所を指定します。

AWS CLI を使用する場合、aws athena create-work-group または aws athena update-work-group コマンドを実行するときに --configuration オプションの OutputLocation パラメータを使用してクエリ結果の場所を指定します。

Athena コンソールを使用してワークグループのクエリ結果の場所を指定する

コンソールのナビゲーションペインが表示されない場合は、左側の展開メニューをクリックします。
ナビゲーションペインで、[Workgroups] (ワークグループ) を選択します。
ワークグループのリストで、編集するワークグループのリンクを選択します。
Edit (編集) を選択します。
クエリ結果の場所と暗号化については、次のいずれかを実行します。
- [Location of query result] (クエリ結果の場所) ボックスに、クエリ結果のために Amazon S3 のバケットへのパスを入力します。パスの先頭に s3:// を付けます。
- [Browse S3] (S3 のブラウズ) で、使用する現在のリージョン用の Amazon S3 バケットを選択し、[Choose] (選択) を選択します。
(オプション) [Expected bucket owner] (想定されるバケット所有者) に、出力ロケーションバケットの所有者になると想定されている AWS アカウントの ID を入力します。これは追加のセキュリティ対策です。バケット所有者のアカウント ID がここで指定した ID と一致しない場合、バケットに出力できません。詳細については、「Amazon S3 ユーザーガイド」の「バケット所有者条件によるバケット所有者の確認」を参照してください。

注記
予期されるバケット所有者の設定は、Athena クエリの結果の出力先として指定した Amazon S3 内の場所にのみ適用されます。これは、外部 Simple Storage Service (Amazon S3) バケット内のデータソースの場所、CTAS や INSERT INTO の書き込み先のテーブルの場所、UNLOAD ステートメントの出力場所、串刺検索のバケットのスピルオペレーション、別のアカウントのテーブルに対して実行される SELECT クエリなど、他の Amazon S3 ロケーションには適用されません。
(オプション) Simple Storage Service (Amazon S3) に保存されているクエリ結果を暗号化するには、[Encrypt query results] (クエリ結果の暗号化) を選択します。Athena の暗号化に関する詳細については、保管中の暗号化を参照してください。
(オプション) クエリ結果バケットの ACL が有効になっているときに、バケット所有者にクエリ結果に対するフルコントロールアクセスを割り当てるには、[Assign bucket owner full control over query results] (クエリ結果に対する完全なコントロールをバケット所有者に付与する) を選択します。たとえば、クエリ結果の場所を別のアカウントが所有している場合に、クエリ結果の所有権とフルコントロールを他のアカウントに付与することができます。

バケットの S3 オブジェクトの所有権の設定が [Bucket owner preferred] (バケット所有者推奨) となっている場合、バケット所有者は、このワークグループから書き込まれたすべてのクエリ結果オブジェクトも所有します。たとえば、外部アカウントのワークグループでこのオプションが有効になっており、そのクエリ結果の場所がアカウントの Simple Storage Service (Amazon S3) バケットに設定されている場合に、このバケットの S3 オブジェクトの所有権が [Bucket owner preferred] (バケット所有者推奨) と設定されていると、外部ワークグループのクエリ結果を所有し、フルコントロールアクセスを持つことになります。

クエリ結果バケットの S3 オブジェクトの所有権設定が [Bucket owner enforced] (バケット所有者の強制) となっているときにこのプションを選択しても、効果はありません。詳細については、Simple Storage Service (Amazon S3) ユーザーガイドのオブジェクトの所有権のコントロールとバケットに対する ACL の無効化を参照してください。
指定したクエリ結果の場所を使用するようにワークグループのすべてのユーザーに要求する場合は、[Settings] (設定) セクションまで下にスクロールして、[Override client-side settings ] (クライアント側設定の上書き) を選択します。
[Save changes] (変更の保存) を選択します。

Athena コンソールを使用したクエリ結果ファイルのダウンロード

クエリを実行した直後に、クエリペインからクエリ結果の CSV ファイルをダウンロードできます。最近のクエリ結果も、[Recent queries] (最近のクエリ) タブからダウンロードできます。

注記

Athena クエリ結果ファイルは、個々のユーザーによって設定できる情報を含むデータファイルです。このデータの読み取りと分析を行うプログラムの一部は、データの一部をコマンドと解釈する可能性があります (CSV インジェクション)。このため、クエリ結果の CSV データをスプレッドシートプログラムにインポートすると、そのプログラムから、セキュリティ上の問題について警告を受ける場合があります。システムを安全に保つには、ダウンロードされたクエリ結果からリンクまたはマクロを無効にするように常に選択する必要があります。

クエリを実行してクエリ結果をダウンロードするには

クエリエディタにクエリを入力し、[Run] (実行) をクリックします。

クエリの実行が終了すると、[Results (結果)] ペインにクエリ結果が表示されます。
クエリ結果の CSV ファイルをダウンロードするには、クエリ結果ペインの上にある [Download results] (結果のダウンロード) を選択します。ブラウザとブラウザの設定によっては、ダウンロードの確認が必要になる場合があります。

以前のクエリのクエリ結果ファイルをダウンロードするには

[Recent queries] (最近のクエリ) を選択します。
検索ボックスを使用してクエリを見つけ、クエリを選択してから、[Download results] (結果のダウンロード) を選択します。

注記
[Download results] (結果のダウンロード) オプションを使用して、手動で削除されたクエリ結果を取得したり、Amazon S3 ライフサイクルルールによって削除または別の場所に移動されたクエリ結果を取得したりすることはできません。

最近のクエリの表示

Athena コンソールを使用して、成功したクエリと失敗したクエリの表示、および失敗したクエリのエラー詳細の表示を行うことができます。Athena では、クエリ履歴が 45 日間保持されます。

Athena コンソールで最近のクエリを表示するには

https://console.aws.amazon.com/athena/ で Athena コンソールを開きます。
[Recent queries] (最近のクエリ) を選択します。[Recent queries] (最近のクエリ) タブには、実行された各クエリに関する情報が表示されます。
クエリエディタでクエリステートメントを開くには、クエリの実行 ID を選択します。
失敗したクエリの詳細を表示するには、クエリの [Failed] (失敗) リンクを選択します。

最近の複数のクエリを CSV ファイルにダウンロードする

Athena コンソールの [Recent queries] (最近のクエリ) タブを使用すると、1 つ以上の最近のクエリを CSV ファイルにエクスポートして、表形式で表示できます。ダウンロードしたファイルには、クエリ結果ではなく、SQL クエリ文字列自体とクエリに関するその他の情報が含まれています。エクスポートされるフィールドには、実行 ID、クエリ文字列のコンテンツ、クエリの開始時間、ステータス、実行時間、スキャンされたデータ量、使用されたクエリエンジンのバージョン、および暗号化方法が含まれます。最近のクエリを最大 500 個、または検索ボックスに入力した条件を使用してフィルター処理をした最大 500 個のクエリをエクスポートできます。

1 つ以上の最近のクエリを CSV ファイルにエクスポートするには

https://console.aws.amazon.com/athena/ で Athena コンソールを開きます。
[Recent queries] (最近のクエリ) を選択します。
(オプション) 検索ボックスを使用して、ダウンロードする最近のクエリを絞り込みます。
[Download CSV] を選択します。
ファイル保存のプロンプトで、[Save] (保存) を選択します。デフォルトのファイル名は、タイムスタンプによって続く Recent Queries です (例: Recent Queries 2022-12-05T16 04 27.352-08 00.csv)

最近のクエリ表示オプションの設定

表示する列やテキストの折り返しなど、[Recent queries] (最近のクエリ) タブのオプションを設定できます。

[Recent queries] (最近のクエリ) タブのオプションを設定するには

https://console.aws.amazon.com/athena/ で Athena コンソールを開きます。
[Recent queries] (最近のクエリ) を選択します。
オプションボタン (歯車のアイコン) を選択します。
[Preferences ] (設定) ダイアログボックスで、ページあたりの行数、行折り返しの動作、および表示する列を選択します。
[Confirm] (確認) を選択します。

クエリ履歴を 45 日より長く保持

クエリ履歴を 45 日より長く保持する場合は、クエリ履歴を取得して、Amazon S3 などのデータストアに履歴を保存できます。このプロセスを自動化するには、Athena および Amazon S3 の API アクションと CLI コマンドを使用できます。以下の手順は、これらのステップをまとめたものです。

クエリ履歴をプログラムで取得して保存するには

Athena の ListQueryExecutions API アクション、または list-query-executions CLI コマンドを使用して、クエリ ID を取得します。
Athena の GetQueryExecution API アクション、または get-query-execution CLI コマンドを使用して、ID に基づいた各クエリに関する情報を取得します。
Simple Storage Service (Amazon S3) の PutObject API アクション、または put-object CLI コマンドを使用して、その情報を Amazon S3 に保存します。

Simple Storage Service (Amazon S3) でのクエリ出力ファイルの検索

ワークグループでクエリが発生し、そのワークグループの設定がクライアント側の設定よりも優先される場合でない限り、クエリ出力ファイルは次のパスパターンで Amazon S3 サブフォルダに保存されます。ワークグループの設定がクライアント側の設定よりも優先される場合、クエリはワークグループによって指定された結果パスを使用します。


QueryResultsLocationInS3/[QueryName|Unsaved/yyyy/mm/dd/]

QueryResultsLocationInS3 は、ワークグループ設定またはクライアント側設定で指定されたクエリ結果の場所です。詳細については、このドキュメントで後述する「クエリ結果の場所の指定」を参照してください。
次のサブフォルダは、ワークグループ設定が結果パスよりも優先されていないコンソールから実行されるクエリに対してのみ作成されます。AWS CLI から実行されるクエリまたは Athena API を使用して実行されるクエリは、QueryResultsLocationInS3 に直接保存されます。
- QueryName は結果を保存するクエリの名前です。クエリが実行されたものの、保存されなかった場合は、Unsaved が使用されます。
- yyyy/mm/dd は、クエリが実行された日付です。

CREATE TABLE AS SELECT クエリに関連付けられたファイルは、上記のパターンの tables サブフォルダに保存されます。

クエリ出力ファイルの識別

ファイルは、クエリの名前、クエリ ID、およびクエリが実行された日付に基づいて、Amazon S3 のクエリ結果の場所に保存されます。各クエリのファイルは QueryID を使用して命名されます。QueryID は、クエリの実行時に Athena が各クエリに割り当てる一意の識別子です。

次のファイルタイプが保存されます。

ファイルタイプファイル命名パターン説明

ファイルタイプ	ファイル命名パターン	説明
クエリ結果ファイル	`QueryID.csv` `QueryID.txt`	DML クエリ結果ファイルはカンマ区切り値 (CSV) 形式で保存されます。 DDL クエリ結果は、プレーンテキストファイルとして保存されます。結果ファイルは、コンソールの使用時には [Results] (結果) ペインから、またはクエリの [History] (履歴) からダウンロードできます。詳細については、「Athena コンソールを使用したクエリ結果ファイルのダウンロード」を参照してください。
クエリメタデータファイル	`QueryID.csv.metadata` `QueryID.txt.metadata`	DML および DDL クエリメタデータファイルはバイナリ形式で保存され、人間が読めるものではありません。ファイル拡張子は、関連するクエリ結果ファイルに対応しています。Athena は、`GetQueryResults` アクションを使用してクエリ結果を読み取るときに、メタデータを使用します。これらのファイルは削除できますが、クエリに関する重要な情報が失われるため、お勧めしません。
データマニフェストファイル	`QueryID-manifest.csv`	データマニフェストファイルは、INSERT INTO クエリの実行時に Athena が Simple Storage Service (Amazon S3) データソースの場所に作成するファイルを追跡するために生成されます。クエリが失敗した場合、マニフェストはクエリが書き込むことを意図したファイルも追跡します。マニフェストは、失敗したクエリの結果として孤立したファイルを識別するのに役立ちます。

クエリ結果ファイル

QueryID.csv

QueryID.txt

DML クエリ結果ファイルはカンマ区切り値 (CSV) 形式で保存されます。

DDL クエリ結果は、プレーンテキストファイルとして保存されます。

結果ファイルは、コンソールの使用時には [Results] (結果) ペインから、またはクエリの [History] (履歴) からダウンロードできます。詳細については、「Athena コンソールを使用したクエリ結果ファイルのダウンロード」を参照してください。

クエリメタデータファイル

QueryID.csv.metadata

QueryID.txt.metadata

DML および DDL クエリメタデータファイルはバイナリ形式で保存され、人間が読めるものではありません。ファイル拡張子は、関連するクエリ結果ファイルに対応しています。Athena は、GetQueryResults アクションを使用してクエリ結果を読み取るときに、メタデータを使用します。これらのファイルは削除できますが、クエリに関する重要な情報が失われるため、お勧めしません。

データマニフェストファイル

QueryID-manifest.csv

データマニフェストファイルは、INSERT INTO クエリの実行時に Athena が Simple Storage Service (Amazon S3) データソースの場所に作成するファイルを追跡するために生成されます。クエリが失敗した場合、マニフェストはクエリが書き込むことを意図したファイルも追跡します。マニフェストは、失敗したクエリの結果として孤立したファイルを識別するのに役立ちます。

AWS CLI を使用してクエリ出力の場所とファイルを特定

AWS CLI を使用してクエリ出力の場所と結果ファイルを特定するには、次の例のように、aws athena get-query-execution コマンドを実行します。abc1234d-5efg-67hi-jklm-89n0op12qr34 をクエリ ID に置き換えます。


aws athena get-query-execution --query-execution-id abc1234d-5efg-67hi-jklm-89n0op12qr34

このコマンドにより、以下のような出力が返されます。各出力パラメータの説明については、AWS CLI コマンドリファレンスの「get-query-execution」を参照してください。


{
    "QueryExecution": {
        "Status": {
            "SubmissionDateTime": 1565649050.175,
            "State": "SUCCEEDED",
            "CompletionDateTime": 1565649056.6229999
        },
        "Statistics": {
            "DataScannedInBytes": 5944497,
            "DataManifestLocation": "s3://aws-athena-query-results-123456789012-us-west-1/MyInsertQuery/2019/08/12/abc1234d-5efg-67hi-jklm-89n0op12qr34-manifest.csv",
            "EngineExecutionTimeInMillis": 5209
        },
        "ResultConfiguration": {
            "EncryptionConfiguration": {
                "EncryptionOption": "SSE_S3"
            },
            "OutputLocation": "s3://aws-athena-query-results-123456789012-us-west-1/MyInsertQuery/2019/08/12/abc1234d-5efg-67hi-jklm-89n0op12qr34"
        },
        "QueryExecutionId": "abc1234d-5efg-67hi-jklm-89n0op12qr34",
        "QueryExecutionContext": {},
        "Query": "INSERT INTO mydb.elb_log_backup SELECT * FROM mydb.elb_logs LIMIT 100",
        "StatementType": "DML",
        "WorkGroup": "primary"
    }
}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

クエリプランの表示

クエリの結果を再利用する