From mediawiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
OOjs UI icon advanced-invert.svg
Release status: stable
Implementation API , Parser function
Description Faceted search for MediaWiki
Author(s) Xxmarijnwtalk (Wikibase Solutions) and others
Latest version 3.6.0 (2021-10-20)
MediaWiki 1.31+
PHP 7.0+
Database changes Yes
Tables search_facets
License GNU General Public License 2.0 or later
  • $wgWSSearchElasticStoreIndex
  • $wgWSSearchDefaultResultLimit
  • $wgWSSearchHighlightFragmentSize
  • $wgWSSearchHighlightNumberOfFragments
  • $wgWSSearchElasticSearchHosts
  • $wgWSSearchAPIRequiredRights
  • $wgWSSearchSearchFieldOverride
  • $wgWSSearchMaxChainedQuerySize
  • $wgWSSearchEnableDebugMode
  • wssearch-execute-api

Check usage and version matrix.

The WSSearch extension implements a faceted search API for Semantic MediaWiki using ElasticSearch.


  • See /api on how to use the WSSearch API.
  • See /usage on how to use the #WSSearchConfig parser function.
  • See /advanced on how to extend WSSearch and how to use more advanced features such as property chains.
  • When using WSSearchFront, one does not need to know the details of the API. To set up a search engine, use the parser functions #WSSearchConfig and #WSSearchFrontend on a page. WSSearchFront is the de facto standard frontend extension for WSSearch.

The #WSSearchConfig parser function is used to set several configuration variables that cannot be passed to the API for security reasons. It sets the search conditions for that page and the list of facet properties. The base query parameter can be used to limit the set of pages that are included in the search.

  |base query=<optional: SMW query>
  |<facet property>

The facet property values should correspond to existing Semantic MediaWiki properties on your wiki. For instance,

  |base query=[[Class::Documentation]]
Only one call to #WSSearchConfig is allowed per page. Multiple calls will result in unexpected behavior.


This extension provides the following optional configuration variables:

Flag Default Description
$wgWSSearchElasticStoreIndex "smw-data-" . strtolower( wfWikiID() )) Sets the name of the ElasticStore index to use.
$wgWSSearchDefaultResultLimit 10 Sets the number of results to return when no explicit limit is given.
$wgWSSearchHighlightFragmentSize 250 Sets the maximum number of characters in the highlight fragment.
$wgWSSearchHighlightNumberOfFragments 1 Sets the maximum number of highlight fragments to return per result.
$wgWSSearchElasticSearchHosts ["localhost:9200"] Sets the list of ElasticSearch hosts to use.
$wgWSSearchAPIRequiredRights ["read", "wssearch-execute-api"] Sets the list of rights required to query the WSSearch API.
$wgWSSearchSearchFieldOverride Sets the search page to redirect to when using Special:Search. The user is redirected to the specified wiki article with the query parameter search_query specified through the search page if it is available. Does not change the behaviour of the search snippets shown when using the inline search field.
$wgWSSearchMaxChainedQuerySize 1000 Sets the maximum number of results to retrieve for a chained property query. Setting this to an extreme value may cause ElasticSearch to run out of memory when performing a large chained query.
$wgWSSearchEnableDebugMode false Enables debug mode.


It is recommended to use this extension in combination with WSSearchFront and (optionally) WSSemanticParsedText.
This extension requires the Semantic MediaWiki extension with the ElasticSearch back-end.
  • Download and place the file(s) in a directory called WSSearch in your extensions/ folder.
  • Only when installing from git run Composer to install PHP dependencies, by issuing composer install --no-dev in the extension directory. (See task T173141 for potential complications.)
  • Add the following code at the bottom of your LocalSettings.php:
    wfLoadExtension( 'WSSearch' );
  • Run the update script which will automatically create the necessary database tables that this extension needs.
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

See also[edit]