Search & Discovery in the Portal

A portal that hosts a thousand services, ten thousand docs pages, and hundreds of APIs is only as useful as its search box. When developers cannot find the runbook, the owning team, or the API they need to call, they fall back to asking in chat — and the portal’s promise of self-service quietly breaks. Search and discovery is the connective tissue that turns a large catalog from a filing cabinet into something you can actually navigate. This section covers how portal search works, how to wire a real search backend, and how to tune relevance so the right result lands first. It sits within Plugin Ecosystem & Custom Extensions, because search in Backstage is itself a plugin surface you compose and extend.

Portal search architecture Collators gather documents from the catalog, TechDocs, and APIs into an index; a query pipeline retrieves, ranks, and renders results. catalog TechDocs API docs collators search index ranked results
Search unifies three very different content sources — structured catalog entities, TechDocs pages, and API definitions — behind one query.

How Portal Search Is Structured

Backstage search is not a single monolith; it is three cooperating parts. Collators walk each content source and emit documents — a catalog collator turns every entity into a searchable record, a TechDocs collator indexes every published docs page, and you can add collators for anything else. A search engine stores those documents and answers queries; the default in-memory Lunr engine is fine for a demo and hopeless at scale. A query pipeline on the frontend takes what the user typed, calls the engine, and renders typed results with the right icon and link.

Understanding this split is what makes the rest tractable: to add a new content type you write a collator, to scale you swap the engine, and to change what ranks first you tune the query. Each concern lives in its own place.

The three parts of portal search Collators emit documents, the engine stores and queries them, and the query pipeline renders typed results. collators emit documents search engine store + query query pipeline render results
Add a content type by writing a collator, scale by swapping the engine, change ordering by tuning the query — three concerns, three seams.

Choosing a Search Engine

The in-memory engine rebuilds its index in the backend’s memory on every restart and searches it linearly. That is acceptable for a few hundred documents and falls over well before you reach real catalog size — indexing pauses startup, memory balloons, and every replica holds its own copy. A dedicated search backend such as Elasticsearch or OpenSearch moves the index out of process, shares it across replicas, and brings real relevance scoring, so a portal that has outgrown a couple of thousand documents should move to one.

In-memory versus dedicated search engine The in-memory engine holds a per-replica index and suits small catalogs; a dedicated engine shares one index and scales. In-memory (Lunr) per-replica index rebuilds on restart good ≤ ~2k docs Dedicated (Elasticsearch) shared external index survives restarts scales to millions
The move to a dedicated engine is less about raw size than about sharing one index across replicas and getting real relevance scoring.

Making Results Relevant

A working index is not the same as a useful one. If a stale, archived service outranks the actively-owned one, or a doc page beats the entity it documents, developers learn to distrust search. Relevance tuning is where you encode judgement: boost by entity type so services and APIs rank above scattered doc fragments, decay by freshness so abandoned content sinks, and weight title matches above body matches so an exact-name query lands on the exact thing. These are covered end-to-end in the ranking how-to below.

Relevance signals Type boost, freshness decay, and title weighting combine into a final relevance score for each result. type boost freshness decay title weight relevance score right result first
Relevance is a blend of signals, not a single score — tuning the weights is how you make the box feel like it reads your mind.

Frequently Asked Questions

Do I need Elasticsearch just to have search?

No — the built-in engine gives you a working search box on day one with zero infrastructure. You need a dedicated engine when the catalog grows past a couple of thousand documents, when you run multiple backend replicas that should share one index, or when relevance quality starts to matter more than convenience. Start simple and migrate when the pain is real.

Why does my search miss pages that clearly exist?

Almost always a collator problem: the content source is not being indexed, or the index is stale because the collation schedule has not run since the content changed. Confirm the relevant collator is registered and check when it last completed — an index only knows about what a collator has told it.