Frequently Asked Questions
Why not just run Elasticsearch?
You can. Backstage has an Elasticsearch engine module and it works. Three differences are worth weighing.
- What you operate. Elasticsearch is a JVM cluster with its own capacity planning and upgrade path. SWIRL for Backstage is one container and one volume, with the index embedded in the process.
- What it searches. Both engines search what Backstage collated. SWIRL also queries connected sources live and returns those results in the same list. An existing Elasticsearch index can be one of those sources.
- Version support. Backstage's Elasticsearch module officially supports Elasticsearch 7.
If you already run Elasticsearch for the catalog and are happy with it, there is no urgent reason to change the indexed lane. The reason to look at SWIRL is usually the federated lane, or relevance complaints.
Does this replace my collators?
No. The catalog collator, the TechDocs collator, and any other collator you run keep running unchanged, on their existing schedules and with their existing configuration. The engine module takes the documents they produce and writes them to SWIRL instead of to the previous engine.
One collator is added: a collator for the swirl-federated type that yields zero documents. Its only job is to register the type, so federated results survive permission filtering and appear as a filter in the search page. It indexes nothing.
Can I keep Postgres search?
Not at the same time. Backstage's search plugin has one engine slot, so the Postgres engine module and the SWIRL engine module cannot both be registered. Remove @backstage/plugin-search-backend-module-pg when you add SWIRL.
Nothing else changes. Your Backstage database keeps its role for the catalog, TechDocs metadata, and every other plugin. Only the search index moves. To go back, remove the SWIRL module and the search.swirl block, put the Postgres module back, and let the collators run once.
What data leaves my network?
Nothing, unless you configure a federated source that is outside your network.
- The index is a directory inside the SWIRL container, on a volume you own.
- Catalog and TechDocs documents go from Backstage to SWIRL over your own network and are stored verbatim in that index.
- Queries go from Backstage to SWIRL over the same path.
- SWIRL Community sends no telemetry.
A federated source changes that by definition. If you connect a hosted GitHub or a Confluence Cloud site, the query string is sent to that vendor and their results come back. That traffic is the same traffic your engineers already generate when they search those systems in a browser. A self-hosted source keeps everything inside your network.
What is in Community versus Enterprise?
OAuth2 is the dividing line. Everything needed to search Backstage well is in Community, under Apache 2.0, for free. Enterprise adds per-user authentication to federated sources, and the features that depend on knowing who is asking.
| Capability | Community | Enterprise |
|---|---|---|
| Tantivy index, BM25 relevance, n-gram titles, typo tolerance | Yes | Yes |
| Attribute filters and Backstage permission filtering on indexed results | Yes | Yes |
| Federated GitHub and Confluence with one service account | Yes | Yes |
| Mandatory scope restriction on federated sources | Yes | Yes |
| OAuth2 sources, and sources that offer no other authentication | No | Yes |
| Per-user identity passthrough to a federated source | No | Yes |
| Semantic cache and cross-source deduplication | No | Yes |
| Use outside Backstage, and the SWIRL AI Search Assistant | Yes, Community has no such restriction | Only with a full SWIRL Enterprise license |
The Backstage SKU is licensed for use inside the Backstage portal. A request that does not carry a verified Backstage token is refused with HTTP 402. A full SWIRL Enterprise license removes that restriction and adds the Assistant, which answers questions over federated results.
Which Backstage versions are supported?
The current Backstage release, the two before it, and any release under six months old. The engine module requires the new backend system and Node 22 or 24.
What happens when SWIRL is down?
Backstage search returns an error rather than stale results. Catalog browsing, TechDocs, and every other plugin keep working. Because the index is on disk, SWIRL serves again seconds after it restarts and never reindexes to recover.
What sources are planned?
GitHub and Confluence ship in this release. Jira, GitLab, and others are planned, with no dates. SWIRL itself already connects to many more systems; the two documented here are the two tested for Backstage. See the SearchProvider Guide for the full set.