核心概念

本頁說明 ToriiDB 的 store、entry、型別、JSON 欄位、過期與查詢語意。

Store、Session 與資料庫

一個 Store 擁有 16 個彼此獨立的資料庫。新的 store 從資料庫 0 開始，Select(index) 接受 0 到 15 的索引。各資料庫有獨立的記憶體與持久化檔案。

Store.Session() 會建立輕量的 Session，共用所有儲存資料與 embedding 設定，但保有獨立的目前資料庫索引。多個呼叫端因此可透過同一個 store 操作不同的邏輯資料庫。

Store 不再使用時應一律呼叫 Close()。關閉會等待非同步向量附加完成，並壓縮已載入的 AOF 檔案。

Entry 與值型別

每個鍵值對應一個 Entry，其中包含 key、raw value、偵測出的 ValueType、建立與更新 timestamp、選用的 expiration、選用的 vector，以及內部 parsed JSON cache。

Entry.Value() 會公開原始字串。Entry.JSON() 序列化完整的持久化表示，包含原本未匯出的 raw value。

Set 語意

Set 預設為 upsert。SetNX 只在頂層鍵不存在時成功，SetXX 只在鍵已存在時成功。指令形式接受相同旗標：

SET <key> <value> [NX|XX] [seconds] [VECTOR]

尾端正整數 seconds 會轉成絕對過期時間。一般覆寫會清除既有 vector，因為舊 embedding 已無法代表新值。

JSON 文件與點記法

指令會把 key.field.nested 的第一個點切成頂層鍵與巢狀路徑。Map 使用 property name；array 使用十進位 index。

SET user {"name":"Torii","profile":{"level":1},"tags":["go","db"]}
GET user.profile.level
SET user.profile.level 2
GET user.tags.0
DEL user.profile.level

欄位層級 SET 會建立缺少的 map 層級，但不會擴充 array。Array index 必須已存在且在範圍內。欄位修改要求頂層值為 JSON object。

Parsed cache 可避免重複解碼 JSON。所有 JSON 寫入路徑都會在釋放資料庫寫鎖前，同步更新 raw serialized value 與 parsed object。

數值修改

INCR <key> [delta] 會修改既有 integer 或 float。使用點記法時，IncrField 會在 parsed JSON object 中找到數值、加上 delta，再持久化完整文件。

缺少 key、缺少 field、非數值或無效 array path 都會失敗，不會建立新的數值 entry。

過期

點讀取、掃描指令與每分鐘一次的清理計時器都會套用過期判斷。即使實體清理尚未執行，超過 timestamp 的鍵值也會被視為不存在。

掃描與查詢

KEYS 使用 Go path.Match glob 語法比對頂層鍵，並依字典順序排序。FIND 比較完整 raw value，最新 entry 優先回傳。QUERY 對 JSON 文件欄位計算條件，同樣最新 entry 優先。

支援的比較運算子包括 EQ/=、NE/!=、GT/>、GTE/GE/>=、LT/<、LTE/LE/<= 與 LIKE。數值排序運算子要求兩側 operand 都能解析為數字。

FIND like *database* LIMIT 10
QUERY profile.level >= 2 AND active = true LIMIT 10
QUERY ( role = admin OR role = editor ) AND NOT disabled = true

AND 優先於 OR；NOT 遞迴套用到下一個 expression；括號用於分組。由於 tokenization 以空白為基礎，括號應獨立分隔，或以 parser 可接受的形式貼在相鄰 token 上。

保留命名空間

__torii: prefix 保留給 embedding cache entry 等內部記錄。掃描型操作會隱藏這些記錄，避免出現在一般應用結果中。點查詢刻意不封鎖，方便除錯時檢查。