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

# 1. 連接資料

> 連接資料庫、選擇資料表，並發布一個 Agent 與 App 都能讀取的分析模型

這份實作教學從頭到尾沿著同一條故事線進行。你會連接一個資料庫、加入文件、用這些文件建立知識庫、讓 Agent 運用資料與知識庫工作，最後把儀表板分享給團隊。每個部分都建立在前一部分之上。

| 部分 | 你會建立 |
| - | - |
| **1. 連接資料**（本頁） | 一個資料庫連線與一個已發布的分析模型 |
| [2. 上傳檔案](/zh/tutorial/02-upload-files) | 檔案中一個存放參考文件的資料夾 |
| [3. 建立知識庫](/zh/tutorial/03-build-context) | 由這些文件建立、有版本的知識庫 |
| [4. 建立 Agent](/zh/tutorial/04-build-agent) | 一個使用模型與知識庫、回答問題，並每週把報告發到 Slack 的 Agent |
| [5. 發布 App](/zh/tutorial/05-ship-an-app) | 一個分享給團隊的 marimo 儀表板 |

在這一部分，你會連接一個 PostgreSQL 資料庫、選擇要開放的資料表，並發布一個**分析模型**——一個可重複使用、有版本的資料集，供 Agent 與 App 讀取。

## 開始之前

* 一個你擁有「**建構者**」或「**管理員**」角色的 DataGen 工作區。
* 一個 PostgreSQL 資料庫的連線資訊，最好使用唯讀角色。

<Note>
  DataGen 透過你提供的資料庫角色讀取來源。請使用只能對要使用的資料表執行 `SELECT` 的角色：查詢能看到該角色可讀取的所有內容。你的管理員也必須在分析 worker 上允許該資料庫主機。
</Note>

## 1. 開啟資料

在左側導覽列點選「**更多**」，再點選「**資料**」。若要讓「資料」固定顯示在導覽列，可以在同一個選單中釘選它。

資料頁面有三個分頁：「**資料集**」、「**連線**」與「**設定**」。

## 2. 新增連線

<Steps>
  <Step title="開始建立連線">
    開啟「**連線**」分頁，點選「**連接原始資料**」。
  </Step>

  <Step title="選擇 PostgreSQL">
    「**原始資料類型**」維持選取 **PostgreSQL**。
  </Step>

  <Step title="填寫表單">
    | 欄位 | 值 |
    | - | - |
    | 連線名稱 | 團隊認得出來的名稱。 |
    | SQL 別名 | 小寫英文字母、數字與底線。SQL 用這個名稱指稱此連線，即使連線改名也不會變。 |
    | 主機 | |
    | 連接埠 | `5432`，除非你的資料庫使用其他連接埠 |
    | 資料庫 | |
    | 使用者名稱／密碼 | 唯讀角色。 |
    | Schema（以逗號分隔） | `public`，或存放資料表的 schema。 |
  </Step>

  <Step title="選擇 TLS 模式">
    對於代管或公開的資料庫，「**TLS**」維持「**驗證憑證與主機名稱**」。其他模式適用於私有網路與本機開發。
  </Step>

  <Step title="儲存">
    點選「**儲存連線**」。連線卡片會出現在「**連線**」分頁。
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/datagen/rusBmwP8bd_Srmdm/images/browser-guide/zh/connect-postgres.jpg?fit=max&auto=format&n=rusBmwP8bd_Srmdm&q=85&s=ac540b0b74419a42509d7623a96a1214" alt="新增 PostgreSQL 連線表單；尚未填入或儲存" width="838" height="863" data-path="images/browser-guide/zh/connect-postgres.jpg" />
</Frame>

## 3. 選擇資料表

在你選擇資料表之前，連線不會開放任何資料表。

1. 在連線卡片上點選「**管理資料表**」。
2. 搜尋或依 schema 篩選，然後選取需要的資料表。
3. 點選「**儲存資料表選取**」。

每個選取的資料表都會成為「**資料集**」分頁中的一個**來源**。開啟來源可以預覽最多 500 列資料。

<Frame>
  <img src="https://mintcdn.com/datagen/rusBmwP8bd_Srmdm/images/browser-guide/zh/data-catalog.jpg?fit=max&auto=format&n=rusBmwP8bd_Srmdm&q=85&s=b2b7e54179f59f34572b658019e35bbf" alt="Neon test 連線的原始資料表清單" width="838" height="863" data-path="images/browser-guide/zh/data-catalog.jpg" />
</Frame>

## 4. 建立分析模型

來源是原始資料。分析模型則保存你的邏輯——合併、篩選、業務規則——而它發布後的快照，就是 Agent 與 App 讀取的內容。

<Steps>
  <Step title="建立模型">
    開啟「**資料集**」分頁，前往「**分析資料**」，點選「**新增分析資料集**」。輸入名稱，「**模式**」維持「**分析 SQL**」，然後點選「**建立分析資料集**」。

    **資料建構器**會開啟：左側是對話與設定，中間是 AI 對話，右側是 SQL、結果、結構與說明文件。
  </Step>

  <Step title="描述你要的資料集">
    在對話中描述這個資料集。建構器會找出相關來源，並替你撰寫 `model.sql`。

    ```text 範例提示 theme={null}
    <描述模型：要合併的資料表、每一列代表什麼、要計算的指標>
    ```
  </Step>

  <Step title="檢查結果">
    開啟「**結果**」分頁，點選「**執行 SQL**」預覽輸出。持續請建構器修改，直到資料列看起來正確為止。
  </Step>

  <Step title="撰寫說明">
    請建構器撰寫說明文件（`model.md`），或在「**說明文件**」分頁自行撰寫：資料粒度、鍵、指標與注意事項。Agent 查閱模型時會讀取這份說明。在「**結構**」分頁加入欄位說明。
  </Step>

  <Step title="儲存草稿">
    點選「**儲存草稿**」。
  </Step>
</Steps>

## 5. 發布模型

1. 在「**設定**」中確認模型為「**實體化**」（新模型的預設值）。Agent 只能連結實體化的模型。
2. 點選「**發布資料集**」，檢閱發布內容後，再點選一次「**發布資料集**」。

模型現在有了已發布的版本 **v1**。「**版本**」分頁會列出每個已發布的版本，你可以回溯到其中任何一個。

<Tip>
  若要讓模型保持最新，請開啟「**設定**」並點選「**開啟自動化**」，再點選「**新增自動化**」。排程更新會重新執行已發布的 SQL，不會修改 SQL，也不會發布新版本。
</Tip>

## 你完成了什麼

* 一個 PostgreSQL 連線，並把選取的資料表設為來源。
* 一個已發布、實體化的分析模型，附有 Agent 能讀取的說明文件。

進一步了解：[連接資料來源](/zh/data/connect)、[建立分析資料](/zh/data/build-models)與[使用資料](/zh/data/use)。

<CardGroup cols={2}>
  <Card title="上一步：核心概念" icon="arrow-left" href="/zh/overview/core-concepts">
    構件之間如何掛載。
  </Card>

  <Card title="下一步：上傳檔案" icon="arrow-right" href="/zh/tutorial/02-upload-files">
    加入知識庫要使用的參考文件。
  </Card>
</CardGroup>


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