文件
首頁 GitHub

API 參考

可直接使用 ToriiDB Go API 建立內嵌式儲存，或透過 Exec 路由文字指令。

Import

import (
    "github.com/pardnchiu/toriidb/core/store"
    "github.com/pardnchiu/toriidb/core/store/filter"
)

生命週期

func New(path ...string) (*Store, error)
func (s *Store) Session() *Session
func (s *Store) Close() error

New 接受零個或一個 storage root，並初始化 16 個延遲載入的 database descriptor。Session 共用資料庫、embedding 設定與背景工作，但保有獨立 selected index。Close 會等待 vector job 並壓縮已載入資料庫。

資料庫切換

func (c *core) Current() int
func (c *core) Select(index int) error

這些方法會提升到 Store 與 Session。有效 index 為 0 到 15。

指令路由器

func (c *core) Exec(input string) string

Exec 解析並執行 Redis-like command language，適合 REPL 與文字介面；直接呼叫方法則可取得 typed return value。

Entry 與型別

type Entry struct {
    Key       string
    Type      ValueType
    CreatedAt int64
    UpdatedAt *int64
    ExpireAt  *int64
    Vector    []float32
}

func (e *Entry) Value() string
func (e *Entry) JSON() ([]byte, error)
func (t ValueType) String() string

Raw value field 刻意設為未匯出。使用 Value 讀取，並以 JSON 序列化完整持久化表示。

寫入操作

type SetFlag int

const (
    SetDefault SetFlag = iota
    SetNX
    SetXX
)

func (c *core) Set(key, value string, flag SetFlag, expireAt *int64) error
func (c *core) SetField(key string, subKeys []string, value string, flag SetFlag, expireAt *int64) error
func (c *core) Incr(key string, delta float64) (float64, error)
func (c *core) IncrField(key string, subKeys []string, delta float64) (float64, error)
func (c *core) Del(keys ...string) int
func (c *core) DelField(key string, subKeys []string) error

expireAt 是絕對 Unix timestamp。Field method 會操作頂層 JSON object 與明確 subkey path。

讀取操作

func (c *core) Get(key string) (*Entry, bool)
func (c *core) GetField(key string, subKeys []string) (string, bool)
func (c *core) Exist(key string) string
func (c *core) ExistField(key string, subKeys []string) string
func (c *core) Type(key string) string
func (c *core) TypeField(key string, subKeys []string) string
func (c *core) Keys(pattern string) []string

Get 與 GetField 提供 typed presence boolean。Exist 與 Type 回傳和 Exec 相同的文字形式。

過期操作

func (c *core) TTL(key string) int64
func (c *core) Expire(key string, seconds int64) error
func (c *core) ExpireAt(key string, timestamp int64) error
func (c *core) Persist(key string) error

TTL 對 missing 或 expired key 回傳 -2，對無 expiration 的 key 回傳 -1。

Find 與 Query

func (c *core) Find(op filter.Operator, value string, limit int) []string
func (c *core) Query(f filter.Filter, limit int) []string

非正數 limit 代表不設定明確結果上限。結果由新到舊排序。

Filter package 提供：

type Filter interface {
    Match(obj any) bool
}

type Cond struct {
    Field string
    Op    Operator
    Value string
}

func AtoFilter(str string) (Filter, error)
func AtoOperation(s string) (Operator, bool)
func Match(stored string, op Operator, target string) bool

可組合 type 包含 And、Or、Not、EQ、NE、GT、GTE、GE、LT、LTE、LE 與 LIKE。

向量操作

func (c *core) SetVector(ctx context.Context, key, value string, flag SetFlag, expireAt *int64) error
func (c *core) VSearch(ctx context.Context, text, pattern string, k int) ([]string, error)
func (c *core) VSim(key1, key2 string) (float64, error)
func (c *core) VGet(key string) ([]float32, bool)

SetVector 同步儲存文字，再於背景附加 vector。VSearch 在 cache miss 時同步嵌入 query，且 k <= 0 時預設使用 10。VGet 回傳 defensive copy。

Utility Package

func WalkKeys(obj any, subKeys []string) (any, bool)
func WriteFile(path string, content []byte, perm os.FileMode) error
func Atov(text string) any
func Vtoa(value any) string
func Vtof(value any) (float64, bool)

這些 helper 支援巢狀 JSON traversal、atomic file replacement 與 value conversion。

最小範例

db, err := store.New("./data")
if err != nil {
    log.Fatal(err)
}
defer db.Close()

if err := db.Set("counter", "1", store.SetDefault, nil); err != nil {
    log.Fatal(err)
}
value, err := db.Incr("counter", 1)
if err != nil {
    log.Fatal(err)
}
fmt.Println(value)

相關頁面

EN