# 寫入 JSON 欄位

本頁說明 ToriiDB 如何設定、遞增與刪除已儲存 JSON 文件中的單一欄位。

## 寫入欄位

```text
SET user.profile.level 2
SET user.profile.active true
SET user.tags.1 database
SET user.meta {"source":"import"}
```

值文字以 `utils.Atov` 轉換：

| 文字 | 儲存為 |
|---|---|
| `null` | JSON null（父層為 object 時刪除該欄位） |
| `true` / `false` | 布林 |
| 整數 / 浮點數 | 數字 |
| 可解析的 `{...}` / `[...]` | object / array |
| 其他 | 字串 |

| 情況 | 結果 |
|---|---|
| 鍵不存在 | 建立新 object |
| 鍵為非 JSON | 失敗：`not JSON type` |
| 鍵為頂層 array | 被只含寫入路徑的新 object 取代 |
| 中間欄位不存在 | 建立空 object |
| 中間欄位為純量 | 失敗 |
| Array 索引超出範圍或非數字 | 失敗；array 不會被延長 |
| `NX` / `XX` | 針對頂層鍵判斷 |
| 結尾秒數 | 設定過期；未帶時既有過期在記憶體中保留 |
| `VECTOR` | 拒絕：`error: VECTOR not supported on field-level SET` |

## 數值欄位

```text
INCR user.profile.level
INCR user.profile.score 0.5
```

`IncrField` 需要頂層 object 與既有的數值欄位，加上 delta 後以 `setParsed` 重寫文件，並把完整文件附加到 log。欄位不存在或非數值時失敗，不會建立任何內容。

## 刪除欄位

```text
DEL user.profile.active
```

只有單一帶點參數才會刪除欄位；`DEL a.b c` 會刪除頂層鍵 `a.b` 與 `c`。`DelField` 需要頂層 object。Object 欄位會被移除；array 元素會設為 `null` 而非縮短 array。路徑上不存在的中間 object 會在刪除前被建立為空 object。

## 相關頁面

- [JSON 文件](/zh/json-documents)
- [SET、DEL、INCR](/zh/cli-reference-write)
- [utils](/zh/api-reference-utils)