From Index to Answer: The Full Pipeline
Understanding the individual components — trigrams, regex acceleration, structural search — is useful. Understanding how they compose into a working system is what separates someone who has read about code search from someone who can build or operate one.
A production code search system like Sourcegraph or Zoekt has four major components:
1. Repository Syncing
The system continuously mirrors repositories from your version control platform (GitHub, GitLab, Bitbucket, Gerrit). This is not a one-time clone — it's a persistent sync process. When a developer pushes a commit, a webhook fires, and the sync service pulls the new commits within seconds.
2. Index Building
After syncing, the indexer processes each repository and produces a shard — a binary file containing the trigram index for that repository's current HEAD. Zoekt stores shards on disk and loads the hot ones into memory. Index building is CPU-intensive but happens asynchronously, so it doesn't block queries.
3. Query Serving
When a developer submits a search query, the query server:
1. Parses the query (literal string, regex, or structural pattern)
2. Extracts required trigrams
3. Fans out the trigram lookup across all shards (potentially on multiple machines)
4. Collects candidate files from each shard
5. Runs the full match (regex or structural) against candidates
6. Ranks and returns results
Steps 3 and 4 are parallelized across shards, which is how the system achieves sub-second latency even across millions of files.
4. Index Updates (Delta Indexing)
When a repository changes, the system does not re-index the entire repository. It identifies which files changed in the new commits and re-indexes only those files, updating the affected shard. This keeps index freshness high (typically under 30 seconds from push to searchable) without the cost of full re-indexing.
Sharding and Scaling
A single Zoekt instance can handle tens of thousands of repositories on a machine with sufficient RAM. When the corpus grows beyond a single machine, the index is sharded — split across multiple machines, each responsible for a subset of repositories. The query server fans out requests to all shards in parallel and merges results. This is the same architecture used by Google's internal Code Search, which indexes billions of lines of code across a distributed fleet.
The practical implication for platform engineers: code search infrastructure scales horizontally. Adding repositories means adding shard capacity, not redesigning the system. The query latency stays roughly constant as long as the fan-out parallelism keeps pace with shard count.
Key Point: The separation between the indexing pipeline (async, write-heavy) and the query serving layer (sync, read-heavy) is the architectural decision that makes code search both fresh and fast. Conflating these two concerns — for example, re-indexing synchronously on every query — is the design mistake that makes naive implementations unusable at scale.