Athena 任務¶

這頁能幫你做什麼¶

Athena 任務讓你在工作流程 (Workflow) 的某個步驟，直接用 SQL 查詢存放在 Amazon S3 上的資料（透過 Amazon Athena），把查到的結果帶進後續步驟使用。和 MySQL 任務類似，差別在於 Athena 查的是雲端上的大量資料檔（例如記錄檔、報表匯出、資料湖），不需要自己維護一台資料庫。常見情境：

對長期累積的銷售、流量或交易紀錄做彙總統計，餵給後面的大型語言模型 (LLM) 產生分析報告。
依使用者輸入的條件，從 S3 上的大型資料集撈出符合的明細。
把查詢結果交給下游步驟轉換或回覆，讓回答有資料依據。

開始前

這個任務需要一個 AWS 類型的連結器 (Connector)，用來提供存取 Athena 與 S3 所需的 AWS 憑證與區域設定。請先到連結器資源頁建立好，再回到這裡選用。若你打開「連結器」對話框時清單是空的，代表還沒有任何 AWS 連結器，需先建立一個（需相應權限）才能繼續。

操作步驟¶

在工作流程編輯器中新增一個 Athena 任務節點（在「新增狀態」面板的「資料庫」分類，與 MySQL、OpenSearch 並列），點選它開啟右側設定表單（如何新增請見任務使用指南）。
在「名稱」填一個好辨識的步驟名稱。
在「連結器」選擇前面建好的 AWS 連結器。這個欄位看起來像下拉選單（右側有箭頭與一顆鉛筆鈕），但點欄位本體、點箭頭、點鉛筆都是開啟同一個含搜尋框的資源選擇對話框，不會展開一般的下拉清單。在對話框選好那筆連結器，要按右上角的「儲存」才會套用。選取時請點該列「名稱」以外的任一格（或列前面的圓鈕）——點「名稱」會在新分頁開啟該連結器的詳細頁，不會選取它（見資源挑選欄位）。
在「SQL 查詢」的內嵌程式碼編輯器（就在表單裡，附自動換行、複製、下載、在對話方塊中編輯等工具鈕）寫下查詢指令。新節點的這個欄位會預帶下面這段範本，把 table_name 換成你實際的 Athena 資料表即可：
```
-- Replace table_name with your Athena table.
SELECT
  *
FROM
  "table_name"
LIMIT
  100;
```
視需要在「資料庫」填要查詢的資料庫（schema）名稱。
在「執行與輸出設定」選擇結果要怎麼產生：用「工作群組」或指定「輸出位置」（見下方說明），並填入對應欄位。
視需要展開設定分頁底部的「進階任務設定」摺疊區塊，調整「唯讀」、「最大列數」、「等待逾時」。
設定「下一個狀態」，視需要填「附註」。
用表單上方的「測試任務」按鈕（）試跑，確認回傳的資料符合預期。

完整欄位說明¶

下表只列 Athena 任務特有的欄位。名稱、附註、下一個狀態、輸入與輸出、錯誤處理、進階／執行設定等所有任務共用的分區，請見任務通用設定。表格的「位置」欄標明該欄位是直接顯示在設定分頁上，還是收在底部的「進階任務設定」摺疊區塊裡。

欄位	位置	必填	預設	說明
連結器	設定分頁	是	無	指定此查詢要使用的 AWS 連結器。點欄位本體、點箭頭或點鉛筆都會開啟同一個資源選擇對話框（只會列出 AWS 類型的連結器），選完要按對話框的「儲存」；沒有一般的下拉清單可展開。也可切換成從工作流程輸入動態帶入。建立方式見連結器資源頁。
SQL 查詢	設定分頁	是	預帶一段 `SELECT * FROM "table_name" LIMIT 100;` 範本（全文見上方步驟 4）	要執行的 Athena SQL 查詢。這是一個內嵌在表單裡的程式碼編輯器，直接在裡面打字即可；工具鈕中的「在對話方塊中編輯」（）可放大成對話框編輯。範本被改掉或刪掉也沒關係，照上方步驟 4 的原文貼回來即可。
資料庫	設定分頁	否	無	預設要查詢的資料庫（schema）名稱。可在查詢中以完整名稱覆寫，也可改用工作流程輸入動態帶入。
執行與輸出設定	設定分頁	是	無	選擇查詢結果的產生方式，二選一：「工作群組」或「輸出位置」（見下方說明）。選定後下方會出現對應欄位。
工作群組	設定分頁	條件	無	當「執行與輸出設定」選「工作群組」時必填。指定執行查詢要使用的 Athena 工作群組，並沿用其預設的結果輸出位置。
輸出位置	設定分頁	條件	無	當「執行與輸出設定」選「輸出位置」時必填。指定查詢結果輸出的 S3 路徑，需以 `s3://` 開頭。本頁截圖用的是「工作群組」模式，所以圖上看不到這一欄。
目錄	設定分頁	否	無	Athena 的「資料目錄」名稱。資料目錄比資料庫高一層：一個資料目錄底下可以有很多資料庫，資料庫底下才是資料表。多數環境只有 AWS 預設的那一個資料目錄，這欄留空即可（平台會用預設目錄）；只有在你的資料另外掛在自建的資料目錄時才需要填。名稱要問維護 Athena 的同事。
唯讀	進階任務設定	否	開啟	開啟時只允許 SELECT、WITH、SHOW、DESCRIBE、EXPLAIN 等唯讀查詢，拒絕任何寫入。IAM 權限仍是主要的安全邊界，此開關提供額外的縱深防禦。
最大列數	進階任務設定	否	10000	查詢結果最多回傳的列數，可填 1～10000。超過會被截斷（輸出的 `truncated` 會標示）。
等待逾時	進階任務設定	否	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 取欄位名稱。

下一步¶

用程式碼 (Code) 任務重組查詢結果，再交給下游步驟。
把查到的資料餵給 LLM 任務或 Structured LLM 任務，產生有資料依據的回答。
若要查的是自管的關聯式資料庫，改用 MySQL 任務。
回到任務通用設定了解輸入與輸出、錯誤處理等共用分區。