querying-data-lake

查詢資料湖

在 Amazon Athena 上跨預設與聯合目錄（Glue、S3 Tables、Redshift）執行 SQL 查詢，支援工作群組選擇、陳述式分類與錯誤復原。

概述

跨預設與聯合目錄執行與管理 Athena SQL 查詢。選擇工作群組、解析目標資產（將模糊參照委派給 finding-data-lake-assets）、對陳述式進行安全分類，並回報成本與掃描資料量。使用 AWS MCP 伺服器進行沙箱執行與稽核日誌記錄；當 MCP 伺服器不可用時，可直接使用相同的 AWS CLI 指令。

參數取得限制：

• 您必須接受一個選用引數：SQL 文字、命名查詢名稱、工作群組名稱、目錄名稱或 profile TABLE_NAME
• 您必須以直接文字或指向包含 SQL 的檔案路徑來接受引數
• 如果尚未設定目標 AWS 區域，您必須詢問使用者
• 在執行任何非簡單查詢前，您必須確認輸出 S3 位置
• 您必須尊重使用者隨時中止的決定

常見任務

1. 驗證相依項目

在執行查詢前檢查必要工具與 AWS 存取權限。

限制：

• 您必須確認 AWS MCP 伺服器工具可用（aws___call_aws），並在可用時透過它們執行查詢；僅在 MCP 伺服器不可用時才回退到 AWS CLI
• 您不得回退到 shell 或 Bash 來執行查詢 — 結果必須透過 MCP 工具或 aws athena CLI 擷取，以便追蹤輸出位置與成本
• 您必須使用 aws sts get-caller-identity 確認憑證，並告知使用者任何缺少的工具

2. 解析工作群組

檢查呼叫者身分、列出工作群組、自動選取最佳工作群組（請參閱 workgroup-selection.md）。

限制：

• 在提交任何查詢前，您必須選取工作群組（避免輸出位置錯誤）
• 您必須向使用者顯示選取的工作群組及其輸出位置
• 失敗時，未經使用者確認，您不得自動升級到不同的工作群組

3. 解析目標資產

如果使用者以名稱、業務概念（「我們的季度報告」、「銷售資料」）、S3 路徑或未指定資料表的目錄來參照資料表，請委派給 finding-data-lake-assets 以傳回具體的 database.table（若非預設目錄則包含目錄）。

限制：

• 您不得嘗試使用 athena list-data-catalogs 或反覆呼叫 get-tables 來解析模糊資產參照 — 這些方法會遺漏聯合目錄並浪費 token
• 僅當使用者提供完整限定參照（確切的 database.table）或希望直接執行的原始 SQL 時，您才應跳過此步驟
• 在建立查詢前，您必須明確陳述已解析的資產：「在 [目錄] 中找到 [資料表]。將使用此資料表進行查詢。」
• 除非使用者提及「聯合」、「Redshift」、「S3 Tables」，或 finding-data-lake-assets 回傳不同的目錄，否則您應預設使用預設的 Glue 目錄

4. 探索結構描述

對於分析性查詢，您應在建立最終查詢前先分析目標資料表。您必須在分析過程中顯示範例資料列（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 聯合目錄時，您必須在執行前警告使用者（「無分割區修剪 — 每次查詢都會掃描整個資料表」）
• 在執行跨目錄 JOIN 前，您必須警告使用者（「跨目錄 JOIN 會產生網路開銷，可能速度較慢」）
• 在執行前，您必須確認輸出 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 聯合查詢