使用查询结果、输出文件和查询历史记录 - Amazon Athena
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用查询结果、输出文件和查询历史记录

Amazon Athena 会将运行的每个查询的查询结果和元数据信息自动存储在查询结果位置(可以在 Amazon S3 中指定)中。如有必要,您可以在此位置访问这些文件以对其进行处理。您还可以直接从 Athena 控制台下载查询结果文件。

运行的每个查询的输出文件都会自动保存,而无论查询本身是否保存。要访问和查看查询输出文件,IAM 委托人(用户和角色)需要 Amazon S3 GetObject 操作的权限来获得查询结果位置,并需要 Athena GetQueryResults 操作的权限。可对查询结果位置进行加密。如果该位置已加密,用户必须具有加密和解密查询结果位置的相应密钥权限。

重要

有权限对查询结果位置执行 Amazon S3 GetObject 操作的 IAM 委托人可以从 Amazon S3 中检索查询结果,即使 Athena GetQueryResults 操作的权限被拒绝。

获取查询 ID

运行的每个查询称为查询执行。查询执行具有唯一的标识符,称为查询 ID 或查询执行 ID。要使用查询结果文件并快速查找查询结果文件,您需要查询 ID。在本主题中,我们将查询 ID 称为 QueryID

使用 Athena 控制台获取已运行查询的 QueryID

  1. 从导航栏中选择 History (历史记录)

  2. 从查询列表中的 State (状态) 下选择查询状态 — 例如 Failed (失败)

  3. 选择 Query ID (查询 ID) 旁边的图标,将 ID 复制到剪贴板。

识别查询输出文件

查询输出文件会按照查询名称、查询 ID 和查询运行日期保存到 Amazon S3 中的查询结果位置。每个查询的文件都使用 QueryID 命名,这是在每个查询运行时 Athena 为其分配的唯一标识符。

会保存以下文件类型:

文件类型 文件命名模式 描述

查询结果文件

QueryID.csv

QueryID.txt

DML 查询结果文件以逗号分隔值 (CSV) 格式保存。它们以表格的形式包含每个查询的结果。DDL 查询结果保存为纯文本文件。您可以在使用控制台时从控制台的 Results (结果) 窗格下载这些文件,也可以从查询 History (历史记录) 中下载。有关更多信息,请参阅 使用 Athena 控制台下载查询结果文件

查询元数据文件

QueryID.csv.metadata

QueryID.txt.metadata

DML 和 DDL 查询元数据文件以二进制格式保存,无法人为读取。文件扩展名对应于相关的查询结果文件。在使用 GetQueryResults 操作读取查询结果时,Athena 使用元数据。虽然可以删除这些文件,但我们不建议这样做,因为这样会丢失关于查询的重要信息。

数据清单文件

QueryID-manifest.csv

生成数据清单文件以跟踪当 INSERT INTO 查询运行时 Athena 在 Amazon S3 数据源位置创建的文件。如果查询失败,清单也将跟踪查询要写入的文件。清单对于识别由于查询失败而导致的孤立文件很有用。

查询输出文件存储在采用以下路径模式的子文件夹中,除非在其配置覆盖了客户端设置的工作组中进行查询。当工作组配置覆盖客户端设置时,查询将使用工作组指定的结果路径。

QueryResultsLocationInS3/[QueryName|Unsaved/yyyy/mm/dd/]
  • QueryResultsLocationInS3 是由工作组设置或客户端设置指定的查询结果位置。请参阅下面的指定查询结果位置

  • 以下子文件夹仅为从控制台运行且工作组配置未覆盖其结果路径的查询而创建。从 AWS CLI 或使用 Athena API 运行的查询将直接保存到 QueryResultsLocationInS3

    • QueryName 是要保存其结果的查询的名称。如果查询已运行但未保存,则使用 Unsaved

    • yyyy/mm/dd 是查询运行的日期。

CREATE TABLE AS SELECT 查询关联的文件存储在以上模式的 tables 子文件夹中。

使用 AWS CLI 标识查询输出位置和查询结果文件

  • 使用以下示例中所示的 aws athena get-query-execution 命令。用查询 ID 替换 abc1234d-5efg-67hi-jklm-89n0op12qr34

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

    该命令返回的输出类似于下方内容。有关每个输出参数的描述,请参阅 AWS CLI Command Reference 中的 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 控制台下载查询结果文件

运行查询后,您可以立即从查询窗格中下载查询结果 CSV 文件,也可使用查询 History (历史记录) 下载。

下载最新查询的查询结果文件

  1. 在查询编辑器中输入您的查询,然后选择 Run query (运行查询)

    查询完成运行后,Results (结果) 窗格将显示查询结果。

  2. 要下载查询结果文件,请在查询结果窗格中选择文件图标。根据您的浏览器和浏览器配置,您可能需要确认下载。

下载早期查询的查询结果文件

  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 中的查询结果存储桶位置,或者您必须使用已指定存储桶且其配置覆盖客户端设置的工作组。如果未指定查询结果位置,则查询会失败并出现错误。

以前,如果您在运行查询时未为 Query result location (查询结果位置) 指定一个值,并且查询结果位置设置未被工作组覆盖,则 Athena 会为您创建默认位置。默认位置为 aws-athena-query-results-MyAcctID-MyRegion,其中 myActiID 是运行查询的 IAM 委托人的 AWS 账户 ID,MyRegi 是运行查询的区域(例如 us-west-1)。

现在,您必须指定查询结果位置或使用覆盖查询结果位置设置的工作组,然后才能在您的账户以前未使用 Athena 的区域中运行 Athena 查询。虽然 Athena 不再为您创建默认查询结果位置,但之前创建的默认 aws-athena-query-results-MyAcctID-MyRegion 位置仍然有效,您可以继续使用它们。

使用 Athena 控制台指定查询结果位置

  1. 从导航栏中,选择 Settings (设置)

  2. Query result location (查询结果位置) 中输入一个位置。您输入的位置将用于后续查询,除非您稍后更改。

    
                            使用 Athena 控制台指定查询结果位置

    如果您是指定查询结果位置并覆盖客户端设置的工作组的成员,则更改查询结果位置的选项不可用,如下图所示:

    
                            当工作组覆盖客户端设置时,查询结果位置设置不可用。

使用工作组指定查询结果位置

您使用 AWS 管理控制台、AWS CLI 或 Athena API 在工作组配置中指定查询结果位置。

如果使用 AWS CLI,请在运行 aws athena create-work-groupaws athena update-work-group 命令时使用 --configuration 选项的 OutputLocation 参数来指定查询结果位置。

使用 Athena 控制台指定工作组的查询结果位置

  1. 在导航栏中选择 Workgroup:CurrentWorkgroupName (工作组: CurrentWorkgroupName)

  2. 执行以下任一操作:

    • 如果编辑现有组,请从列表中选择它,选择 View details (查看详细信息),然后选择 Edit Workgroup (编辑工作组)

    • 如果要创建新组,请选择 Create workgroup (创建工作组)

  3. 对于 Query result location (查询结果位置),请选择 Select (选择) 文件夹。

  4. 从 S3 位置的列表中,连续选择蓝色箭头,直到您要使用的存储桶和文件夹显示在顶行。选择选择

  5. Settings (设置) 下,执行下列操作之一:

    • 选择 Override client-side settings (覆盖客户端设置),可在上面指定的位置保存此工作组成员运行的所有查询的查询文件。

    • 清除 Override client-side settings (覆盖客户端设置),只有当工作组成员使用 Athena API、ODBC 驱动程序或 JDBC 驱动程序运行查询而不在 Amazon S3 中指定输出位置时才会在上面指定的位置保存查询文件。

  6. 如果要编辑工作组,请选择 Save (保存)。如果要创建工作组,请选择 Create workgroup (创建工作组)

查看查询历史记录

您可以使用 Athena 控制台查看成功和失败的查询、下载成功查询的查询结果文件以及查看失败查询的错误详细信息。Athena 将查询历史记录保留 45 天。

在 Athena 控制台中查看查询历史记录

  1. https://console.amazonaws.cn/athena/ 打开 Athena 控制台。

  2. 选择 History 选项卡。History (历史记录) 选项卡显示有关运行的每个查询的信息。

    
                        在 Athena 控制台中查看查询历史记录。
  3. 请执行下列操作之一:

    • 要在查询编辑器中查看查询语句,请在 Query (查询) 列中选择查询的文本。较长的查询语句将采用缩写形式。

      
                                选择查询的文本以在查询编辑器中进行查看。
    • 要查看查询 ID,请选择其 State (状态)Succeeded (成功)Failed (失败)Cancelled (已取消))。查询 ID 显示在指针提示中。

      
                                在 Athena 控制台的 History (历史记录) 选项卡上查看查询 ID。
    • 要将成功查询的结果下载到 .csv 文件中,请选择 Download results (下载结果)

      
                                从 Athena 控制台的 History (历史记录) 选项卡下载查询结果。
    • 若要查看失败查询的详细信息,请选择该查询的 Error details (错误详细信息)

      
                                选择 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 中。