Architecture #

Pizza is a distributed search engine built on a shared-nothing design: every node owns its shards, memory, and disks — and within a node, every CPU core runs its own runtime instance, sharing nothing with the other cores. All disk and network I/O is asynchronous, running on a thread-per-core runtime ( monoio); on Linux, io_uring offloads the WAL’s durable-write fsyncs whenever the kernel supports it.

From request to storage #

Gateway #

Every request enters through the gateway’s HTTP surface — _search, _doc, _bulk — modeled on the Elasticsearch REST API, so existing clients and tooling work unchanged. Bodies are accepted in Pizza’s canonical DSL and common Elasticsearch forms alike; the normalization is idempotent and happens before parsing (see API conventions).

Distributed query engine #

The coordinator plans the request and fans out one subquery per shard group of the target collections, skipping copies on nodes whose search lanes are saturated. Each node admits searches into two lanes — FAST for regular queries, HEAVY for aggregations and deep pagination — so big requests cannot starve small ones. Ranked hits and aggregations merge back on the coordinator, which returns partial results on timeout rather than hanging. The full pipeline is on How query works.

Data nodes #

Data nodes hold the shard copies. Each node runs one worker per CPU core on the thread-per-core runtime: a core’s worker owns its coroutines, memory, and I/O, and cores exchange work by message passing instead of locks. With nothing shared on the hot path, a node’s throughput scales with its core count, allocations stay NUMA- and cache-local, and a slow operation on one core never blocks the others.

Storage #

Each data node serves its shards from local storage, in the four parts the diagram shows under every runtime instance:

WAL — a write is acknowledged only after it is appended to the shard’s write-ahead log: a local file-based WAL by default, with a Kafka-backed WAL available.
Store — the forward documents, persisted in Pizza’s native FIRE columnar format.
Index — inverted indexes (term dictionaries, Roaring-bitmap postings) built into immutable FIRE segments that are memory-mapped and never copied, alongside the in-memory mutable layer that keeps fresh writes searchable.
Meta — cluster state: the catalog and shard assignments, held in an embedded KV store and kept in agreement across the cluster by Raft consensus. Replication and inter-node subqueries ride a zero-copy capnp RPC transport.

How writes flow through the WAL into searchable segments — and how recovery replays them back — is on How realtime works.

Why shared-nothing and asynchronous I/O #

As core counts grow, the first bottleneck in a shared-everything design is not compute but contention: locks, cache-coherency traffic, and remote-memory hops that get more expensive with every core you add. Pizza removes the contention instead of tuning it. Because cores share no mutable state, the hot path — posting-list merges, scoring, column scans — parallelizes with no coordination, and memory stays on the NUMA node and in the cache of the core that last touched it.

Isolation follows from the same property, at every scale: a saturated node is skipped during dispatch, a failed subquery degrades one request to partial results, a slow core holds up no other core, and an in-flight durable fsync never blocks the reactor serving the rest of the requests.