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

「翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。」

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

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

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

重要

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

クエリ ID の取得

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

Athenaコンソールを使用して を取得するには QueryID 実行したクエリの

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

    
                        Athenaコンソールでクエリ履歴を表示する。
  2. クエリのリストから、[State (状態)] の下のクエリステータス (例—: Succeeded) を選択します。クエリ ID がポインタヒントに表示されます。

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

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

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

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

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

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

クエリ結果ファイル

QueryID.csv

QueryID.txt

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

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

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

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

QueryID.csv.metadata

QueryID.txt.metadata

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

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

QueryID-manifest.csv

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

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

QueryResultsLocationInS3/[QueryName|Unsaved/yyyy/mm/dd/]
  • QueryResultsLocationInS3 は、ワークグループ設定またはクライアント側設定で指定されたクエリ結果の場所です。以下の「クエリ結果の場所の指定」を参照してください。

  • 次のサブフォルダは、ワークグループ設定が結果パスよりも優先されていないコンソールから実行されるクエリに対してのみ作成されます。または AWS CLI API を使用して実行されるクエリは、 に直接保存されます。AthenaQueryResultsLocationInS3.

    • QueryName は結果を保存するクエリの名前です。クエリが実行されたものの、保存されなかった場合は、Unsaved が使用されます。

    • yyyy/mm/dd は、クエリが実行された日付です。

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

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

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

    { "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 ファイルをダウンロードできます。

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

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

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

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

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

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

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

  2. クエリのリストをクエリが見つかるまで操作し、クエリの [Action (アクション)] で [Download results (結果のダウンロード)] を選択します

クエリ結果の場所の指定

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

  • Athenaコンソールを使用してクエリを実行する場合、ナビゲーションバーの [Settings (設定)] 入力されたクエリ結果の場所によってクライアント側の設定が決まります。

  • AthenaAPI を使用してクエリを実行する場合、OutputLocationStartQueryExecutionアクションのパラメータによってクライアント側の設定が決まります。

  • ODBC または JDBC ドライバーを使用してクエリを実行する場合、接続 URL で指定された S3OutputLocation プロパティによってクライアント側の設定が決まります。

重要

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

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

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

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

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

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

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

  1. ナビゲーションバーから、[Settings (設定)] を選択します。

  2. [Query result location (クエリ結果の場所)] に、既存のフォルダへのパス (末尾のスラッシュを含む) を入力します。Amazon S3

    注記

    末尾にスラッシュを含めてください。エラーに末尾のスラッシュの結果を含めない Invalid S3 folder location.

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

    
                            Athenaコンソールでのクエリ結果の場所の指定

    クエリ結果の場所を指定し、クライアント側の設定を上書きするワークグループのメンバーである場合、次の図に示すように、クエリ結果の場所を変更するオプションは使用できません。

    
                            ワークグループがクライアント側の設定を上書きする場合、クエリ結果の場所の設定は使用できません。

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

AWS マネジメントコンソール、AWS CLI、または Athena API を使用して、ワークグループ設定でクエリ結果の場所を指定できます。

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

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

  1. ワークグループの選択:CurrentWorkgroupNameナビゲーションバーの 。

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

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

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

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

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

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

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

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

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

クエリ履歴の表示

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

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

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

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

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

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

      
                                クエリのテキストを選択してクエリエディタで表示する。
    • クエリ ID を表示するには、その状態 (成功、失敗、またはキャンセル) を選択します。クエリ ID がポインタヒントに表示されます。

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

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

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

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

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

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

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

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