Wikibase Faceted Search

Usage documentation

foo haswbfacet:P1=Q123 haswbfacet:P2=a|b|c haswbfacet:P3

Installation

Requirements

• PHP 8.1 or later
• MediaWiki 1.43 or later
• CirrusSearch
• Wikibase Repository
• Elasticsearch

Load and enable

Load the extension using Composer:

COMPOSER=composer.local.json composer require --no-update professional-wiki/wikibase-faceted-search:~1.0

Enable the extension by adding the following to your LocalSettings.php:

wfLoadExtension( 'WikibaseFacetedSearch' );

Update MediaWiki database

Run the MediaWiki update.php script:

php maintenance/run.php update

You can verify the installation by checking your wiki's Special:Version page.

Configure

Because Wikibase Faceted Search only indexes Statements for Properties that are configured to have Facets, you need to finish your initial configuration before building the search index.

If you do not yet have Wikibase Properties, then you first have to create them. You can defer this step to a later time, though you will not get any facets until you have created the properties and specified them in the configuration.

View the configuration documentation.

Build Search Index

Run the following maintenance scripts to build the search index:

php extensions/CirrusSearch/maintenance/UpdateSearchIndexConfig.php
php extensions/CirrusSearch/maintenance/ForceSearchIndex.php --skipParse
php extensions/CirrusSearch/maintenance/ForceSearchIndex.php --skipLinks --indexOnSkip

You will need to re-run these whenever you add new properties to the configuration.

Configuration

If you install Wikibase Faceted Search without further configuration, your wiki will continue to work as before, but without the faceted search functionality.

How To Configure

Configuration is typically done via the in-wiki configuration page at MediaWiki:WikibaseFacetedSearch. A link to this page can be found in the Wikibase section on the Special:SpecialPages page. The configuration page takes a JSON string that defines the facets that should be shown in the sidebar. The page lists documentation for the configuration options.

You can also change configuration via LocalSettings.php via the wgWikibaseFacetedSearchConfig variable. It takes the same JSON string as the configuration page. Configuration on the configuration page will override the configuration in wgWikibaseFacetedSearchConfig. You can disable the configuration page by setting wgWikibaseFacetedSearchEnableInWikiConfig to false.

Many configuration changes require rebuilding the search index. Not rebuilding the search index after changing the configuration can lead to incorrect search results and incorrect information shown in the facets. It will not break your wiki, and previously configured facets will be unaffected. Thus, it is not absolutely critical to rebuild the search index immediately.

Key Configuration Capabilities

Item Types and Facets

Define what properties should have facets per item type. Example: Publications (P31=Q42) should have facets for Author (P1) and Year of Publication (P2)

Facet and Display Options

Define facet type and display options. For instance, you might wish to use a range facet for numeric properties.

Define UI labels for item types, optionally internationalized. Example: Q42 should be shown as "Publications" in the UI (even if the Wikibase label is "Publication")

Index Wikitext Via Sitelinks

Optionally, specify the Site ID of a Sitelink that points to wikitext pages in your wiki. This will make the wikitext page show up in the results instead of the Wikibase item. It also allows you to combine structured search via the facets with full-text search of whatever is shown on the wikitext page.

This is great for cases where you have "display pages" that show the information from a Wikibase item in a more readable format. For instance, a Author:Q1337 page that shows data from Item:Q1337.