Concepts

These pages explain storage, query execution, and result guarantees. Read them in order for an overview or select a topic below. For commands and flags, use the CLI reference.

The storage model separates published data from disposable query state:

Object storage plus the catalog generation lineage is the only authority. Local caches can be rebuilt from objects. Capacity and cache-residency observations guide placement; workers enforce admission at dispatch.

Page	Answers
Why YoloSearch	Intended workloads, storage and execution choices, and current limits
Architecture	The roles, the single binary, the gRPC surface, and where consensus is and is not allowed
Segments and objects	What a segment physically is, the object layout, and the three identifiers a document has
Catalog and generations	How a written segment becomes visible, how versions and deletes resolve, and how compaction and GC reclaim
Storage modes and caching	Where a reader gets its bytes, every cache layer and its budget, and what warms on a repeat
The query lifecycle	What happens between a query string and a result frame, including failure behavior
Ranking and exactness	BM25F, the bounded scoring algebra, the exact-prefix proof, tie order, and approximate tail ordering

• Segment — the unit of immutability, publication, caching, placement, and compaction. One immutable WavesDB checkpoint in one object prefix.
• Generation — an immutable catalog record naming the complete active segment set. A query pins exactly one.
• Public ID — the deterministic 128-bit document identity used in result frames and tie ordering.
• Logical key — the schema field marked key. It defines upsert identity.
• Exact prefix — the leading run of results whose ordering is established by score bounds and deterministic tie handling.
• Storage mode — HYDRATE_FULL, REMOTE_BLOCKS, or AUTO: where an immutable reader gets checkpoint bytes. It never changes query semantics.

Longer definitions are in the glossary.

The quick start walks through a local server, sample schema, document load, and query.