JSON Documents

Use dot notation to read and mutate nested JSON objects and arrays while ToriiDB keeps its parsed cache synchronized.

Stored Representation

A value is classified as json only when it is valid JSON and its outer value is an object or array. Each Entry keeps the serialized string in its unexported value field and may keep a parsed object in parsed.

Method	Role
`Value()`	Returns the raw serialized value
`JSON()`	Serializes all persisted entry fields, including the unexported value
`parseAndCache()`	Parses on cache miss; caller must hold a write lock or be single-threaded
`cached()`	Reads an already-warmed cache while a read lock is held
`setParsed(obj)`	Serializes and caches a modified object together

This design prevents the raw value and parsed representation from diverging.

Dot-Notation Paths

Exec splits the first dot into a top-level key and a list of subkeys:

user.profile.level
└── key: user
    └── path: profile, level

Object paths use field names. Array paths use decimal indexes:

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

Empty path components are ignored. Field operations require a JSON value at the top-level key.

Field Writes

A field-level SET calls SetField:

SET user.profile.level 2
SET user.profile.active true

Missing object maps are created automatically. Existing arrays may be traversed, but an array index must parse as an integer and remain within bounds. A scalar encountered before the final path component causes the operation to fail.

NX and XX are evaluated against the top-level key, not the individual field. VECTOR is not supported on field-level SET.

Field Reads and Types

GET user.profile.level
EXIST user.profile.level
TYPE user.profile.level

GetField holds the database read lock across entry lookup, cache access, and WalkKeys. Values are rendered through utils.Vtoa; TypeField then applies normal type detection to the rendered result.

Numeric Fields

IncrField requires the target to be numeric:

INCR user.profile.level
INCR user.profile.level 0.5

It reads the value through WalkKeys, converts it with Vtof, writes the result with setParsed, updates the entry timestamp, and persists the full document.

Field Deletion

A single dotted key passed to DEL deletes that field:

DEL user.profile.active

Object properties are removed. For an array path, deletion assigns JSON null to the selected element rather than shrinking the array.

Passing multiple keys to DEL performs top-level key deletion instead of field deletion.

Concurrency Rules

SetField, IncrField, and DelField hold the database write lock.
GetField and Query hold the read lock while accessing parsed objects.
Every JSON write path calls setParsed before releasing the write lock.
Replay warms parsed caches for JSON entries before concurrent reads begin.