Athena 任務¶
這頁能幫你做什麼¶
Athena 任務讓你在工作流程 (Workflow) 的某個步驟，直接用 SQL 查詢存放在 Amazon S3 上的資料（透過 Amazon Athena），把查到的結果帶進後續步驟使用。和 MySQL 任務 類似，差別在於 Athena 查的是雲端上的大量資料檔（例如記錄檔、報表匯出、資料湖），不需要自己維護一台資料庫。常見情境：
- 對長期累積的銷售、流量或交易紀錄做彙總統計，餵給後面的大型語言模型 (LLM) 產生分析報告。
- 依使用者輸入的條件，從 S3 上的大型資料集撈出符合的明細。
- 把查詢結果交給下游步驟轉換或回覆，讓回答有資料依據。
開始前
這個任務需要一個 AWS 類型的連結器 (Connector)，用來提供存取 Athena 與 S3 所需的 AWS 憑證與區域設定。請先到 Connector 資源頁 建立好，再回到這裡選用。若你打開「連結器」對話框時清單是空的，代表還沒有任何 AWS 連結器，需先建立一個（需相應權限）才能繼續。
操作步驟¶
-
在工作流程編輯器中新增一個 Athena 任務節點（節點選單的「Database」分類，與 MySQL、OpenSearch 並列），點選它開啟右側設定表單。
-
在「名稱」填一個好辨識的步驟名稱。
- 在「連結器」點開後會跳出資源選擇對話框，從中選擇前面建好的 AWS 連結器。
- 在「SQL 查詢」編輯器寫下查詢指令。欄位預設帶有一段範本，把
table_name換成你實際的 Athena 資料表即可。 - 視需要在「資料庫」填要查詢的資料庫（schema）名稱。
- 在「執行與輸出設定」選擇結果要怎麼產生：用「工作群組」或指定「輸出位置」（見下方說明），並填入對應欄位。
- 視需要展開進階欄位調整「唯讀」、「最大列數」、「等待逾時」。
- 設定「下一個狀態」，視需要填「附註」。
- 用表單上方的測試按鈕（）試跑，確認回傳的資料符合預期。
完整欄位說明¶
下表只列 Athena 任務特有的欄位。名稱、附註、下一個狀態、輸入與輸出、錯誤處理、進階／執行設定等所有任務共用的分區，請見 Action 通用設定。
| 欄位 | 必填 | 預設 | 說明 |
|---|---|---|---|
| 連結器 (Connector) | 是 | 無 | 指定此查詢要使用的 AWS 連結器，尤其在需要跨帳號存取時。點開後會跳出資源選擇對話框，只會列出 AWS 類型的連結器。也可切換成從工作流程輸入動態帶入。建立方式見 Connector 資源頁。 |
| SQL 查詢 (SQL Query) | 是 | 範本（見下方） | 要執行的 Athena SQL 查詢。點欄位會開啟「Athena 編輯器」對話框撰寫。預設帶有一段查詢範本，請把 table_name 換成實際資料表。 |
| 資料庫 (Database) | 否 | 無 | 預設要查詢的資料庫（schema）名稱。可在查詢中以完整名稱覆寫，也可改用工作流程輸入動態帶入。 |
| 執行與輸出設定 (Execution and Output Setting) | 是 | 無 | 選擇查詢結果的產生方式，二選一：「工作群組」或「輸出位置」（見下方說明）。選定後下方會出現對應欄位。 |
| 工作群組 (Workgroup) | 條件 | 無 | 當「執行與輸出設定」選「工作群組」時必填。指定執行查詢要使用的 Athena 工作群組，並沿用其預設的結果輸出位置。 |
| 輸出位置 (Output Location) | 條件 | 無 | 當「執行與輸出設定」選「輸出位置」時必填。指定查詢結果輸出的 S3 路徑，需以 s3:// 開頭。 |
| 目錄 (Catalog) | 否 | 無 | 指定 Athena 的資料目錄 (Data Catalog) 名稱。 |
| 唯讀 (Read Only) | 否 | 開啟 | 開啟時只允許 SELECT、WITH、SHOW、DESCRIBE、EXPLAIN 等唯讀查詢，拒絕任何寫入。IAM 權限仍是主要的安全邊界，此開關提供額外的縱深防禦。 |
| 最大列數 (Max Rows) | 否 | 10000 | 查詢結果最多回傳的列數，可填 1～10000。超過會被截斷（輸出的 truncated 會標示）。 |
| 等待逾時 (Wait Timeout) | 否 | 300 | 等待查詢完成的最長秒數，可填 1～870。在此時間內未完成則逾時中斷。 |
執行與輸出設定的兩種方式¶
「執行與輸出設定」決定 Athena 要把查詢結果寫到哪裡：
- 工作群組 (Workgroup)：使用 Athena 工作群組來管理查詢執行設定，並沿用其預設的結果輸出位置。適合已在 AWS 端規劃好工作群組的情境。
- 輸出位置 (Output Location)：使用你指定的 S3 路徑來儲存查詢結果，需以
s3://開頭。適合需要把結果寫入特定位置的情境。
實際範例與預期結果¶
設定內容：
- 連結器：選一個 AWS 連結器（或留空用預設工作階段）
- SQL 查詢：
SELECT region, SUM(amount) AS total FROM sales WHERE year = 2025 GROUP BY region - 資料庫：
analytics_db - 執行與輸出設定：輸出位置
- 輸出位置：
s3://your-bucket/athena-results/
測試輸出（欄位以後端實際回傳為準）：
{
"errors": null,
"action_type": "athena_action",
"columns": ["region", "total"],
"rows": [
["north", 128000],
["south", 96500]
],
"query_execution_id": "a1b2c3d4-0000-1111-2222-333344445555",
"truncated": false
}
Note
輸出欄位說明：columns 為結果的欄位名稱陣列，rows 為資料列（每列是一個依 columns 順序排列的陣列），query_execution_id 為這次 Athena 查詢的執行識別碼，truncated 表示結果是否因超過「最大列數」而被截斷，action_type 固定為 athena_action。在後續步驟可用 JSONPath 取值，例如 $.rows[0] 取第一列、$.columns 取欄位名稱。
下一步¶
- 用 Transformation 任務 重組查詢結果，再交給下游步驟。
- 把查到的資料餵給 LLM 任務 或 Structured LLM 任務，產生有資料依據的回答。
- 若要查的是自管的關聯式資料庫，改用 MySQL 任務。
- 回到 Action 通用設定 了解輸入與輸出、錯誤處理等共用分區。