Unlocking Advanced Search in MediaWiki: A Guide to CirrusSearch

What is CirrusSearch?

CirrusSearch is the MediaWiki extension that replaces the built-in search engine with an Elasticsearch backend. Every Wikimedia project — Wikipedia, Wiktionary, Commons — runs on it, and the same engine is available to self-hosted wikis. It brings three practical improvements over the default search:

• Multilingual text analysis. Stemming, diacritic folding and language-specific tokenization are handled by Elasticsearch analyzers, so searches behave much more naturally in languages other than English.
• Near-real-time indexing. Full-text results usually reflect edits within a few minutes; up to 30 minutes is still considered normal operation.
• Template expansion. Content transcluded from templates is indexed as if it were written on the page itself, which the default search does not do.

CirrusSearch is actively maintained and, since MediaWiki 1.44, is also compatible with OpenSearch 1.3 as an alternative backend. The Wikimedia Search Platform has documented a gradual migration of its own infrastructure to OpenSearch, so the extension is not tied to Elasticsearch's licensing or hosting model.

Prerequisites

Before installing the extension, check the dependency chain, because it is the most common source of setup failures:

• Elasticsearch. MediaWiki 1.39 and later require Elasticsearch 7.10.2 (a compatibility layer allows 6.8.23+ on older installations). MediaWiki 1.44+ also supports OpenSearch 1.3. Elasticsearch needs a Java runtime; the official Docker image is the fastest way to get a single-node instance up.
• PHP cURL support. CirrusSearch talks to Elasticsearch over HTTP and PHP must be compiled with the cURL extension.
• The Elastica extension. Elastica is a PHP library used for the Elasticsearch client; it is a required dependency of CirrusSearch and must be installed and loaded first.

Installation

Install both extensions into your extensions/ directory. When installing from Git, run Composer inside each extension directory so the PHP dependencies are resolved:

cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Elastica
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/CirrusSearch
cd Elastica && composer install --no-dev
cd ../CirrusSearch && composer install --no-dev

Then load both extensions at the bottom of LocalSettings.php — Elastica must come first:

wfLoadExtension( 'Elastica' );
wfLoadExtension( 'CirrusSearch' );

Point CirrusSearch at your Elasticsearch instance:

$wgCirrusSearchServers = [
    'http://localhost:9200'
];

For a managed service such as Amazon OpenSearch, which only exposes port 443 over HTTPS, you will typically need a TLS-terminating proxy (for example nginx) in front of the cluster.

Finally, create the index. The maintenance scripts live inside the extension directory, not in the MediaWiki core maintenance/ folder:

php extensions/CirrusSearch/maintenance/UpdateSearchIndexConfig.php --startOver
php extensions/CirrusSearch/maintenance/ForceSearchIndex.php

After that, search should work. A quick sanity check is to search for a page you just edited and confirm it appears in the results within a few minutes.

How the query language works

CirrusSearch accepts ordinary keyword queries with Google-like operators. All keywords are lower-case and case-sensitive; quoted phrases disable stemming and match the exact phrase. The wildcards * (any number of characters) and escaped \? (a single character) work inside words, and a tilde suffix enables fuzzy matching — wikimdia~1 tolerates one changed character, while "exact phrase"~2 allows two extra words between the terms.

Useful filters

• intitle:Foo — matches pages with "Foo" in the title.
• incategory:Science — restricts results to pages in the Science category; deepcat:Science also includes subcategories.
• hastemplate:Infobox — finds pages that transclude a given template, which is handy for spotting pages still using an old infobox.
• inlanguage:de — filters by page language.
• insource:/regex/ — matches against the wikitext source instead of the rendered content (regex searches require the optional search-extra plugin and an extra indexing pass; see below).
• filetype:png filesize:>20 — file searches; file sizes are expressed in kilobytes.

Date filters

Pages can be filtered by creation or last-edit date using creationdate: and lasteditdate:. Ranges are built by combining two filters:

creationdate:2025                    pages created anywhere in 2025
creationdate:now-1h                  pages created in the last hour
creationdate:>=2024 creationdate:<2025   pages created during 2024
lasteditdate:>today-1y               pages edited within the last year

Namespaces and prefixes

Use prefix: to restrict a search to pages whose names start with a given prefix — for example prefix:User limits results to the User namespace:

prefix:User "API" incategory:Developer

Finding similar pages

The morelike: operator returns pages that share significant terms with the given pages, which is useful for research or for discovering orphaned articles:

morelike:Marie_Curie|radium

The same operator is available through the search API (action=query&list=search&srsearch=morelike:...), so it can be scripted.

Relevance, boosting and sorting

By default, results are ranked by relevance. Two keywords adjust ranking without filtering results: prefer-recent: decays the score of older pages (for example prefer-recent:1y), and boost-templates:"Template:Important|200%" multiplies the score of pages transcluding specific templates.

For a deterministic order, append &sort= to the search results URL — valid orders include last_edit_desc, incoming_links_desc, create_timestamp_asc, random and title_natural_asc (API callers use the srsort parameter). Note that an explicit sort order disables scoring-based keywords such as prefer-recent and boost-templates.

Operations and troubleshooting

• Index freshness. The full-text index updates in near real time. Template changes propagate through the job queue and can take up to a few hours on large wikis; a null edit to a page forces the change through immediately.
• Job queue. On production wikis the documentation recommends running the job queue with Redis, because the large CirrusSearch index jobs can exceed the database-backed queue's message size limits.
• Large imports. After bulk-loading thousands of pages, run UpdateSearchIndexConfig.php --startOver followed by a full ForceSearchIndex.php instead of waiting for the job queue.
• Database name restrictions. If your MySQL database name contains capital letters, indexing fails silently; set $wgCirrusSearchIndexBaseName to a lower-case index base name.
• Debugging queries. Append cirrusDumpQuery to a search URL to see the Elasticsearch query CirrusSearch generated, and cirrusDumpResult to dump the raw document scores (cirrusExplain=pretty adds a human-readable scoring explanation). The extension also exposes cirrus-config-dump, cirrus-settings-dump and cirrus-mapping-dump API modules.

Enabling regex searches

Regular expression queries via insource:/.../ are an opt-in feature. Install the org.wikimedia.search:extra plugin into Elasticsearch, enable it in LocalSettings.php with $wgCirrusSearchWikimediaExtraPlugin[ 'regex' ], then recreate the index with UpdateSearchIndexConfig.php --startOver. Regex queries are comparatively slow, so the docs recommend combining them with a normal keyword filter to limit the candidate set.

Bringing it together

Suppose you run a support knowledge base and want all troubleshooting pages for a specific error code that mention "Windows" and were updated in the last quarter:

"Error 0x80070057" incategory:Windows lasteditdate:>now-3M intitle:"error code"

Results are ranked by relevance, and adding &sort=last_edit_desc reorders them newest-first. CirrusSearch turns the default search box into a tool that users can actually build precise queries in, and most of the setup effort goes into getting the requirements right — after that, indexing and querying are largely maintenance-free. The official Help:CirrusSearch page is the best reference for the full operator syntax.