Skip to main content
分析資料是建立在原始資料與其他分析資料之上的 SQL 查詢。你在 資料建構器 中建立它： 一側是與建構器 Agent 的對話，另一側是分析資料的 SQL、結果與說明文件。發布會把 SQL 凍結成一個版本；實體化的分析資料還會產生 Agent 讀取的 Parquet 快照。

​
設定資料建構器（每個工作區一次）

建構器 Agent 和其他 Agent 一樣在沙盒中執行，因此需要執行環境。由 管理員 在 資料 -> 設定（建構器設定）中設定一次；設定適用於工作區內所有分析資料， 從下一次建構器回合起生效。 執行框架、沙箱環境與連線保險庫為必填：在設定完成之前，建構器不會執行。

​
新增其他原始資料

資料庫資料表透過 管理資料表 成為原始資料（請參閱連接資料來源）。 另外兩種原始資料由管理員新增。

​
檔案原始資料

檔案 中的 CSV、TSV 或 Parquet 檔案可以成為原始資料。不會另存副本： 每次查詢都讀取檔案當下的內容，所以原始資料永遠是最新的。
1

開始

在 資料 -> 連線 點選 連接原始資料，原始資料類型 選擇 工作區檔案。
2

選擇一個檔案

從檔案的 工作區 分頁或某個 Agent 的輸出中，選擇一個 .csv、.tsv 或 .parquet 檔案。資料夾與其他格式不能作為原始資料。
3

設定解析選項

輸入 原始資料名稱；分隔檔案還要設定 編碼（UTF-8、UTF-16、Big5、CP950、Latin-1 或 自動偵測）、分隔符號，以及 第一列為標題。
4

新增

勾選 同時建立分析資料，就會立刻為檔案建置並發布實體化快照（Agent 與 App 只能讀取 分析資料，不能讀取原始資料）。點選 新增原始資料。
原始資料的 SQL 名稱為 data.files.raw.<檔名>（或 data.files.outputs.<檔名>）。開啟它並使用 解析選項 修改選項，或覆寫偵測到的欄位型別（VARCHAR、BIGINT、DOUBLE、DECIMAL(38,9)、 BOOLEAN、DATE、TIMESTAMP），例如把開頭為 0 的編號保留為 VARCHAR。刪除原始資料不會 影響檔案本身。

​
查詢原始資料（Oracle）

在 Oracle 連線卡片上，新增查詢 會儲存一個由資料庫以自己的 SQL 方言執行的 SELECT。 用它讓 Oracle 先完成大型的關聯與篩選，再把結果交給 DataGen。
  • 每個資料表都必須寫成 schema.table，且位於連線設定的 schema 中。
  • 只讀取查詢結果，最多 100,000 列。查詢文字最多 20,000 個字元。
  • 檢查並儲存 會向資料庫取得結果欄位，同時驗證查詢。
這個原始資料的 SQL 名稱為 data.<連線別名>.query.<名稱>。

​
建立分析資料

有三種起點，每一種都會在新草稿上開啟資料建構器。

​
選擇模式

原生 SQL 分析資料依資料庫原本的方式命名資料表（不使用 data.* 名稱），不需要登錄資料表， 且一律實體化。分析 SQL 分析資料以 SQL 名稱讀取原始資料與其他分析資料。

​
使用 AI 資料建構器

建構器分為三個區域：
  • 側欄：對話（你的建構器對話）、設定（分析資料的檔案與設定）與 版本。
  • 建構器對話。
  • 分析資料檢視區，含 SQL、資料、結構 與 說明文件 分頁。
在對話中描述你要的分析資料。建構器 Agent 會探索目錄、撰寫 model.sql、依發布規則檢查、 可以啟動預覽，並撰寫分析資料的說明文件。你隨時可以自行編輯 model.sql。點選 儲存草稿 保存變更；儲存不會發布。
範例需求
在 設定 -> 原始資料 中限制建構器看得到的原始資料與分析資料，預設為 所有可用資產（預設）。範圍越小，建構器要搜尋的越少，也能避免分析資料讀到不該讀的資料表。

​
預覽

在 SQL 分頁，執行 SQL 會在背景執行目前的草稿。你可以繼續編輯或離開；預覽不會變更 已發布的資料。結果顯示在 資料 分頁，並保留 24 小時。執行詳情 會顯示實際執行的 SQL 與 下次預覽時限（分鐘）。建構器 Agent 也可以啟動預覽，這類預覽會標示 由代理啟動。

​
執行模式

在分析資料的設定中選擇 執行模式：
  • 即時查詢：每次讀取分析資料時執行已儲存的 SQL。
  • 實體化：把結果存成快照。Agent 與 App 讀取的就是它，更新排程也只更新它。

​
為分析資料撰寫說明

說明文件決定了 Agent 能否安全地使用分析資料。
  • 結構 分頁：資料集與每個欄位的說明，包括單位與業務規則。點選 儲存說明。
  • 說明文件 分頁：model.md，涵蓋粒度與鍵值、可加總的指標、關聯方式、資料來源脈絡與注意事項。 它與 SQL 一起儲存、一起發布，Agent 透過 datagen-data describe 讀取。可以請建構器撰寫， 也可以自己寫。

​
發布

1

檢閱

點選 發布資料集。檢閱發布 對話框會顯示名稱、執行模式與狀態。實體化分析資料可設定 建置逾時上限（1 到 60 分鐘）。
2

建置

再次點選 發布資料集 確認。實體化分析資料會排入佇列並建置成快照（排隊中，等待可用資源、 正在建置快照、快照已就緒）。建置失敗時點選 重試建置；在此期間先前的快照仍可使用。
3

上線

建置成功後，新版本會成為 上線中。已連結的 Agent 從建置完成後的第一次查詢起讀取新版本。

​
版本與回溯

版本 依新到舊列出每個發布過的版本，以及各版本保留的快照與資料列數。 還原定義不會還原原始資料的歷史資料列。要回溯實體化版本，該版本必須仍保有快照；若沒有， 請先還原至草稿再重新發布，用目前的資料重新建置。 每個分析資料保留的快照：目前使用中的快照、最近 3 次更新的快照，以及每個已發布版本的快照。 更舊的快照會自動移除。

​
更新

更新會重新執行 已發布 的 SQL 並存成新的快照。它不會修改 SQL、不會發布，也不會動到草稿。 開啟分析資料的 自動化 分頁：
  • 更新已發布資料：立即更新一次。
  • 新增自動化：建立排程。
排程以最後儲存或繼續它的人的權限執行（顯示為 以 的身分執行）。某次執行失敗時， 分析資料會繼續提供上次成功的資料；連續失敗 3 次後排程會自動暫停。排除原因後點選 繼續。

​
刪除分析資料

刪除分析資料 會移除分析資料及其版本、排程與 Agent 連結。讀取它的其他分析資料需要另外更新。

​
下一步

在 Agent 與 App 中使用資料

把發布後的分析資料連結到 Agent，並在沙盒中查詢。

datagen-data CLI

建構器與 Agent 查詢資料時使用的所有指令。