Architecture

A search request is parsed, run against the inverted index and any filters in parallel, ranked with BM25, and returned:

For multi-term queries, execution uses block-max WAND pruning: the index tracks the maximum possible score contribution of each block of postings, so blocks that can't beat the current top-K results are skipped without being fully scored — the same candidate set and ranking as scoring everything, done in less work.

Text fields are tokenized — alphanumeric runs become tokens, Unicode-normalized (NFD) with combining marks stripped, then lowercased and truncated at 64 characters. Han ideographs are segmented individually as standalone tokens; there is no stemming and no stop-word removal, so "running" and "run" are distinct tokens today. The inverted index maps each token to the postings list of documents containing it.

Ranking uses BM25, the standard lexical relevance function used across full-text search engines: term frequency in a document is rewarded, discounted by how common a term is across the whole collection, and normalized for document length. Fields can carry an optional per-field boost multiplier declared on the schema.

New documents land in an in-memory memtable behind a write-ahead log. Once the memtable crosses --max-memtable-docs (default 100,000), it's flushed into a new, immutable, memory-mapped segment on disk. Every write goes through the WAL first — see Persistence for the durability guarantees that follow from that.

Each segment is a set of files — terms (an FST map), postings (fixed-size blocks with per-block skip metadata: max doc id, max term frequency, byte offset), columnar field values, and document bodies — each with a small magic-number and version header. Postings and column data are read lazily via mmap and decoded only for what a query actually touches, which is what keeps memory usage proportional to how much of the corpus is actively queried rather than to total corpus size.

Because a search fans out across every committed segment plus the current memtable, segment count drives query latency independent of corpus size. A background tiered merge keeps that bounded: once a collection holds more than --merge-trigger-segments (default 8) segments, the smallest --merge-fan-in (default 4) by document count are folded into one.

The write-ahead log is a sequence of checksummed frames — a record header, payload length, CRC32, then the JSON-encoded upsert or delete. On startup, the log is replayed to reconstruct anything not yet flushed to a segment; if it ends mid-record (a crash mid-write), replay stops at the first incomplete or checksum-failing frame and truncates there rather than refusing to start. How often the WAL is fsynced is the --sync-interval-ms flag — see Persistence.

Each collection guards its mutable state — the memtable, the segment list, and the WAL — behind a single read-write lock. Segments themselves are immutable and shared via reference counting, so a reader that has taken its snapshot of the segment list keeps querying it consistently even while a flush or merge swaps in new segments underneath for the next reader. Writes take the lock only briefly, to append to the memtable and WAL.

The two levers that bound memory usage are --max-memtable-docs (how much unflushed data can accumulate in memory) and --merge-fan-in (a merge holds everything it's folding together in memory at once while it runs). Committed segment data itself is memory-mapped rather than loaded wholesale, so steady-state memory tracks the working set a workload actually touches.

Tachyon runs as a single node today, by design — no clustering layer to operate. Distributed search, replication, and sharding are the next major milestones for teams that outgrow one node; synonyms, stemming, stop words, result highlighting, geo search, and nested documents extend the query surface after that. Full detail on the Roadmap.