Meilisearch for Shopware 6

System Requirements

To fully utilize the extension, the following minimum system requirements must be met:

• Shopware v6.5.4.0 or higher
• PHP v8.1 or higher
• Meilisearch v1.5 or higher

Additionally, we recommend the following services:

• Redis
• RabbitMQ or another queuing system supported by Shopware

Initial Installation

The extension itself can be purchased as usual from the Shopware Community Store.

However, an additional third-party software is required - namely Meilisearch. Meilisearch is an open-source search engine written in Rust, making it inherently fast and performant. A Meilisearch instance can be created in two different ways:

Self-Hosted

There is the option to provide Meilisearch either by yourself or through a hosting partner of your choice. A detailed description can be found HERE.

Meilisearch Cloud

If self-hosting a Meilisearch instance is not an option, you can use Meilisearch Cloud. This has the advantage that you don’t have to worry about updates and the associated export/import work.

Please note, however, that with this option, additional costs will be incurred that are NOT part of the paid extension price.

Initial Settings - Extension Configuration

To begin using the extension, the following basic settings must be configured under

  Settings => My Extensions => Meilisearch for Shopware6

Please note that the settings cannot be configured per sales channel at this time. Please stay in the “All Sales Channels” section to make configurations.

General Configuration

Enable Meilisearch Search

With this setting, the Meilisearch search can be globally enabled or disabled. If this setting is disabled, the Shopware default search using Elasticsearch (Opensearch) will be used.

Meilisearch Index Prefix

This prefix is used for better identification in the pool of Meilisearch indexes. As a Meilisearch instance could be used simultaneously with multiple projects, this helps with better identification.

Meilisearch Host Address without Slash at the End

The URL of the Meilisearch instance should be entered here to establish communication between Shopware and Meilisearch. CAUTION: Without a slash at the end.

Meilisearch API Key

As described in the official documentation, a Meilisearch instance in production mode should always be equipped with an API key to prevent data retrieval by third parties. This API key (Master key) should be entered in this field.

Batch Size

This setting indicates how many entities are sent to Meilisearch at once during the indexing process. The size to be used depends on the hardware on which the Meilisearch instance is running. Since Meilisearch works heavily on RAM, we recommend not exceeding the value of 500-1000. This is because higher values not only increase the load on the Meilisearch instance but also on Shopware itself, as data (depending on size) is fetched and processed from the database before being transmitted to Meilisearch. The process runs asynchronously, but the load on the server itself remains.

Entities

Each shop has its individual custom fields. In the extension, efforts are made to find products with the most custom fields and use them as the default template for indexing. Here, you can take control and set the entities that should be used as templates for indexing.

This does not mean that the same data will be used for all entities in the index. Instead, the selected entity provides the basic data structure for all subsequent entities during indexing.

For example, a product has the following custom fields:

  - topSaleBadge
  - subTitle
  - additionalContent

If a product does not have all three custom fields set, it may be that they are missing in the index. To ensure that all fields are indexed for all products, the product that has set all 3 custom fields should be set as the template.

The following entities can be set:

• Product used as a data structure template
• Category used as a data structure template
• Manufacturer used as a data structure template

Scheduled Task - Clearing Database Tasks

Shops that make many changes to products, categories, and manufacturers daily also create changes in the Meilisearch index. This can lead to the TASK DB at Meilisearch reaching a limit and being unable to perform new changes.

As the TASK DB can be quite helpful for logging, you can set the default settings for the integrated Scheduled Task here.

Meilisearch stores task logs for the following 3 possible statuses:

• Successful
• Aborted
• Failed

By default, no Tasks are removed from the Task DB by the Scheduled Task.

To give the user the ability to control this, there are also configuration options here.

Status

Selection of the three different possible statuses is possible here.

Delete Tasks X Days Before Day X

Here, the time window can be set for which tasks should be deleted from the Task DB. By default, 30 days are set. This means that all tasks in the Task DB older than 30 days will be removed.

Administration Section

Once all the basic settings from the Initial Settings section have been configured, Meilisearch can be further configured under Settings => Extensions => Meilisearch Configuration. The initial screen looks like this:

Before proceeding with additional configurations, the initial indexing must be started. In this screenshot, the current connection status between Meilisearch and Shopware is also displayed. If the API data is incorrect, a notification will be shown, as follows:

Here, with a click on the button Meilisearch offline, check API data, you can directly navigate to the basic settings of the extensions to make adjustments:

Once the issue with potentially incorrect API data is resolved, the Initial Indexing can be re-enabled, and indexing can be started.

Subsequently, the dropdown is activated, and you will find a separate index for each of your entities and each language of the entities:

Clicking on an index name reveals the view with possible detailed views:

Overview

In the menu item ‘Overview,’ global data on individual indices and their current order status are displayed. Since the sales channel serves as the basis here, there are separate index details for each entity and each language of the entity.

Preview

To provide certainty about which search results are achieved in which sales channels, languages, and entities, a search can be conducted in the ‘Preview’ menu. The language dropdown allows testing the search preview for different languages. Additionally, an entity (e.g., product) must be selected to use the search preview.

Settings

The Settings section is the centerpiece of the extension. Here, search results can be customized down to the smallest detail.

To access the settings, an entity must be selected where the setting will ultimately be applied.

Ranking Rules Settings

With the Ranking Rules, it is possible to influence Meilisearch’s internal ranking. Meilisearch works from top to bottom, meaning that the search primarily looks for the used search term (words) with the highest match rate.

From the resulting set, typos are considered.

A list of individual ranking rules can be found in the official documentation.

Additionally, there is the option to include custom data in the ranking rules. By clicking on Add Rules, a new window opens where fields from the entity (here Product) can be added:

After adding a new field, it can be placed in the ranking rules hierarchy. For newly added ranking rules, sorting can be done in ascending or descending order, or the new ranking rule can be removed.

The individual ranking rules can be rearranged via drag-and-drop. After adjusting the ranking rules, it is necessary to transmit the settings to the Meilisearch instance by clicking on the Update Ranking Rules button; otherwise, the settings will not be applied.

Typo Tolerance Settings

One of Meilisearch’s strengths is Typo Tolerance. This means that search results can be correct even if there are typos in the search term. For example, searching for Fernsher can still find Fernseher.

This behavior can be influenced here by defining at which word length 1 typo and at which word length 2 typos should be accepted.

After adjusting the values, the change must be transmitted to the Meilisearch instance by clicking on Update Typo Tolerance Settings.

Index Settings

On the search page, a maximum number of results is usually provided. Here, you can set a maximum value for the delivered results available on the search page.

After adjusting the values, the change must be transmitted to the Meilisearch instance by clicking on Update Index Settings.

Enable Cascading Search

This setting, when active, allows converting a multi-word search term into individual search queries.

For example, if a user searches for Smart TV, the process is as follows:

  Step 1 => Search for Smart TV

  If no result is available, the word Smart is removed; otherwise, the result is delivered.

  Step 2 => Search for TV

  If no result is available, no results are returned.

Danger Zone

In this area, only final tasks can be performed. Currently, there are two functions:

1. Create/Update Indices

   This causes all entries that are new in Shopware for the selected entity to be transmitted to the Meilisearch index.

2. Delete Index

   Clicking on Delete Index deletes the index in the Meilisearch instance, and the reference to this index is deleted in Shopware.

Synonyms

In some cases, a word for a webshop operator may mean the same for several other words or vice versa. For this reason, it is also possible in Meilisearch to define synonyms to ensure this.

Adding New Synonyms

To be able to add new synonyms, the language and entity must be chosen beforehand. Only languages assigned to the sales channel are available. After selecting the language and entity, a synonym can be defined by clicking on ‘Add Synonyms’:

In the left text field, write your search term, which can mean one or more other words. In the right text field, write the word or words that can mean the word on the left.

The result looks like this:

There is also the option to copy

synonyms from another index. This is useful, for example, if two languages with the same or similar base, such as en-US and en-GB, should have the same synonyms.

Copying is started by clicking on Copy Synonyms from Index.

Of course, synonyms can also be edited or deleted as usual with a click on the three dots symbol of the respective row.

After adjusting the values, the change must be transmitted to the Meilisearch instance by clicking on Update Synonyms in Index.

Storefront Section

The user interface in the storefront has been visually adjusted only slightly and follows the Shopware standard.

Search Suggestions

Upon entering a search term in the search field, the search preview opens according to the Shopware standard. This search preview is extended with manufacturer and category results.

Search Overview Page

The search overview page remains visually unchanged by default. However, adjustments to the filters are made by the extension. A category filter is added to allow filtering results to a specific category.

As perhaps evident from the screenshot, the individual filter options are accompanied by the resulting number of items for each specific option. The result count also updates when a filter is applied:

Custom Manufacturer Overview Page

Another feature of the extension is an individual manufacturer overview page linked in the search preview. It is an SEO URL, which is also found in the SEO data structure of Shopware according to the Shopware standard.

The structure of the URL is

  /search/MANUFACTURER_NAME

MANUFACTURER_NAME is replaced by the respective stored manufacturer name in a web-safe manner.

When clicking on one of the found manufacturers, you are redirected to a page that displays a product listing of the manufacturer, including filter options and a meaningful heading: