> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 建立分析資料

> 新增檔案與查詢原始資料，用 AI 資料建構器建立分析資料，並預覽、撰寫說明、發布、回溯與更新

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

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

建構器 Agent 和其他 Agent 一樣在沙盒中執行，因此需要執行環境。由 **管理員** 在
**資料 -> 設定**（**建構器設定**）中設定一次；設定適用於工作區內所有分析資料，
從下一次建構器回合起生效。

| 設定 | 用途 |
| - | - |
| **執行框架** | 建構器回合使用的 Agent 執行環境（Harness）。請參閱 [Harness](/zh/foundation/harness)。 |
| **沙箱環境** | 建構器執行時使用的映像。請參閱[沙箱環境](/zh/foundation/sandbox-environments)。 |
| **連線保險庫** | 提供給建構器自身工具的憑證。連線憑證不從這裡取得。請參閱[連線保險庫](/zh/foundation/vault)。 |
| **工具** | 選填，給建構器使用的工具組。 |
| **參考知識庫（已發布）** | 建構器可以讀取的知識庫，例如你的指標定義。 |
| **技能（已核准）** | 安裝在建構器上的 Skill。 |
| **自訂提示詞** | 套用到工作區所有建構器的額外指示，最多 20,000 個字元。 |

執行框架、沙箱環境與連線保險庫為必填：在設定完成之前，建構器不會執行。

## 新增其他原始資料

資料庫資料表透過 **管理資料表** 成為原始資料（請參閱[連接資料來源](/zh/data/connect)）。
另外兩種原始資料由管理員新增。

### 檔案原始資料

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

<Steps>
  <Step title="開始">
    在 **資料 -> 連線** 點選 **連接原始資料**，**原始資料類型** 選擇 **工作區檔案**。
  </Step>

  <Step title="選擇一個檔案">
    從檔案的 **工作區** 分頁或某個 Agent 的輸出中，選擇一個 `.csv`、`.tsv` 或 `.parquet`
    檔案。資料夾與其他格式不能作為原始資料。
  </Step>

  <Step title="設定解析選項">
    輸入 **原始資料名稱**；分隔檔案還要設定 **編碼**（UTF-8、UTF-16、Big5、CP950、Latin-1 或
    **自動偵測**）、**分隔符號**，以及 **第一列為標題**。
  </Step>

  <Step title="新增">
    勾選 **同時建立分析資料**，就會立刻為檔案建置並發布實體化快照（Agent 與 App 只能讀取
    分析資料，不能讀取原始資料）。點選 **新增原始資料**。
  </Step>
</Steps>

原始資料的 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.<名稱>`。

## 建立分析資料

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

| 起點 | 做法 |
| - | - |
| 單一原始資料，原樣使用 | 開啟原始資料，點選 **建立分析資料**。草稿為 `SELECT * FROM <原始資料>`，實體化。 |
| 空白分析資料 | **資料集 -> 分析資料 -> 新增分析資料集**，輸入名稱、選擇 **模式**，再點選 **建立分析資料集**。 |
| 檔案 | 新增檔案原始資料時勾選 **同時建立分析資料**。這種會立即發布。 |

### 選擇模式

| 模式 | 在哪裡執行 | 適用情境 |
| - | - | - |
| **分析 SQL**（預設） | DataGen 內的 DuckDB，可跨任意原始資料與分析資料 | 要整合多個原始資料，或來自不同資料庫的原始資料。 |
| **原生 SQL** | 原樣在一個 PostgreSQL、MySQL 或 Oracle **連線** 上執行 | 希望資料庫先完成大型資料表的關聯、篩選與彙總。 |

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

## 使用 AI 資料建構器

建構器分為三個區域：

* 側欄：**對話**（你的建構器對話）、**設定**（分析資料的檔案與設定）與 **版本**。
* 建構器對話。
* 分析資料檢視區，含 **SQL**、**資料**、**結構** 與 **說明文件** 分頁。

在對話中描述你要的分析資料。建構器 Agent 會探索目錄、撰寫 `model.sql`、依發布規則檢查、
可以啟動預覽，並撰寫分析資料的說明文件。你隨時可以自行編輯 `model.sql`。點選 **儲存草稿**
保存變更；儲存不會發布。

```text 範例需求 theme={null}
建立一個分析資料，每位客戶每月一列：訂單數、營收與首次下單日期。
只計算已完成的訂單。請在說明文件中寫明粒度，以及哪些欄位可以加總。
```

<Tip>
  在 **設定 -> 原始資料** 中限制建構器看得到的原始資料與分析資料，預設為
  **所有可用資產（預設）**。範圍越小，建構器要搜尋的越少，也能避免分析資料讀到不該讀的資料表。
</Tip>

### 預覽

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

### 執行模式

在分析資料的設定中選擇 **執行模式**：

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

### 為分析資料撰寫說明

說明文件決定了 Agent 能否安全地使用分析資料。

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

## 發布

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

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

  <Step title="上線">
    建置成功後，新版本會成為 **上線中**。已連結的 Agent 從建置完成後的第一次查詢起讀取新版本。
  </Step>
</Steps>

## 版本與回溯

**版本** 依新到舊列出每個發布過的版本，以及各版本保留的快照與資料列數。

| 動作 | 效果 |
| - | - |
| **檢視版本** | 以唯讀方式開啟該版本的定義。 |
| **還原至草稿** | 以該版本的 SQL 與設定取代目前草稿。在你再次發布之前不會發布任何東西。 |
| **回復到此版本** | 立即把該版本及其保留的某個快照設為上線資料。你的工作草稿不受影響。 |

還原定義不會還原原始資料的歷史資料列。要回溯實體化版本，該版本必須仍保有快照；若沒有，
請先還原至草稿再重新發布，用目前的資料重新建置。

每個分析資料保留的快照：目前使用中的快照、最近 3 次更新的快照，以及每個已發布版本的快照。
更舊的快照會自動移除。

## 更新

更新會重新執行 **已發布** 的 SQL 並存成新的快照。它不會修改 SQL、不會發布，也不會動到草稿。
開啟分析資料的 **自動化** 分頁：

* **更新已發布資料**：立即更新一次。
* **新增自動化**：建立排程。

| 頻率 | 說明 |
| - | - |
| **每小時**、**每日**、**每週** | 選擇分鐘、時間或星期，以及 **時區**。 |
| **自訂（cron）** | 五個欄位：分 時 日 月 星期。最多每小時執行一次。 |
| **上游資料更新時** | 在這個分析資料讀取的實體化分析資料更新後執行，不依時鐘執行。 |

排程以最後儲存或繼續它的人的權限執行（顯示為 **以 {name} 的身分執行**）。某次執行失敗時，
分析資料會繼續提供上次成功的資料；連續失敗 3 次後排程會自動暫停。排除原因後點選 **繼續**。

## 刪除分析資料

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

## 下一步

<CardGroup cols={2}>
  <Card title="在 Agent 與 App 中使用資料" icon="plug" href="/zh/data/use">
    把發布後的分析資料連結到 Agent，並在沙盒中查詢。
  </Card>

  <Card title="datagen-data CLI" icon="terminal" href="/zh/developers/data-cli">
    建構器與 Agent 查詢資料時使用的所有指令。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.