> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# 儲存空間概觀

Mastra 儲存空間以 domain 組織。每個 domain 都擁有一組資料表或 collection。視 adapter 與設定而定，你可以使用所有 domain，或只使用其中一部分。

## 儲存 domain

`MastraCompositeStore` 可以路由下列 domain key：

並非每個儲存 adapter 都會實作所有 domain。只要 adapter 套件匯出對應的 domain 類別，複合儲存空間就能讓你為各 domain 混用不同 adapter。

| Domain                | 說明                                                                                                        |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| `memory`              | 對話持久化：訊息、thread 與資源（包括 working memory）。                                                                   |
| `workflows`           | 用於暫停與繼續執行的 Workflow run snapshot。                                                                         |
| `workflowDefinitions` | 持久化的[動態 Workflow](https://mastra.zisheng.pro/zh-TW/docs/workflows/dynamic-workflows) 定義（beta）。啟動時載入並即時註冊。 |
| `scores`              | 評估執行所產生的評估分數記錄。                                                                                           |
| `observability`       | 供可觀測性 exporter 與 Studio 使用的 Trace 和 span。                                                                 |
| `datasets`            | 實驗使用的 dataset 記錄、版本化項目與 dataset 版本。                                                                       |
| `experiments`         | 實驗執行與各項目的實驗結果。                                                                                            |

下列 schema 定義涵蓋 `memory`、`workflows`、`scores` 與 `observability` 中有文件說明、以資料庫為基礎的內建資料表。其他 domain 與非資料庫 adapter 則使用各實作專屬的儲存結構。

## 核心 schema

**訊息**:

儲存對話訊息及其 metadata。每則訊息都屬於一個 thread，並包含實際內容，以及傳送者角色與訊息型別的 metadata。

iduuidv4PRIMARYKEYNOT NULL訊息的唯一識別碼（格式：`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）thread\_iduuidv4FK → threads.idNOT NULL父 thread 參照resourceIduuidv4CAN BE NULL擁有此訊息之資源的 IDcontenttextNOT NULLV2 格式的訊息內容 JSON。範例：`{ format: 2, parts: [...] }`roletextNOT NULL`user | assistant` 列舉值createdAttimestampNOT NULL用於排列 thread 訊息

訊息的 `content` 欄位包含符合 `MastraMessageContentV2` 型別的 JSON 物件；此型別的設計與 AI SDK 的 `UIMessage` 訊息結構緊密對應。

formatintegerNOT NULL訊息格式版本（目前為 2）partsarray (JSON)NOT NULL訊息部分的陣列（文字、Tool 呼叫、檔案、推理等）。此陣列中的項目結構會依 `type` 而異。experimental\_attachmentsarray (JSON)CAN BE NULL選用的檔案附件陣列contenttextCAN BE NULL選用的訊息主要文字內容toolInvocationsarray (JSON)CAN BE NULL選用的陣列，用於彙整 Tool 呼叫與結果reasoningobject (JSON)CAN BE NULL關於 assistant 回應背後推理過程的選用資訊annotationsobject (JSON)CAN BE NULL選用的其他 metadata 或註解

**Thread**:

將相關訊息組合在一起並與資源建立關聯。包含對話的 metadata。

iduuidv4PRIMARYKEYNOT NULLThread 的唯一識別碼（格式：`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）resourceIdtextNOT NULL此 thread 所關聯外部資源的主要識別碼。用於分組及擷取相關 thread。titletextNOT NULL對話 thread 的標題metadatatext以 JSON 字串表示的自訂 thread metadata。範例：

```json
{
  "category": "support",
  "priority": 1
}
```

createdAttimestampNOT NULLupdatedAttimestampNOT NULL用於排列 thread 歷程

**資源**:

儲存資源範圍 working memory 的使用者專屬資料。每個資源代表一名使用者或實體，讓 working memory 能跨該使用者的所有對話 thread 持久保存。

idtextPRIMARYKEYNOT NULL資源識別碼（使用者或實體 ID）：與 thread 和 Agent 呼叫中使用的 resourceId 相同workingMemorytextCAN BE NULL以 Markdown 文字表示的持久 working memory 資料。包含可跨對話 thread 持久保存的使用者個人資料、偏好與上下文資訊。metadatajsonbCAN BE NULL以 JSON 表示的其他資源 metadata。範例：

```json
{
  "preferences": {
    "language": "en",
    "timezone": "UTC"
  },
  "tags": [
    "premium",
    "beta-user"
  ]
}
```

createdAttimestampNOT NULL資源記錄首次建立的時間updatedAttimestampNOT NULLWorking memory 上次更新的時間

**Workflow**:

對 Workflow 呼叫 `suspend()` 時，其狀態會以下列格式儲存。呼叫 `resume()` 時，則會還原該狀態。

workflow\_nametextNOT NULLWorkflow 名稱run\_iduuidv4NOT NULLWorkflow 執行的唯一識別碼。用於追蹤暫停／繼續執行週期中的狀態（格式：`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）snapshottextNOT NULL以 JSON 序列化的 Workflow 狀態。範例：

```json
{
  "value": {
    "currentState": "running"
  },
  "context": {
    "stepResults": {},
    "attempts": {},
    "triggerData": {}
  },
  "activePaths": [],
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1648176000000
}
```

createdAttimestampNOT NULLupdatedAttimestampNOT NULL上次修改時間，用於追蹤 Workflow 執行期間的狀態變更

**Evals**:

儲存針對 Agent 輸出執行指標所得的評估結果。

inputtextNOT NULL提供給 Agent 的輸入outputtextNOT NULLAgent 產生的輸出resultjsonbNOT NULL包含分數與詳細資料的評估結果資料。範例：

```json
{
  "score": 0.95,
  "details": {
    "reason": "回應準確反映來源資料",
    "citations": [
      "第 1 頁",
      "第 3 頁"
    ]
  }
}
```

agent\_nametextNOT NULLmetric\_nametextNOT NULL例如 Faithfulness、Hallucination 等。instructionstextNOT NULLAgent 的 system prompt 或指示test\_infojsonbNOT NULL其他測試 metadata 與設定global\_run\_iduuidv4NOT NULL將相關評估執行分組（例如一次 CI 執行中的所有單元測試）run\_iduuidv4NOT NULL受評估執行的唯一識別碼（格式：`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）created\_attimestampNOT NULL

**Trace**:

擷取 OpenTelemetry Trace，以供監控與除錯。

idtextNOT NULLPRIMARYKEY唯一的 Trace 識別碼parentSpanIdtext父 span 的 ID。若 span 位於最上層則為 NullnametextNOT NULL階層式操作名稱（例如 `workflow.myWorkflow.execute`、`http.request`、`database.query`）traceIdtextNOT NULL用來將相關 span 分組的根 Trace 識別碼scopetextNOT NULL建立 span 的 library／套件／服務（例如 `@mastra/core`、`express`、`pg`）kindintegerNOT NULL`INTERNAL`（0，處理程序內）、`CLIENT`（1，對外呼叫）、`SERVER`（2，傳入呼叫）、`PRODUCER`（3，建立非同步工作）、`CONSUMER`（4，處理非同步工作）attributesjsonb包含 span metadata 的使用者自訂 key-value pairstatusjsonb包含 `code`（UNSET=0、ERROR=1、OK=2）與選用 `message` 的 JSON 物件。範例：

```json
{
  "code": 1,
  "message": "HTTP request failed with status 500"
}
```

eventsjsonbSpan 期間發生且附有時間戳記的事件linksjsonb與其他相關 span 的連結othertext以 JSON 字串表示的其他 OpenTelemetry span 欄位。範例：

```json
{
  "droppedAttributesCount": 2,
  "droppedEventsCount": 1,
  "instrumentationLibrary": "@opentelemetry/instrumentation-http"
}
```

startTimebigintNOT NULLSpan 開始時距 Unix epoch 的奈秒數endTimebigintNOT NULLSpan 結束時距 Unix epoch 的奈秒數createdAttimestampNOT NULL