Documentation
Home GitHub

Querying

Search keys, compare stored values, and filter JSON documents with ToriiDB scan commands.

Query Commands

Command Scope Result ordering
KEYS Top-level key names Lexicographic
FIND Complete raw entry values Newest entry first
QUERY Fields inside JSON documents Newest entry first

All scan commands skip expired entries and reserved __torii:* internal keys.

KEYS

KEYS <pattern>

KEYS applies Go path.Match to each top-level key:

KEYS *
KEYS user:*
KEYS cache:?

Invalid patterns do not match. Results are sorted lexicographically. Dot notation is not interpreted here; the pattern is matched against the entire top-level key.

FIND

FIND <op> <value> [LIMIT <n>]

FIND compares each entry's complete raw value:

FIND eq active
FIND gt 100 LIMIT 20
FIND like *database* LIMIT 10

Supported operators are:

Names Meaning
EQ, = Exact string equality
NE, != String inequality
GT, > Numeric greater than
GTE, GE, >= Numeric greater than or equal
LT, < Numeric less than
LTE, LE, <= Numeric less than or equal
LIKE Text pattern matching

Numeric operators return no match unless both stored and target values parse as floating-point numbers.

LIKE Patterns

LIKE treats leading and trailing * specially:

Pattern Match behavior
prefix* Stored value starts with prefix
*suffix Stored value ends with suffix
*part* Stored value contains part
part Stored value contains part
* Matches every value

The implementation is a text matcher, not a regular-expression engine.

QUERY

QUERY <expression> [LIMIT <n>]

QUERY evaluates conditions against parsed JSON documents. Field names may use dot notation:

QUERY active = true
QUERY profile.level >= 3
QUERY role = admin AND active = true LIMIT 20
QUERY ( role = admin OR role = editor ) AND NOT disabled = true

Entries that are not JSON, or whose parsed cache is unavailable, are skipped. Missing fields do not satisfy a condition.

Expression Grammar

The expression parser supports:

expression := or
or         := and (OR and)*
and        := not (AND not)*
not        := NOT not | primary
primary    := "(" expression ")" | field operator value

Operator names are case-insensitive. AND binds more tightly than OR, and NOT recursively applies to the next expression.

Input is tokenized by whitespace. Parentheses may be attached to neighboring tokens because the parser peels leading ( and trailing ), but values themselves cannot contain unquoted whitespace as a single operand.

Programmatic Filters

The filter package exposes composable filters:

f := filter.And{
    filter.GTE{Field: "profile.level", Value: "3"},
    filter.EQ{Field: "active", Value: "true"},
}
keys := db.Query(f, 20)

Available condition types include EQ, NE, GT, GTE, GE, LT, LTE, LE, and LIKE. filter.AtoFilter parses the same infix grammar used by the QUERY command.

Limits and Ordering

FIND and QUERY sort matches by UpdatedAt when present, otherwise CreatedAt, newest first. Display text breaks timestamp ties. A positive trailing LIMIT n truncates after sorting; omitted or invalid limits mean no explicit limit.

For large scans, ToriiDB processes key slices in blocks of 1024 and merges the collected results before sorting.

中文