クエリ結果、出力ファイル、クエリ履歴の使用 - Amazon Athena

クエリ結果、出力ファイル、クエリ履歴の使用

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

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

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

重要

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

クエリ ID の取得

実行される各クエリはクエリ実行と呼ばれます。クエリ実行には、クエリ ID またはクエリ実行 ID と呼ばれる一意の識別子があります。クエリ結果ファイルを操作し、クエリ結果ファイルをすばやく見つけるには、クエリ ID が必要です。このトピックでは、クエリ ID を QueryID と呼びます。

実行されるクエリの QueryID を取得するために Athena コンソールを使用する

  1. ナビゲーションバーから [History] (履歴) を選択します。

    
                        Athena コンソールでクエリ履歴を表示します。
  2. クエリのリストから、[State] (状態) にあるクエリステータス ([Succeeded] (成功) など) を選択します。クエリ ID がツールチップに表示されます。

    
                        Athena コンソールの [History] (履歴) タブでクエリ ID を表示します。
  3. [Query ID] (クエリ ID) の横にあるアイコンをクリックして、ID をクリップボードにコピーします。

    
                        Athena コンソールの [History] (履歴) タブでクエリ ID をクリップボードにコピーします。

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 が 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" } }

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

クエリを実行した直後に、またはクエリの [History (履歴)] を使用して、クエリペインからクエリ結果の CSV ファイルをダウンロードできます。

注記

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

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

  1. クエリエディタにクエリを入力し、[Run query (クエリの実行)] を選択します。

    クエリの実行が終了すると、[Results (結果)] ペインにクエリ結果が表示されます。

  2. クエリ結果ファイルをダウンロードするには、クエリ結果ペインでファイルアイコンを選択します。ブラウザとブラウザの設定によっては、ダウンロードの確認が必要になる場合があります。

    
                        Athena コンソールでクエリ結果を .csv ファイルに保存します。

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

  1. [History (履歴)] を選択します。

  2. クエリが見つかるまで、クエリのリストを確認していきます。クエリが見つかれば、そのクエリの [Action] (アクション) で [Download results] (結果のダウンロード) を選択します。

クエリ結果の場所の指定

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 コンソールを使用してクライアント側の設定のクエリ結果の場所を指定する

  1. クエリ結果の場所を指定するワークグループに切り替えます。デフォルトのワークグループの名前は primary です。

  2. ナビゲーションパネルから [Settings] (設定) をクリックします。

  3. クエリ結果の場所と暗号化については、次のいずれかを実行します。

    • [選択] をクリックし、既存の Amazon S3 フォルダへのパスを選択します。

    • 末尾のスラッシュを含む、Amazon S3 フォルダへのパスを入力します。バケットやフォルダが存在しない場合、最初にクエリを実行したときに Athena が自動的に作成します。

      注記

      末尾にスラッシュを含めてください。末尾のスラッシュが含められていない場合は、「Invalid S3 folder location」エラーが発生します。

    入力する Amazon S3 の場所は、後続のクエリに使用されます。必要に応じて、この場所は後で変更できます。

    
                            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 コンソールを使用してワークグループのクエリ結果の場所を指定する

  1. ナビゲーションで [Workgroup (ワークグループ): CurrentWorkgroupName] をクリックします。

  2. 次のいずれかを行ってください。

    • 既存のワークグループを編集する場合は、リストからそのワークグループを選択し、[View details (詳細を表示)]、[Edit Workgroup (ワークグループの編集)] の順に選択します。

    • 新しいワークグループを作成する場合は、[Create workgroup (ワークグループの作成)] を選択します。

  3. [Query result location (クエリ結果の場所)] で、[Select (選択)] フォルダを選択します。

  4. S3 の場所のリストから、使用するバケットとフォルダが一番上の行に表示されるまで、青色の矢印を連続して選択します。[Select] を選択します。

  5. [Settings (設定)] で、次のいずれかを実行します。

    • [Override client-side settings (クライアント側設定の上書き)] を選択して、このワークグループのメンバーが実行するすべてのクエリについて、上記で指定した場所にクエリファイルを保存します。

    • ワークグループメンバーが、Amazon S3 の出力場所を指定することなく Athena API、ODBC ドライバー、または JDBC ドライバーを使用してクエリを事項する場合に限り、[Override client-side settings] (クライアント側設定の上書き) をオフにして、上記で指定した場所にクエリファイルを保存します。

  6. ワークグループを編集する場合は、[Save (保存)] を選択します。ワークグループを作成する場合は、[Create workgroup (ワークグループの作成)] を選択します。

クエリ履歴の表示

Athena コンソールを使用して、成功したクエリと失敗したクエリの表示、成功したクエリのクエリ結果ファイルのダウンロード、失敗したクエリのエラー詳細の表示を行うことができます。Athena では、クエリ履歴が 45 日間保持されます。

Athena コンソールでクエリ履歴を表示する

  1. https://console.aws.amazon.com/athena/ で Athena コンソールを開きます。

  2. [History] タブを選択します。[履歴] タブには、実行された各クエリに関する情報が表示されます。

    
                        Athena コンソールでクエリ履歴を表示します。
  3. 次のいずれかを行ってください。

    • クエリエディタでクエリステートメントを表示するには、[クエリ] 列でクエリのテキストを選択します。長いクエリステートメントは省略されます。

      
                                クエリのテキストを選択してクエリエディタで表示する。
    • クエリ ID を表示するには、その [State] (状態) ([Succeeded] (成功)、[Failed] (失敗)、または [Cancelled] (キャンセル)) を選択します。クエリ ID がツールチップに表示されます。

      
                                Athena コンソールの [History] (履歴) タブでクエリ ID を表示します。
    • 成功したクエリの結果を .csv ファイルにダウンロードするには、[Download results (結果のダウンロード)] を選択します。

      
                                Athena コンソールの [History] (履歴) タブからクエリ結果をダウンロードします。
    • 失敗したクエリの詳細を表示するには、クエリの [Error detail (エラー詳細)] を選択します。

      
                                [Error details] (エラー詳細) を選択して、失敗したクエリの詳細を表示します。
      
                                失敗したクエリのエラー詳細を表示します。

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

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

  1. Athena の ListQueryExecutions API アクション、または list-query-executions CLI コマンドを使用して、クエリ ID を取得します。

  2. Athena の GetQueryExecution API アクション、または get-query-execution CLI コマンドを使用して、ID に基づいた各クエリに関する情報を取得します。

  3. Amazon S3 の PutObject API アクション、または put-object CLI コマンドを使用して、その情報を Amazon S3 に保存します。