使用查詢結果、近期查詢和輸出檔案 - Amazon Athena

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

使用查詢結果、近期查詢和輸出檔案

Amazon Athena 會自動將执行的每個查詢的查詢結果和中繼資料資訊存放在查詢結果位置,您可以在 Amazon S3 中指定该位置。如有必要,您可以存取此位置中的檔案來使用它們。您也可以直接從 Athena 主控台下載查詢結果檔案。

若是第一次設定 Amazon S3 查詢結果位置,請參閱使用 Athena 主控台指定查詢結果位置

每個執行的查詢都會自動儲存輸出檔案。若要存取和檢視查詢輸出檔案,IAM 委託人 (使用者和角色) 需要對查詢結果位置進行 Amazon S3 GetObject 動作的許可,以及 Athena GetQueryResults 動作的許可。查詢結果位置可以加密。如果位置已加密,則使用者必須擁有適當的金鑰許可,才能加密和解密查詢結果位置。

重要

具有查詢結果位置之 Amazon S3 GetObject 動作許可的 IAM 委託人,能夠從 Amazon S3 擷取查詢結果,即使 Athena GetQueryResults 動作的許可遭拒也一樣。

指定查詢結果位置

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. 請在導覽列中選擇 Manage (管理)。

  4. 對於 Manage settings (管理設定),請執行下列其中一項動作:

    • Location of query result (查詢結果的位置) 方塊中,輸入您在 Amazon S3 中為查詢結果建立的儲存貯體路徑。在路徑中加上 s3:// 作為字首。

    • 選擇 Browse S3 (瀏覽 S3),選擇您在目前區域建立的 Amazon S3 儲存貯體,然後選擇 Choose (選擇)。

    注意

    如果您使用為工作群組中的所有使用者指定查詢結果位置的工作群組,則變更查詢結果位置的選項將無法使用。

  5. (選用) 選擇 View lifecycle configuration (檢視生命週期組態),以檢視和設定查詢結果儲存貯體上的 Amazon S3 生命週期規則。您建立的 Amazon S3 生命週期規則可以是到期規則或轉換規則。到期規則會在一段時間之後自動刪除查詢結果。轉換規則會將其移至另一個 Amazon S3 儲存層。如需詳細資訊,請參閱《Amazon Simple Storage Service 使用者指南》中的設定儲存貯體的生命週期組態

  6. (選用) 在 Expected bucket owner (預期的儲存貯體擁有者) 中,輸入您預期成為輸出位置儲存貯體擁有者的 AWS 帳戶 ID。這是一項附加的安全措施。如果儲存貯體擁有者的帳戶 ID 與您在此處指定的 ID 不相符,則嘗試輸出到儲存貯體的動作會失敗。如需詳細資訊,請參閱 Amazon S3 使用者指南中的使用儲存貯體擁有者條件驗證儲存貯體擁有權

    注意

    預期的儲存貯體擁有者設定僅適用於您為 Athena 查詢結果指定的 Amazon S3 輸出位置。它不適用於其他 Amazon S3 位置,例如外部 Amazon S3 儲存貯體、CTASINSERT INTO 目的地資料表位置、UNLOAD 陳述式輸出位置等資料來源位置,也不適用於溢出聯合查詢儲存貯體的操作,或針對另一個帳戶中的資料表執行的 SELECT 查詢。

  7. (選用) 如果要將存放在 Simple Storage Service (Amazon S3) 中的查詢結果加密,選擇 Encrypt query results (將查詢結果加密)。如需在 Athena 中加密的詳細資訊,請參閱 靜態加密

  8. (選用) 對於查詢結果儲存貯體,選擇 Assign bucket owner full control over query results (指派儲存貯體擁有者對查詢結果的完整控制),以便在 ACL 已啟用時,授予儲存貯體擁有者對查詢結果的完整存取。例如,如果您的查詢結果位置係由另一個帳戶所擁有,則可以授予另一個帳戶對查詢結果的所有權和完整控制。如需詳細資訊,請參閱《Simple Storage Service (Amazon S3) 使用者指南》中的控制物件的所有權並停用儲存貯體的 ACL

  9. 選擇 Save (儲存)。

先前建立的預設位置

先前,如果您在 Athena 中執行查詢而未指定 Query result location (查詢結果位置) 的值,且查詢結果位置設定未被工作群組覆寫,則 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-groupaws athena update-work-group 命令,請使用 --configuration 選項的 OutputLocation 參數來指定查詢結果位置。

若要使用 Athena 主控台指定工作群組的查詢結果位置
  1. 如果未顯示主控台的導覽窗格,請選擇左側的展開選單。

    
                            選擇展開選單。
  2. 在導覽窗格中,選擇 Workgroups (工作群組)。

  3. 在工作群組清單中,選擇您要編輯的工作群組之連結。

  4. 選擇 編輯

  5. 對於 Query result location and encryption (查詢結果位置和加密),執行下列其中一項:

    • Location of query result (查詢結果的位置) 文字方塊中,輸入您要在 Amazon S3 中存放查詢結果的儲存貯體路徑。在路徑中加上 s3:// 作為字首。

    • 選擇 Browse S3 (瀏覽 S3),選擇您在目前區域中想要使用的 Amazon S3 儲存貯體,然後選擇 Choose (選擇)。

  6. (選用) 在 Expected bucket owner (預期的儲存貯體擁有者) 中,輸入您預期成為輸出位置儲存貯體擁有者的 AWS 帳戶 ID。這是一項附加的安全措施。如果儲存貯體擁有者的帳戶 ID 與您在此處指定的 ID 不相符,則嘗試輸出到儲存貯體的動作會失敗。如需詳細資訊,請參閱 Amazon S3 使用者指南中的使用儲存貯體擁有者條件驗證儲存貯體擁有權

    注意

    預期的儲存貯體擁有者設定僅適用於您為 Athena 查詢結果指定的 Amazon S3 輸出位置。它不適用於其他 Amazon S3 位置,例如外部 Amazon S3 儲存貯體、CTASINSERT INTO 目的地資料表位置、UNLOAD 陳述式輸出位置等資料來源位置,也不適用於溢出聯合查詢儲存貯體的操作,或針對另一個帳戶中的資料表執行的 SELECT 查詢。

  7. (選用) 如果要將存放在 Simple Storage Service (Amazon S3) 中的查詢結果加密,選擇 Encrypt query results (將查詢結果加密)。如需在 Athena 中加密的詳細資訊,請參閱 靜態加密

  8. (選用) 對於查詢結果儲存貯體,選擇 Assign bucket owner full control over query results (指派儲存貯體擁有者對查詢結果的完整控制),以便在 ACL 已啟用時,授予儲存貯體擁有者對查詢結果的完整存取。例如,如果您的查詢結果位置係由另一個帳戶所擁有,則可以授予另一個帳戶對查詢結果的所有權和完整控制。

    如果儲存貯體的 S3 物件所有權設定為 Bucket owner preferred (首選的儲存貯體擁有者) 時,則儲存貯體擁有者亦擁有從此工作群組寫入的所有查詢結果物件。例如,如果外部帳戶的工作群組啟用此選項,並將其查詢結果位置設定為您帳戶的 Simple Storage Service (Amazon S3) 儲存貯體,且該儲存貯體的 S3 物件所有權設定為 Bucket owner preferred (首選的儲存貯體擁有者) 時,則您擁有外部工作群組的查詢結果並具有完整的控制存取。

    當查詢結果儲存貯體的 S3 物件所有權設定為 Bucket owner enforced (強制的儲存貯體擁有者) 時,則選取此選項不會有任何作用。如需詳細資訊,請參閱《Simple Storage Service (Amazon S3) 使用者指南》中的控制物件的所有權並停用儲存貯體的 ACL

  9. 如果要讓工作群組的所有使用者使用您指定的查詢結果位置,請往下捲動到 Settings (設定) 部分,然後選擇 Override client-side settings (覆寫用戶端設定)。

  10. 選擇 Save changes (儲存變更)

使用 Athena 主控台下載查詢結果檔案

您可以在執行查詢之後,立即從查詢窗格下載查詢結果 CSV 檔案檔案。您也可以從 Recent queries (近期查詢) 索引標籤中,下載近期查詢的查詢結果。

注意

Athena 查詢結果檔案是資料檔案,內含個別使用者可設定的資訊。讀取與分析此資料的某些程式很可能會將某些資料解譯為命令 (CSV injection)。因此,將查詢結果 CSV 資料匯入至試算表程式時,該程式可能會提醒您關於安全方面的考量。為確保系統的安全,您應該始終選擇停用下載的查詢結果中的連結或巨集。

執行查詢並下載查詢結果
  1. 在查詢編輯器中輸入查詢,然後選擇 Run (執行)。

    當查詢完成執行時,Results (結果) 窗格會顯示查詢結果。

  2. 若要下載查詢結果的 CSV 檔案,請選擇查詢結果窗格上方的 Download results (下載結果)。根據您的瀏覽器和瀏覽器組態,您可能需要確認下載。

    
                        將查詢結果儲存至 Athena 主控台中的 .csv 檔案。
下載先前查詢的查詢結果檔案
  1. 選擇 Recent queries (近期查詢)。

    
                        選擇 Recent queries (近期查詢) 以檢視先前的查詢。
  2. 使用搜尋方塊尋找查詢、選擇查詢,然後選擇 Download results (下載結果)。

    注意

    您無法使用 Download results (下載結果) 選項來擷取已手動刪除的查詢結果,或擷取已由 Amazon S3 生命週期規則刪除或移至其他位置的查詢結果。

    
                        選擇 Download results (近期查詢) 以尋找並下載以前的查詢結果。

檢視近期查詢

使用 Athena 主控台可查看哪些查詢成功或失敗,並檢視失敗查詢的錯誤詳細資訊。Athena 會將查詢歷史記錄保留 45 天。

在 Athena 主控台中檢視近期查詢。
  1. 前往 https://console.aws.amazon.com/athena/ 開啟 Athena 主控台。

  2. 選擇 Recent queries (近期查詢)。Recent queries (近期查詢) 索引標籤顯示每個已執行查詢的相關資訊。

  3. 若要在查詢編輯器中開啟查詢陳述式,請選擇查詢的執行 ID。

    
                        選擇查詢的執行 ID 即可在查詢編輯器中看到該查詢內容。
  4. 若要查看失敗查詢的詳細資訊,請選擇查詢的 Failed (失敗) 連結。

    
                        選擇查詢的 Failed (失敗) 連結以檢視失敗相關資訊。

將多個近期查詢下載到 CSV 檔案

您可以使用 Athena 主控台的 Recent queries (近期查詢) 標籤,將一或多個近期查詢匯出至 CSV 檔案,以便以表格格式檢視這些查詢。下載的檔案不包含查詢結果,而是 SQL 查詢字串本身以及有關查詢的其他資訊。匯出的欄位包括執行 ID、查詢字串內容、查詢開始時間、狀態、執行時間、掃描的資料量、使用的查詢引擎版本以及加密方法。您可以匯出最多 500 個近期查詢,或使用在搜尋方塊中輸入的條件,匯出最多 500 個篩選的查詢。

若要將一或多個近期查詢匯出至 CSV 檔案
  1. 前往 https://console.aws.amazon.com/athena/ 開啟 Athena 主控台。

  2. 選擇 Recent queries (近期查詢)。

  3. (選用) 使用搜尋方塊,篩選您要下載的近期查詢。

  4. 選擇 Download CSV (下載 CSV)。

    
                            選擇 Download CSV (下載 CSV)。
  5. 出現檔案儲存提示時,選擇 Save (儲存)。預設檔案名稱 Recent Queries 後面接著一個時間戳記 (例如,Recent Queries 2022-12-05T16 04 27.352-08 00.csv)

設定近期查詢顯示選項

您可以設定 Recent queries (近期查詢) 標籤的選項 (例如要顯示的資料欄和文字換行)。

若要設定 Recent queries (近期查詢) 標籤的選項
  1. 前往 https://console.aws.amazon.com/athena/ 開啟 Athena 主控台。

  2. 選擇 Recent queries (近期查詢)。

  3. 選擇選項按鈕 (齒輪圖示)。

    
                            選擇選項按鈕以設定近期查詢的顯示。
  4. Preferences (偏好設定) 對話方塊中,選擇每頁的列數、換行反應和要顯示的資料欄。

    
                            設定近期查詢的顯示方式。
  5. 選擇 Confirm (確認)。

保留超過 45 天的查詢歷史記錄

若要將查詢歷史記錄保留 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 中。

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