Search Overview

RCE Code exposes five retrieval modalities through one small facade. Each is a single method on CodeEngine and a single rce-code subcommand. This page explains what each one does, when to reach for it, and how to choose.

The modalities differ along two axes: exact vs. ranked, and what they need to be built first. Grep and structural lookup are exact and need no extra build step beyond the index. Lexical is ranked and works straight off the index. Semantic is ranked but needs embeddings. Hybrid fuses the ranked modalities and is the recommended “just search” path.

The five modalities at a glance

Lexical

SQLite FTS5 BM25 over chunks, with identifier sub-token expansion so getUserById matches “user” and “id”.

Grep

Live ripgrep over the working tree, aligned to the indexed corpus. Exact, no index required.

Semantic

Cosine KNN over chunk embeddings. Needs embeddings to be built first.

Hybrid

Reciprocal Rank Fusion of lexical, semantic, and symbol results. The recommended default.

Structural

Exact symbol lookup, definition-aligned spans, and a resolved call graph.

Repo Map

Aider-style relevance-ranked map via personalized PageRank, fit to a token budget.

Comparison table

Every modality maps to one Python method on the CodeEngine facade and one CLI command. Lexical, semantic, hybrid, and symbol search all return list[SearchResult] (each result carries .score, .chunk, and .source); grep returns list[GrepHit]; the repo map returns a single text string.

Modality	Best for	Python method	CLI command
Lexical	Keyword / identifier ranking off the index, no embeddings	`engine.search_lexical(query, top_k=10)`	`rce-code search "..."`
Grep	Exact literal or regex matches over the live working tree	`engine.grep(pattern, ...)`	`rce-code grep "..."`
Semantic	Conceptual / natural-language queries (needs embeddings)	`engine.search_semantic(query, top_k=10)`	`rce-code search-semantic "..."`
Hybrid	The default “just search” path; fuses the ranked modalities	`engine.search_hybrid(query, top_k=10)`	`rce-code search-hybrid "..."`
Structural (symbols)	Exact definitions, references, and the resolved call graph	`engine.find_symbol`, `engine.find_references`, `engine.get_callers`, …	`rce-code find`, `rce-code refs`, `rce-code callers`, …
Repo Map	A compact, ranked overview of the codebase for context windows	`engine.build_repo_map(...)`	`rce-code repomap`

How to choose

Start with hybrid

If you do not have a specific reason to pick a single modality, use hybrid search. It over-fetches from lexical, semantic, and symbol search and fuses them with Reciprocal Rank Fusion, so a chunk that several modalities agree on rises to the top. It is insensitive to the differing score scales of BM25 and cosine similarity, and it degrades gracefully to lexical + symbol when nothing has been embedded yet.

default_search.py

from rce.code import CodeEngine

engine = CodeEngine.open_or_create("/path/to/repo")
engine.index()   # build the index
engine.embed()   # optional: enables the semantic leg of hybrid

for hit in engine.search_hybrid("retry with backoff", top_k=5):
    print(round(hit.score, 4), hit.source, hit.chunk.file_path)
engine.close()

Reach for an exact modality when you know what you want

You know the exact text or a regex. Use grep. It shells out to ripgrep over the live working tree, so it needs no index and never goes stale.
You know a symbol name or want the call graph. Use structural lookup. It is exact: definitions, references by name, and resolved callers/callees.
You want keyword ranking but no embeddings. Use lexical search directly.
You want conceptual similarity. Use semantic search after running engine.embed().

Semantic and hybrid need embeddings for their semantic leg

Semantic search returns [] until something is embedded. Hybrid still works without embeddings — it simply fuses lexical and symbol results — but the semantic contribution only appears once you run engine.embed() (or rce-code embed). The default embedder is offline, so this requires no network.

The repo map is a different shape

Unlike the four search methods, repo map does not answer a query with a ranked list. It produces a single text overview of the most relevant definitions across the repo, ranked by personalized PageRank over the reference-to-definition graph and truncated to a token budget. It is meant for priming an LLM's context window, not for locating a specific result.