querying-data-lake

查询数据湖

在 Amazon Athena 上跨默认目录和联合目录（Glue、S3 Tables、Redshift）执行 SQL 查询，支持选择工作组、语句分类和错误恢复。

概述

在默认目录和联合目录上执行并管理 Athena SQL 查询。选择工作组，解析目标资产（将模糊引用委托给 finding-data-lake-assets），对语句进行安全分类，并报告成本和扫描的数据量。使用 AWS MCP 服务进行沙盒化执行和审计日志记录；如果 AWS MCP 服务不可用，相同的 AWS CLI 命令也可直接使用。

参数获取限制：

• 你 MUST 接受单个可选参数：SQL 文本、命名查询名称、工作组名称、目录名称，或 profile TABLE_NAME
• 你 MUST 接受直接文本形式的参数，或包含 SQL 的文件指针
• 如果尚未设置，你 MUST 向用户询问目标 AWS 区域
• 执行任何非简单查询之前，你 MUST 确认输出 S3 位置
• 你 MUST 尊重用户在任何步骤中取消操作的决定

常见任务

1. 验证依赖项

运行查询前，检查所需工具和 AWS 访问权限。

限制：

• 你 MUST 验证 AWS MCP 服务工具（aws___call_aws）是否可用；如果可用，必须通过这些工具运行查询；只有在 MCP 服务不可用时才能回退到 AWS CLI
• 你 MUST NOT 回退到 shell 或 Bash 执行查询——必须通过 MCP 工具或 aws athena CLI 获取结果，以便跟踪输出位置和成本
• 你 MUST 使用 aws sts get-caller-identity 确认凭证，并告知用户缺少的任何工具

2. 解析工作组

检查调用者身份，列出工作组，并自动选择最合适的工作组（参见 workgroup-selection.md）。

限制：

• 提交任何查询之前，你 MUST 选择一个工作组（以避免输出位置错误）
• 你 MUST 向用户展示所选工作组及其输出位置
• 失败时，你 MUST NOT 未经用户确认便自动切换到其他工作组

3. 解析目标资产

如果用户按名称、业务概念（“我们的季度报告”“销售数据”）、S3 路径引用表，或只指定目录而未指定表，则委托给 finding-data-lake-assets，以返回具体的 database.table（以及非默认目录时的目录）。

限制：

• 你 MUST NOT 使用 athena list-data-catalogs 或遍历 get-tables 来解析模糊的资产引用——这些方式会遗漏联合目录并浪费令牌
• 仅当用户提供完全限定的引用（精确的 database.table）或希望原样执行的原始 SQL 时，你 SHOULD 跳过此步骤
• 在构建查询前，你 MUST 明确说明解析出的资产：“在 [目录] 中找到 [表]。将使用该表执行查询。”
• 默认情况下，你 SHOULD 使用默认 Glue 目录；除非用户提到“federated”“Redshift”“S3 Tables”，或 finding-data-lake-assets 返回了其他目录

4. 探查架构

对于分析类查询，构建最终查询前，你 SHOULD 对目标表进行探查。探查时 MUST 展示示例行（SELECT ... LIMIT 5）。

5. 构建查询

表的引用方式取决于目录类型：

• 默认 Glue 目录：database.table（单目录查询省略目录前缀）。在跨目录查询中，使用 "awsdatacatalog".database.table 限定默认目录中的表。
• 已注册的数据源：datasource.database.table
• 未注册的 Glue 目录："catalog/subcatalog".database.table

6. 分类并执行

执行前先对 SQL 语句进行分类：

语句	行为
SELECT、SHOW、DESCRIBE、EXPLAIN	安全 — 执行
INSERT、UPDATE、DELETE、DROP、ALTER、CREATE、TRUNCATE、MERGE	具有破坏性 — 警告用户并要求明确确认
不确定	按具有破坏性处理；先确认

工具调用示例（通过 AWS MCP 服务）：

aws___call_aws(command="aws athena start-query-execution --work-group <WORKGROUP_NAME> --query-string '<sql>' --query-execution-context Database=<db>")

对于联合查询或 S3 Tables 目录，还要在执行上下文中设置 Catalog=<CATALOG_PATH>（例如 Catalog=s3tablescatalog/<BUCKET_NAME>）。

约束：

• 如果目标是 Redshift 联合查询，执行前必须警告用户（“不进行分区裁剪 — 每次查询都会扫描整张表”）
• 执行跨目录联接前，必须警告用户（“跨目录联接会产生网络开销，可能较慢”）
• 执行前必须确认输出 S3 位置
• 执行前必须说明将调用哪个工具
• 必须尊重用户中止操作的决定

7. 展示结果并恢复

展示结果时，提供费用、扫描的数据量、耗时和可执行的见解。失败时，列出可用的工作组，并让用户选择要使用哪个工作组重试。

参数路由

按以下顺序解析；匹配到第一项后即停止：

1. 包含 SQL 关键字（SELECT、SHOW、DESCRIBE、INSERT 等）— SQL 文本，直接执行
2. profile TABLE_NAME — 对表进行全面分析（参见 query-patterns.md）
3. 匹配已知的命名查询 — 查找并执行
4. 匹配已知的工作组 — 显示工作组状态和近期查询
5. 匹配已知的目录 — 委托给 exploring-data-catalog 枚举数据库和表
6. 无参数 — 显示近期查询活动和可用表

原则

• 执行前始终选择工作组（避免输出位置错误）
• 对陌生表运行分析查询前，先分析表
• 展示结果时同时提供费用，帮助用户了解成本
• 对大型表的探索性查询，建议使用 LIMIT
• 对答案显而易见的问题，绝不询问用户；但始终确认与安全相关的操作（切换工作组、更改输出位置、非 SELECT 语句）

故障排除

错误	原因	修复方法
混合大小写导致 Redshift 标识符错误	Redshift 联合查询名称只能使用小写	将标识符转换为小写
CatalogId 验证失败	传入了 ARN，而非目录名称	传入目录名称，而非 ARN
跨目录 information_schema 查询无结果	缺少目录限定符	使用目录限定路径："catalog".information_schema.tables
查询因输出位置错误而失败	工作组未配置输出位置	选择另一个配置了输出位置的工作组，或配置输出位置
未经确认就执行了具有破坏性的语句	跳过了语句分类	始终对 INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/TRUNCATE/MERGE 进行分类，并向用户确认

其他资源

• 工作组选择逻辑
• 常见查询模式
• Athena 最佳实践
• Athena 联合查询