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

# 儲存概覽

Mastra 儲存按域劃分。每個域擁有一組資料表或 collection。視乎你的 adapter 及設定，你可以使用所有域或只使用其中一部分。

## 儲存域

`MastraCompositeStore` 可以路由以下域 key：

並非每個儲存 adapter 都會實作所有域。當 adapter 套件有匯出對應的域 class 時，複合儲存可讓你為每個域混合使用 adapter。

| Domain                | 說明                                                                                                         |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `memory`              | 持久儲存對話：訊息、thread 及 resource（包括 working memory）。                                                            |
| `workflows`           | 用於暫停及恢復的 Workflow 執行快照。                                                                                    |
| `workflowDefinitions` | 持久儲存的[動態 Workflow](https://mastra.zisheng.pro/zh-HK/docs/workflows/dynamic-workflows) 定義（beta）。啟動時載入並即時註冊。 |
| `scores`              | Evals 執行產生的評估分數記錄。                                                                                         |
| `observability`       | observability exporter 及 Studio 所用的 Trace 與 span。                                                          |
| `datasets`            | 實驗所用的 dataset 記錄、版本化項目及 dataset 版本。                                                                        |
| `experiments`         | 實驗執行及逐項實驗結果。                                                                                               |

以下結構描述定義涵蓋 `memory`、`workflows`、`scores` 及 `observability` 的內置資料庫支援資料表。其他域及非資料庫 adapter 會使用實作特定的儲存結構。

## 核心結構描述

**訊息**:

儲存對話訊息及其 metadata。每則訊息均屬於一個 thread，並包含實際內容，以及傳送者 role 及訊息類型的 metadata。

iduuidv4PRIMARYKEYNOT NULL訊息的唯一識別碼（格式：`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）thread\_iduuidv4FK → threads.idNOT NULL上層 thread 參照resourceIduuidv4CAN BE NULL擁有此訊息的 resource 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**:

將相關訊息分組並與 resource 關聯。包含對話的 metadata。

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

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

createdAttimestampNOT NULLupdatedAttimestampNOT NULL用於排列 thread 歷史記錄

**Resource**:

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

idtextPRIMARYKEYNOT NULLResource 識別碼（使用者或實體 ID）：與 thread 及 Agent 調用所用的 resourceId 相同workingMemorytextCAN BE NULL以 Markdown 文字儲存的持久 working memory 資料。包含跨對話 thread 持續保留的使用者個人檔案、偏好及情境資料。metadatajsonbCAN BE NULLJSON 格式的其他 resource metadata。範例：

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

createdAttimestampNOT NULL首次建立 resource 記錄的時間updatedAttimestampNOT NULL最後更新 working 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 輸出執行指標後所得的 Evals 結果。

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

```json
{
  "score": 0.95,
  "details": {
    "reason": "Response accurately reflects source material",
    "citations": [
      "page 1",
      "page 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

**Traces**:

擷取 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 的程式庫／套件／服務（例如 `@mastra/core`、`express`、`pg`）kindintegerNOT NULL`INTERNAL`（0，處理程序內）、`CLIENT`（1，向外調用）、`SERVER`（2，傳入調用）、`PRODUCER`（3，建立非同步工作）、`CONSUMER`（4，處理非同步工作）attributesjsonb包含 span metadata、由使用者定義的鍵值配對statusjsonb包含 `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