v0.7.0
Home GitHub

Core Concepts

Last updated

This page explains the handles you work with in ToriiDB: the store, sessions, databases, entries, and the reserved key namespace.

Store, Session, and Database

A Store owns 16 independent databases numbered 0 through 15. Each database has its own sync.RWMutex, in-memory map[string]*Entry, directory db_N/, and load-once guard. A database is replayed from disk the first time any operation touches it.

Handle Created by Shares Owns
Store store.New(dir, apiKey...) nothing all databases, embedder, background wait group, expiry timer
Session Store.Session() databases, embedder, wait group its own selected database index

Select(index) only changes the index of the handle it is called on and rejects values outside 0-15. The index is a plain int with no lock, so concurrent callers must each use their own Session; the daemon creates one per request for this reason.

Entries

type Entry struct {
    Key       string
    Type      ValueType
    CreatedAt int64
    UpdatedAt *int64
    ExpireAt  *int64
    Vector    []float32
    // value and parsed are unexported
}

Entry.Value() returns the raw string. The unexported parsed field caches the decoded JSON value and is only changed through setValue() or setParsed(), so it never drifts from the raw string. Get returns a copy of the entry taken under the read lock.

Reserved Namespace

Keys starting with __torii: hold internal data such as the embedding cache (__torii:embed:<sha256>). Scan-style operations skip them so they never leak into application results. Point lookups such as GET __torii:... are intentionally allowed for debugging.

中文