Documentation
Home GitHub

API Reference

Use the ToriiDB Go API directly for embedded storage, or route command strings through Exec.

Import

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

Lifecycle

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

New accepts zero or one storage root and initializes 16 lazy database descriptors. Session shares databases, embedding configuration, and background work while keeping its own selected index. Close waits for vector jobs and compacts loaded databases.

Database Selection

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

These methods are promoted through Store and Session. Valid indexes are 0 through 15.

Command Router

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

Exec parses and executes the Redis-like command language. It is useful for REPLs and textual interfaces; direct methods provide typed return values.

Entry and Types

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

The raw value field is intentionally unexported. Use Value to read it and JSON to serialize the complete persisted representation.

Write Operations

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 is an absolute Unix timestamp. Field methods operate on a top-level JSON object and an explicit subkey path.

Read Operations

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 and GetField provide typed presence booleans. Exist and Type return the same textual forms used by Exec.

Expiration

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 returns -2 for a missing or expired key and -1 for a key without expiration.

Find and Query

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

A non-positive limit means no explicit result limit. Results are ordered newest first.

The filter package provides:

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

Composable types include And, Or, Not, EQ, NE, GT, GTE, GE, LT, LTE, LE, and LIKE.

Vector Operations

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 stores text synchronously and attaches its vector in the background. VSearch embeds the query synchronously on a cache miss and defaults to k = 10 when k <= 0. VGet returns a 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)

These helpers support nested JSON traversal, atomic file replacement, and value conversion.

Minimal Example

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)
中文