使用查询结果、最近查询和输出文件 - Amazon Athena
指定查询结果位置使用 Athena 控制台下载查询结果文件查看最近的查询在 Amazon S3 中查找查询输出文件
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

使用查询结果、最近查询和输出文件

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. （可选）在 Expected bucket owner（预期存储桶拥有者）中，输入您希望成为输出位置存储桶的拥有者 Amazon Web Services 账户 的 ID。这是附加安全措施。如果存储桶拥有者的账户 ID 与您在此处指定的 ID 不匹配，则输出到存储桶的尝试将失败。有关更多信息，请参阅《Amazon S3 用户指南》中的使用存储桶拥有者条件验证存储桶所有权

    注意

    预期存储桶拥有者设置仅适用于您为 Athena 查询结果指定的 Amazon S3 输出位置。其不适用于其他 Amazon S3 位置，例如外部 Amazon S3 存储桶中的数据源位置、CTAS 和 INSERT INTO 目标表位置、UNLOAD 语句输出位置、为联合查询溢出存储桶的操作，或针对另一个账户中的表运行的 SELECT 查询。

  6. （可选）如果要加密存储在 Amazon S3 中的查询结果，则选择 Encrypt query results（加密查询结果）。要详细了解 Athena 的加密，请参阅静态加密。

  7. （可选）如果查询结果存储桶启用了 ACL，则选择 Assign bucket owner full control over query results（为存储桶拥有者分配对查询结果的完全控制权），以向存储桶拥有者授予对查询结果的完全控制权。例如，假设您的查询结果位置属于其他账户所有，则可以将所有权以及对查询结果的完全控制权授予该其他账户。有关更多信息，请参阅《Amazon S3 用户指南》中的控制存储桶的对象所有权和禁用 ACL。

  8. 选择 Save（保存）。

以前创建的默认位置

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

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

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

您使用 Amazon Web Services Management Console、Amazon CLI 或 Athena API 在工作组配置中指定查询结果位置。

使用 Amazon CLI 时，请在运行 aws athena create-work-group 或者 aws 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（预期存储桶拥有者）中，输入您希望成为输出位置存储桶的拥有者 Amazon Web Services 账户 的 ID。这是附加安全措施。如果存储桶拥有者的账户 ID 与您在此处指定的 ID 不匹配，则输出到存储桶的尝试将失败。有关更多信息，请参阅《Amazon S3 用户指南》中的使用存储桶拥有者条件验证存储桶所有权

    注意

    预期存储桶拥有者设置仅适用于您为 Athena 查询结果指定的 Amazon S3 输出位置。其不适用于其他 Amazon S3 位置，例如外部 Amazon S3 存储桶中的数据源位置、CTAS 和 INSERT INTO 目标表位置、UNLOAD 语句输出位置、为联合查询溢出存储桶的操作，或针对另一个账户中的表运行的 SELECT 查询。

  7. （可选）如果要加密存储在 Amazon S3 中的查询结果，则选择 Encrypt query results（加密查询结果）。要详细了解 Athena 的加密，请参阅静态加密。

  8. （可选）如果查询结果存储桶启用了 ACL，则选择 Assign bucket owner full control over query results（为存储桶拥有者分配对查询结果的完全控制权），以向存储桶拥有者授予对查询结果的完全控制权。例如，假设您的查询结果位置属于其他账户所有，则可以将所有权以及对查询结果的完全控制权授予该其他账户。

    如果存储桶的 S3 Object Ownership（S3 对象所有权）设置为 Bucket owner preferred（存储桶拥有者优先），则存储桶拥有者还拥有从此工作组写入的所有查询结果对象。例如，假设某个外部账户的工作组启用了此选项并将其查询结果位置设置为您账户的 Amazon S3 存储桶，并且该存储桶的 S3 Object Ownership（S3 对象所有权）设置为 Bucket owner preferred（存储桶拥有者优先），则您将拥有并完全控制该外部工作组的查询结果的访问权限。

    如果查询结果存储桶的 S3 Object Ownership（S3 对象所有权）设置为 Bucket owner enforced（存储桶拥有者强制），则选择此选项将不具有效力。有关更多信息，请参阅《Amazon S3 用户指南》中的控制存储桶的对象所有权和禁用 ACL。

  9. 如果您希望工作组的所有用户使用您指定的查询结果位置，请向下滚动到 Settings（设置）部分，然后选择 Override client-side settings（覆盖客户端侧设置）。

  10. 选择保存更改。

使用 Athena 控制台下载查询结果文件

运行查询后，您可以立即从查询窗格中下载查询结果 CSV 文件。您还可以从 Recent queries（最近的查询）选项卡下载最近查询的查询结果。

注意

Athena 查询结果文件为数据文件，其中包含了可以被单个用户配置的信息。有些数据在用来读取和分析该数据的程序中有可能会将部分数据解释为命令（CSV 注入）。因此，将查询结果 CSV 数据导入到某个电子表格程序时，该程序可能警告您注意安全风险。为了确保系统安全，您应始终选择禁用下载查询结果中的链接或宏。

运行查询并下载查询结果

  1. 在查询编辑器中输入您的查询，然后选择 Run（运行）。

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

  2. 要下载查询结果的 CSV 文件，请选择查询结果窗格上方的 Download results（下载结果）。根据您的浏览器和浏览器配置，您可能需要确认下载。

    将查询结果保存到 Athena 控制台中的 .csv 文件。

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

  1. 选择 Recent queries（最近的查询）。

    选择 Recent queries（最近的查询）以查看以前的查询。

  2. 使用搜索框查找查询，选择查询，然后选择 Download results（下载结果）。查询保留 45 天。

    选择 Recent queries（最近的查询）以查找并下载以前的查询结果。

查看最近的查询

您可以使用 Athena 控制台查看哪些查询成功或失败，并查看失败查询的错误详细信息。Athena 会将查询历史记录保留 45 天。

在 Athena 控制台中查看最近的查询

  1. 从 https://console.aws.amazon.com/athena/ 打开 Athena 控制台。

  2. 选择 Recent queries（最近的查询）。Recent queries（最近的查询）选项卡显示有关运行的每个查询的信息。

  3. 要在查询编辑器中打开查询语句，请选择查询的执行 ID。

    选择查询的执行 ID 以在查询编辑器中进行查看。

  4. 要查看失败查询的详细信息，请选择该查询的 Failed（失败）链接。

    选择查询的 Failed（失败）链接，以查看有关该失败的信息。

  5. 要配置 Recent queries（最近的查询）选项卡的选项，如要显示的列和文本换行，请选择选项按钮（齿轮图标）。

    选择选项按钮，配置最近查询的显示。

  6. 在 Preferences（首选项）对话框中，选择每页行数、换行行为和要显示的列。

    配置最近查询的显示。

  7. 选择 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 是由工作组设置或客户端设置指定的查询结果位置。有关更多信息，请参阅本文后面的指定查询结果位置。

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

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

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

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

识别查询输出文件

查询输出文件会按照查询名称、查询 ID 和查询运行日期保存到 Amazon S3 中的查询结果位置。每个查询的文件都使用 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 数据源位置创建的文件。如果查询失败，清单也将跟踪查询要写入的文件。清单对于识别由于查询失败而导致的孤立文件很有用。

使用 Amazon CLI 标识查询输出位置和文件

要使用 Amazon 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

该命令返回的输出类似于下方内容。有关每个输出参数的说明，请参阅 Amazon 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"
    }
}