This guide breaks down the concept of nested hierarchical facets and offers practical tips for implementation with [Meilisearch](https://www.meilisearch.com/).

* * *

Table of contents
-----------------

[What is faceted search?](#what-is-faceted-search?)  
[Nested hierarchical facets](#nested-hierarchical-facets)  
[Data structuring for hierarchical faceted search](#data-structuring-for-hierarchical-faceted-search)  
[Creating a hierarchical faceted search experience with Meilisearch](#creating-a-hierarchical-faceted-search-experience-with-meilisearch)  
[Using InstantSearch and instant-meilisearch](#using-instantsearch-and-instant-meilisearch)

* * *

What is faceted search?
-----------------------

Faceted search lets users refine search results via broad categories or facets. It's an intuitive way to sift through content, enabling users to find results matching their exact requirements.

Take ecommerce websites as a case in point. Users, when searching for products, encounter both a result list and a range of facets to help refinement. These facets can typically be found on the sidebar.

Example from our [ecommerce demo](https://ecommerce.meilisearch.com/):

![](https://lh6.googleusercontent.com/vYLVdlN0R66skuGADtqg1mO_yYVuNs-kaNUKE0FRAS55tGHj5_08OEZ4-0rLMoyx9NpBm5z-AIV6ySCJThl1jjoh5GtDFFzAH1B-Lzk38N9ksnGMFD7zzMCn0zL2zb-3fiYFQPBUlAQwi9S5BKXC6n0)

Nested hierarchical facets
--------------------------

Nested facets provide a multi-level structure that helps users navigate through data by applying successive filters, often displayed in a hierarchical manner.

**Nested hierarchical facets** are particularly useful for navigating and searching large datasets or collections. Users can navigate up and down through various levels, thereby improving discoverability.

Picture an online book shopping experience. Users can:

1.  Begin with the overarching "Books" category
2.  Dive deeper by selecting a "Genre"
3.  Focus on a sub-genre
4.  And further refine by attributes like "Author", "Publication Date", or "Rating"

The foundation for such a search lies in the structuring of data.

### Data structuring for hierarchical faceted search

When implementing a hierarchical faceted search, data documents need a hierarchical categorization too—broad categories leading to finer ones.

Take a product dataset as an example:

```JSON
{
    "id": 1,
    "name": "Seagate BarraCuda 1 To (ST1000DM014)",
    "hierarchicalCategories": {
        "lvl0": "Electronics",
        "lvl1": "Electronics > Computer and Tablets",
        "lvl2": "Electronics > Computer and Tablets > Computer Parts",
        "lvl3": "Electronics > Computer and Tablets > Computer Parts > Storage"
    } 
}

```

Each product is linked to hierarchical categories, flowing from broad to specific, to establish a clear pathway through the data. This organized categorization is crucial in implementing faceted search, steering users from general categories like "Electronics" to more precise ones, such as "Storage" within "Computer Parts"

### Creating a hierarchical faceted search experience with Meilisearch

In Meilisearch, facets are a specific use-case of [filters](https://www.meilisearch.com/docs/learn/fine_tuning_results/filtering). Whether something is a filter or a facet depends above all on UX and UI design. To be able to refine results based on facets, you need to add the attributes you want to use as facets to the [filterableAttributes list](https://www.meilisearch.com/docs/reference/api/settings#filterable-attributes). From our product example, you should set  `hierarchicalCategories` as filterable.

Hierarchical facets typically use the [`AND` logical operator](https://www.meilisearch.com/docs/learn/fine_tuning_results/filtering#and), as each level of the hierarchy acts conjunctively with the others to narrow down the search progressively.  

Example:

*   Category: Electronics
    *   Subcategory: Computers
        *   Brand: Apple

The results would show items that are in the Electronics category AND the Computers subcategory AND of the Apple brand.

When creating a faceted search interface, it is helpful to display the distribution of results across the different facets. Showing users the number of results in different categories as they refine their search can enhance their search experience.

Meilisearch supports this functionality through the [`facets` search parameter](https://www.meilisearch.com/docs/reference/api/search#facets). When you add the `facets` parameter to your search query, Meilisearch returns a [facetDistribution](https://www.meilisearch.com/docs/reference/api/search?ref=blog.meilisearch.com#facetdistribution) object. This object provides the number of matching documents distributed among the values of the given facet.

```JSON
  "facetDistribution":{
    "categories":{
      "Electronics":20,
      "Electronics > Computer and Tablets":7,
      …
      "Electronics > Computer and Tablets > Computer Parts > Storage":3
    }
```

Leveraging the facets search parameter, you can present a neatly organized and intuitive search interface, allowing users to filter through hierarchical categories effectively. Meilisearch hands you the keys to build your own faceted search UI, yet for a quick and easy setup, employing InstantSearch with instant-meilisearch is a highly efficient alternative.

### Using InstantSearch and instant-meilisearch

[InstantSearch](https://github.com/algolia/instantsearch?ref=blog.meilisearch.com) is an open-source front-end library to build search UIs. [Instant-meilisearch](https://github.com/meilisearch/meilisearch-js-plugins/tree/main/packages/instant-meilisearch?ref=blog.meilisearch.com) is the go-to search client for integrating InstantSearch with Meilisearch.

In this guide, we’ll be using React code samples, you can find more examples in InstantSearch’s documentation

To use InstantSearch with instant-meilisearch, you need to:

#### 1\. Import the required modules

```JavaScript
import React from 'react';
import { InstantSearch, SearchBox, InfiniteHits, HierarchicalMenu } from 'react-instantsearch';
import { instantMeiliSearch } from '@meilisearch/instant-meilisearch';
```

####   
2\. Establish a Meilisearch client with your Meilisearch host and search API key

```JavaScript
const searchClient = instantMeiliSearch( 'https://ms-7053a8dd7c09-72.lon.meilisearch.io', 'meilisearchApiKey' )
```

#### 3\. Set up instantsearch with your Meilisearch index name and the search client  

```Javascript
function App() {
  return (
    <InstantSearch indexName="products" searchClient={searchClient}>
      {/* Widgets */}
    </InstantSearch>
  );
}

```

To have a better understanding of how InstantSearch and instant-meilisearch work together, you can refer to our [dedicated blog post](__GHOST_URL__/instant-meilisearch/).

In this guide we’ll use InstantSearch’s `HierarchicalMenu` widget to display categories in a hierarchical fashion.

This widget has a required prop called `attributes`. It takes an array of string values. Each string identifies a specific attribute from your data structure, intended to be used in generating the hierarchical menu.

```JavaScript
<HierarchicalMenu
    attributes={[
        "hierarchicalCategories.lvl0",
        "hierarchicalCategories.lvl1",
        "hierarchicalCategories.lvl2",
        "hierarchicalCategories.lvl3"
    ]}
/>
```

With this widget you can create a menu akin to the example below:

![Screenshot of a hierarchical faceted search interface under 'Categories'. 'Electronics' is the main category with 2874 items, under which 'Image & Sound' is a subcategory with 1047 items. Further nested, 'Television' is highlighted with 689 items, which breaks down into an additional level showing 'TV' with 689 items.](https://lh5.googleusercontent.com/sv4j33IY1r0fpIqWnFRZpT_ntj1ccjqPKnzQuI40BvzH2Ko26pTfsYDCbal8llJsoc2y3RuQACarskaoOJrtMJOrV0Tr6bf8yLwVFeb-s_tEudtr7UIdXpufpoR7SWMGjRHhc40fpMJ-Teb2-Gwe5dE)

* * *

This guide equips you with the fundamental understanding and steps needed to implement a hierarchical faceted search using Meilisearch and InstantSearch, enhancing user navigation through layered, intuitive categorization.

For more things Meilisearch, you can subscribe to our [newsletter](https://meilisearch.us2.list-manage.com/subscribe?u=27870f7b71c908a8b359599fb&id=79582d828e&ref=blog.meilisearch.com). You can learn more about our product by checking out the [roadmap](https://roadmap.meilisearch.com/?ref=blog.meilisearch.com) and participating in our [product discussions](https://github.com/meilisearch/product/discussions?ref=blog.meilisearch.com).

For anything else, join our developers community on [Discord](https://discord.meilisearch.com/?ref=blog.meilisearch.com).

Guide to hierarchical faceted search

Let's take a look at some of the most significant changes in Meilisearch's latest update. We’ll go over the main changes in this article, but you can also view the [full changelog](https://github.com/meilisearch/meilisearch/releases/tag/v1.4.0) on GitHub.

<Callout>
  v1.4 is now available on [Meilisearch Cloud](https://cloud.meilisearch.com/?utm_campaign=release-v1-4&utm_source=blog). Upgrade your Meilisearch instance in one click without downtime.
</Callout>

New feature: custom text separators  

--------------------------------------

To make string data searchable, Meilisearch relies on [separators](https://www.meilisearch.com/docs/learn/advanced/datatypes?utm_campaign=release-v1-4&utm_source=blog#separators), as they serve to divide a string into tokens or words. Examples of separators include whitespaces, full-stops, or number signs (#). They play a crucial role in helping Meilisearch segment text effectively and enhance search relevancy.

Meilisearch comes with a predefined list of separators. However, these separators do not suit all use cases. For example, in a hashtag search, the number sign should not be considered a separator, but part of the word.

Starting with v1.4, Meilisearch allows you to customize the separators list to suit your specific needs.

### Using an SDK or the API

<Callout>
  This section shows code samples in JavaScript. Check out our [official SDKs](https://www.meilisearch.com/docs/learn/what_is_meilisearch/sdks?utm_campaign=release-v1-4&utm_source=blog) or the [API reference](https://www.meilisearch.com/docs/reference/api/settings?utm_campaign=release-v1-4&utm_source=blog#separator-tokens) for more examples.
</Callout>

#### Adding characters to the separators list  

To include a character in the separators list, update your index’s _Separators Tokens_ settings:

```JavaScript
client.index('myIndex').updateSeparatorTokens(['&sect;'])
```

This request adds the encoded version of the section sign character (\`§\`) to the separator tokens list.

#### Removing characters from the separators list  

To remove one or more characters from the separators list, update your index’s _Non Separator Tokens_ settings:

```JavaScript
client.index('myIndex').updateNonSeparatorTokens(['@', '#', '&'])
```

### Using Meilisearch Cloud

On [Meilisearch Cloud](https://cloud.meilisearch.com/?utm_campaign=release-v1-4&utm_source=blog), you can configure _Separator Tokens_ from your index’s settings. Both fields accept JSON format. To include separators, add them to the 'separators' field. To exclude certain characters as separators, list them under 'non-separators'.

![Screenshot of Meilisearch Cloud UI showcasing the 'separator settings' section. It features two fields: one for listing separators and another for listing non-separators. ](https://unable-actionable-car.media.strapiapp.com/0dfq_LJ_Qj_G_L_Rt9_X_r_F6d6_RKYCTU_Kt_K_ib_Q9_E_Ye3_A8_Cq_V_Ea20_Mv_q3_Pgo_Yrdkbcy_WC_8_QSZN_6f_Bn_D_Wu_QN_87_H_Izf_1_Zyk_FWKKD_Lv_b64487b283.jpg)

New feature: custom dictionary
------------------------------

<Callout>
  This section shows code samples in JavaScript. Check out our [official SDKs](https://www.meilisearch.com/docs/learn/what_is_meilisearch/sdks?utm_campaign=release-v1-4&utm_source=blog) or the [API reference](https://www.meilisearch.com/docs/reference/api/settings?utm_campaign=release-v1-4&utm_source=blog#dictionary) for more examples.
</Callout>

Now, you can add a custom word dictionary to improve Meilisearch's segmentation of specific words. This is particularly useful when working with domain-specific terminology like “Node.js” or proper nouns like “E. E. Cummings”.

To add words to the dictionary, update your index’s _Dictionary_ settings:

```JavaScript
client.index('myIndex').updateDictionary(['e. e.', 'e.e.', 'e e'])
```

On [Meilisearch Cloud](https://cloud.meilisearch.com/?utm_campaign=release-v1-4&utm_source=blog), you can configure a _Custom Dictionary_ by providing a JSON array in your index’s settings. You can also upload a JSON file as dictionary.

### Using custom dictionary with stop words and synonyms

The introduction of a custom dictionary acts as a powerful adjunct to existing features like [stopWords](https://www.meilisearch.com/docs/reference/api/settings?utm_campaign=release-v1-4&utm_source=blog#stop-words) and [synonyms](https://www.meilisearch.com/docs/learn/configuration/synonyms?utm_campaign=release-v1-4&utm_source=blog). Together, they synergize to improve the relevancy of the search results.

Let’s consider a literary database where an author's name may appear in various forms or abbreviations. This leads to fragmented search results, making it challenging for users to find works by that specific author. For example, take the different ways one might search for works by E. E. Cummings. Using the custom dictionary feature along synonyms can standardize these name variations, thereby enhancing the relevancy of search results.

Using synonyms and custom dictionary together, here’s an example of index settings that address this scenario:

```JSON
{
"dictionary": ["E. E.", "E.E.", "E E"],
"synonyms": {
    "E. E.": [ "E.E.", "E E", "Edward Estlin"],
    "E.E.": ["E. E.", "E E", "Edward Estlin"],
    "E E": ["E. E.", "E.E.", "Edward Estlin"],
    "Edward Estlin": ["E. E.", "E.E.", "E E"]
}
```

Breaking bug fix: improved filtering with backslashes
-----------------------------------------------------

In v1.4, we've addressed a longstanding bug that users faced when using backslashes (\\) at the end of the \`filter\` search parameter expression.

Let’s consider the following documents:

```JSON
[
  {
    "id": 1,
    "path": "my\\test\\path"
  },
  {
    "id": 2,
    "path": "my\\test\\path\\"
  }
]

```

**Note**: The double backslashes in the example are for JSON escaping.

Before v1.4.0, trying to filter on the second document using either of the filters `path = "my\\test\\path\\"` or `path = "my\\test\\path\\\"` would lead to errors.

Now, you can use any filter expression with backslashes. Just make sure to escape each `\` character in your filter.  

Using our example, to filter on the second document successfully, the filter should be written as: `path = "my\\\\test\\\\path\\\\"`.  

⚠️ **Warning:** If you're upgrading from v1.3.X or earlier and have previously used backslashes in filters, be aware that in v1.4.0, the correct filter for the first document should be `path = "my\\\\test\\\\path"`.  

Two layers of escaping are applied: : first, escape for JSON, then for the Meilisearch filter. Meilisearch turns `\\\\` back to `\\`, and JSON parsing will result in a single `\`.  

<Callout>
  Consider using built-in methods of your programming language to handle backslashes:- PHP: [addslashes() function](https://www.php.net/manual/en/function.addslashes.php)\- JavaScript: While JS doesn't have a specific method for adding slashes. You can use the [replace method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace), as suggested on [StackOverflow](https://stackoverflow.com/questions/7744912/making-a-javascript-string-sql-friendly)
</Callout>

Contributors
------------

We are really grateful for all the community members who participated in this release. We would like to thank: [@dogukanakkaya](https://github.com/dogukanakkaya), [@JannisK89](https://github.com/JannisK89), and [@vivek-26](https://github.com/vivek-26) for their help with Meilisearch. We want to send a special shout out to [mmachatschek](https://github.com/mmachatschek/) for his help and involvement with the backlash bug.

Conclusion
----------

And that’s it for v1.4! Remember to check the [changelog](https://github.com/meilisearch/meilisearch/releases/tag/v1.4.0) for the full release notes, and see you next time!  

You can stay in the loop by subscribing to our [newsletter](https://meilisearch.us2.list-manage.com/subscribe?u=27870f7b71c908a8b359599fb&id=79582d828e). To learn more about Meilisearch's future and help shape it, take a look at our [roadmap](https://roadmap.meilisearch.com/) and come participate in our [Product Discussions](https://github.com/meilisearch/product/discussions).  

For anything else, join our developers community on [Discord](https://discord.gg/meilisearch).

What's new in v1.4?

[Symfony](https://symfony.com/) is an open-source web development framework for PHP that enables users to create web applications by utilizing sets of reusable components. Originating from France, Symfony combines a web application framework, a philosophy, and a vibrant community.

**With Meilisearch, Symfony gained better control over parsing and indexing of documentation content to speed up and improve the quality of search results.**

> _Using Meilisearch has been a delight so far. It all starts with its quick and simple installation process, followed by its great and thorough documentation, and it ends with a powerful search engine with mind-blowing performance. Meilisearch feels fun, fresh and uncomplicated._ \- Javier Eguiluz, Symfony Evangelist.

Challenge
---------

Fast and efficient information retrieval from [Symfony’s documentation](https://symfony.com/doc/current/index.html) is essential for the success of its rapidly growing community. The Symfony Documentation, including code samples, comprises well **over 12 million words**, and throughout its history, Symfony has published **30 different version updates**, making smooth information retrieval from the documentation crucial. In fact, to ensure the search function is as accessible as possible for [symfony.com](https://symfony.com/) visitors, the team integrated multiple keyboard shortcuts to open the search input across the entire website.

In the past, Symfony’s team explored various products and services, including Apache Solr, Elasticsearch, Google Custom Search Engine, and Algolia Search. However, the team realized the need for better control over the parsing and indexing of search content in order to tweak the search rules and improve website navigation and the overall search experience as a result. While using a fully hosted service is convenient, the pre-existing [configuration via JSON files](https://github.com/algolia/docsearch-configs/blob/master/configs/symfony.json) proved cumbersome and did not provide Symfony with the flexibility it required.

Secondly, there was potential to improve the overall quality of the search results, with the Symfony team receiving some complaints about inaccurate or missing results from the documentation users. Unfortunately, due to the aforementioned lack of control over the parsing and indexing processes, significant improvements to these results were unattainable and the need for a better alternative became evident.

Why Symfony chose Meilisearch
-----------------------------

Determined to find a better alternative, Symfony’s team started research on search engines. From the very beginning, the preference was for open-source projects developed in Go, because there was existing internal prior expertise in that language. Although there were many search solutions on the markets that matched those requirements, many of them lacked active development, didn’t have an active community, or missed essential features such as support for synonyms.

Finally, the team looked at Meilisearch, which provides an open-source search engine developed in Rust, along with an option to self-host, and quickly found a fit. Meilisearch’s established reputation as an open-source project with a vibrant community played a pivotal role in influencing the final decision.

Implementation
--------------

Meilisearch offers integrations with a wide range of programming languages and frameworks. In addition to hosting Symfony's index data, the Meilisearch team provided valuable assistance during the migration process so that a single developer who had no prior experience with Meilisearch was able to handle an entire migration and the implementation process, using the [Meilisearch PHP integration](https://github.com/meilisearch/meilisearch-php) with the Symfony [HttpClient component](https://symfony.com/http-client).

Here’s a brief overview of the technical integration process:

1.  **Parsing Symfony Documentation:** For Symfony’s documentation, the process included splitting the entire page contents into multiple small documents in order to produce better search results, closely related to the query terms.
2.  **Indexing Documents** was the simplest part of the process and included configuring [stopwords](https://specs.meilisearch.com/specifications/text/0123-stop-words-setting-api.html#_3-functional-specification) (list of words to be ignored in search queries) and synonyms to produce better search results.

For a full walkthrough of how Symfony implemented parsing of their documentation, documents indexing, and search engine interface, we recommend taking a look at their blog post on [migrating symfony.com search engine to Meilisearch](https://symfony.com/blog/migrating-symfony-com-search-engine-to-meilisearch).

Results
-------

The Symfony team focuses primarily on two different aspects of performance when evaluating the results:

*   **Performance of indexing contents:** Meilisearch can index approximately 800 full documents per second, which includes the processing of hundreds of stopwords and tens of synonyms.
*   **Performance of queries:** Symfony, including all versions of Symfony Docs and documentation for bundles, parses 12,754 files and generates 85,146 Meilisearch documents. The total time taken to parse, create, and index all these documents is 17 seconds. The search index consumes approximately 1.2 GB of disk space, with most queries returning results in less than 10 milliseconds.

> Nicolas Grekas, Core team member at Symfony, summarizes it as follows: _“These numbers are quite impressive and offer an excellent experience when updating search results in real-time as you type."_

To complete the evaluation process, the Symfony team conducted a comprehensive comparison between the previous search engine results and the new Meilisearch engine. They tested typical queries, rare queries, long queries, and queries with typos. Below is a [comparison of the search results](https://symfony.com/blog/migrating-symfony-com-search-engine-to-meilisearch#evaluating-the-result) obtained before (left) and after implementing Meilisearch (right):

![](https://unable-actionable-car.media.strapiapp.com/lp_X3_F9zw6h_F_Ka_8_Wrm3h_W4_X2_O8_KL_8_OA_4hfb_C9igir_cs_F_Pwp_M9_NQA_Rs_A_Rm_Nqdb1_Sjozss6q4_L_Pcg_n5_Vp_Pj_Selc_J_Ms_Wk_Cn_Zrbm_C_eb917263f4.jpg)

![](https://unable-actionable-car.media.strapiapp.com/Yyk95_A_Bhdkqzb_E2nia_BG_Rth_F_Iq_C_yu_Ek4_N_Duoya_AGIL_4ld_Xvi_Nn_TNJ_2_Ybw_R7_A2_M_Xtij4g_Xi_Hemu5t_H4_HBWAMBL_Zmv_Z6hv_Eks_Gzv_459f570ba3.jpg)

Since the new search experience was deployed, the team hasn't received any negative feedback from the community, which normally served as an indicator of the quality of the search experience.

Vision
------

Currently, Symfony's team is satisfied with Meilisearch's feature offering, which offers all the essential features needed, including indexing arbitrary information, sorting, result weighting, handling stopwords, synonyms, facets, filtering, and more.

> Javier Eguiluz, Symfony Evangelist, advises: "_Before integrating it into your projects, be aware of some_ [_known limitations_](https://docs.meilisearch.com/learn/advanced/known_limitations.html)_. If your project requirements are complex (e.g., cross-faceting between multiple indexes, etc.), make sure to check if these advanced features are already supported. Additionally, it's a good idea to review the_ [_Meilisearch public roadmap_](https://roadmap.meilisearch.com/)_._"

For a full walkthrough of how Symfony implemented parsing of their documentation, documents indexing, and search engine interface, we recommend taking a look at their blog post on [**migrating symfony.com search engine to Meilisearch**](https://symfony.com/blog/migrating-symfony-com-search-engine-to-meilisearch)**.**  
  
Ready to optimize your documentation search? [Start a free trial](https://www.meilisearch.com/cloud) with Meilisearch today.

Cracking the code: Symfony's search solution for 12 million words of documentation

**🚀 Introducing vector search**
--------------------------------

![Introducing Meilisearch's Vector search and Vector database to navigate the future of search](https://unable-actionable-car.media.strapiapp.com/introducing_vector_search_8e7f819b5e.png)

We’re excited to bring experimental support for vector search. This release introduces **semantic and hybrid search capabilities** to further enhance the search experience.

[Read the announcement](__GHOST_URL__/introducing-vector-search/).

**🤗 Hugging Face success story**
---------------------------------

![Hugging Face success story facilitating AI accessibility with Meilisearch Cloud](https://unable-actionable-car.media.strapiapp.com/huggingface_1d18e1c3b0.png)

Meilisearch powers the discovery of **300,000+ AI models, datasets, and demos** in the Hugging Face repository. Read to learn why Hugging Face chose Meilisearch Cloud to power their search.

[Read the success story](__GHOST_URL__/hugging-face-democratizes-ai/).

**📚 Introducing Documentation Crawler**
----------------------------------------

0:00

/

1×

We’re introducing the **Meilisearch Documentation Crawler** to enable to users integrate search into any docs site—paste your URL and let it do its magic. ✨ Check out the video or read the blog post below.

[Learn more about the Documentation Crawler](__GHOST_URL__/documentation-crawler-release/).

* * *

**📰 In the news**
------------------

### 🔄 [Syncing Meilisearch with your MySQL database](https://www.meilisearch.com/docs/learn/cookbooks/meilisync_mysql?utm_campaign=newsletter&utm_source=september-news-23)

Learn how to keep Meilisearch in sync with your MySQL database.

### 🔝 [How to boost your search results with filter scoring](__GHOST_URL__/filter-scoring-guide/?utm_campaign=newsletter&utm_source=september-news-23)

Assign weights to your filters and prioritize documents based on how well they match your criteria.

### 🦜🔗 [A step-by-step tutorial to building semantic search](__GHOST_URL__/langchain-semantic-search-tutorial/?utm_campaign=newsletter&utm_source=september-news-23)

Learn how to use **LangChain** with Meilisearch to build semantic search using similarity search.

### 🔍 [Refining facets by ID with InstantSearch](__GHOST_URL__/id-based-facets-guide/?utm_campaign=newsletter&utm_source=september-news-23)

Read this community article how to use Meilisearch with Pydantic.

### 🔼 [Vercel marketplace integration](https://vercel.com/integrations/meilisearch-cloud)

The Vercel marketplace now lists 1 search integration—Meilisearch.

### 🍿 [Prose linting with Vale](__GHOST_URL__/prose-linting-with-vale/?utm_campaign=newsletter&utm_source=september-news-23)

Learn the importance of a style guide in technical writing and how Vale ensures your content complies with it.

* * *

🤗 Made with Meilisearch
------------------------

Our project of the month is [notiondesk.so](https://notiondesk.so/). Notiondesk allows you to turn a Notion database into a help center for customers.

Notiondesk use Meilisearch to power search in the help centers. Take a look at the search in [this example](https://help.bazarafrique.com/fr).

[![The easiest way to build a help center with Notion](https://unable-actionable-car.media.strapiapp.com/Screenshot_2023_09_18_at_18_27_37_1f3e6deccc.png)](https://notiondesk.so/)

<Callout>
  _We’re always looking to promote new projects from the community. Post yours in the_ [_#built-with-meilisearch_](https://discord.meilisearch.com/) _Discord channel!_
</Callout>

* * *

**🏡 Life at Meili**
--------------------

Our off-sites are designed to help people bond and get to know each other better without taking away the spontaneity of the connection. We want people to have fun without feeling pressured to perform.

[![Brittany, France](https://unable-actionable-car.media.strapiapp.com/Bretagne_1_5c86b3b085.jpg)](__GHOST_URL__/organizing-a-people-first-offsite/)

Brittany, France

[Read the blog post](__GHOST_URL__/organizing-a-people-first-offsite/).

* * *

**🦸‍♀️ We’re hiring!**
-----------------------

See our open positions:

*   [Head of Finance](https://jobs.lever.co/meili/14970d91-fb2f-4130-b568-97872eb62b31)
*   [Founding Account Executive](https://jobs.lever.co/meili/92e2ebdc-3023-4fbe-8dd2-c3cfc9ecd7bf)

* * *

Get these monthly updates straight to your inbox by subscribing to our [newsletter](https://meilisearch.us2.list-manage.com/subscribe?u=27870f7b71c908a8b359599fb&id=79582d828e&ref=blog.meilisearch.com).

For more things Meilisearch, join our developers community on [Discord](https://discord.gg/meilisearch/?ref=blog.meilisearch.com). You can learn more about the product by checking out the [roadmap](https://roadmap.meilisearch.com/?ref=blog.meilisearch.com) and participating in [product discussions](https://github.com/meilisearch/product/discussions?ref=blog.meilisearch.com).

Until next time.

Meilisearch September Updates

  
In this guide, we’ll delve into the concept of faceting in [Meilisearch](https://www.meilisearch.com/) and how to use it to display facet names while filtering by IDs.

**What is faceting?**
---------------------

[Faceting](https://www.meilisearch.com/docs/learn/fine_tuning_results/faceted_search) is a technique used in search engines to classify search results into multiple categories or “facets”. These facets can be anything from categories, tags, price ranges, to even colors. This makes it easier for the user to navigate and filter through the results, providing a more refined and efficient search experience.

**Why use the ID as a facet filter?**
-------------------------------------

For most applications and users, filtering by facet names, such as the genre of movies, is often sufficient and intuitive. Facet names are human-readable and provide a clear idea of what the filter does. However, in some use cases, it is preferable to filter by ID for a couple of key reasons:

*   **Less prone to errors**: IDs are usually simpler and standardized, making them less susceptible to typos or inconsistencies that might be present in facet names.
*   **Unique identifiers**: In some databases, facet names might be repeated with slightly different characteristics, whereas IDs are always unique. This is especially useful in cases where you have items with similar or identical names but different properties.

By using IDs for filtering but displaying the corresponding facet names to the users, you can achieve the best of both worlds: efficiency and usability. This way, you are leveraging the strengths of both IDs and names, making your application robust and user-friendly.

**The ID-to-name challenge**
----------------------------

In Meilisearch, facets are a specialized use-case of filters. Essentially, you can use any attribute added to the [`filterableAttributes`](https://www.meilisearch.com/docs/reference/api/settings#filterable-attributes) list as a facet. When you add a facet parameter to your search query, Meilisearch will return a `[facetDistribution](https://www.meilisearch.com/docs/reference/api/search#facetdistribution)` object. This object provides the number of matching documents distributed among the values of the given facet.

```JSON
 "facetDistribution":{
    "genres":{
      "Classics":6,
      "Comedy":1,
      "Coming-of-Age":1,
      "Fantasy":2,
      "Fiction":8,
      …
    }
  }
```

However, if the field you’ve added to the filterableAttributes list is an ID, the `facetDistribution` object will return these IDs.

```JSON
 "facetDistribution":{
    "genres":{
      "5":6,
      "6":1,
      "8":1,
      "13":2,
      "16":8,
      …
    }
  }
```

While IDs are great for back-end operations, they are not necessarily user-friendly or meaningful on the front-end. This is why you might want to map these IDs back to their corresponding facet names when displaying them in your user interface.

**ID-to-name mapping in the frontend**
--------------------------------------

Suppose you have a dataset of movies following the structure below:

```JSON
{
    "id": 5,
    "title": "Four Rooms",
    "overview": "It's Ted the Bellhop's first night on the job....",
    "genres": [
        {
            "id": 7,
            "name": "Crime"
        },
        {
            "id": 6,
            "name": "Comedy"
        },
    ],
    "release_date": 818467200,
}
```

You want a faceted search based on the movies genres. So you add genres.id to the [filterable attributes](https://www.meilisearch.com/docs/reference/api/settings#filterable-attributes) list. Of course, in the UI you want to display genres.name, so that the user will see “Crime” on the UI instead of “7”.

Let’s dive into how you can accomplish this with InstantSearch and instant-meilisearch.

### **Using InstantSearch and instant-meilisearch**

[InstantSearch](https://github.com/algolia/instantsearch) is an open-source front-end library to build search UIs. [Instant-meilisearch](https://github.com/meilisearch/meilisearch-js-plugins/tree/main/packages/instant-meilisearch) is the go-to search client for integrating InstantSearch with Meilisearch.

To use instant-meilisearch with InstantSearch, you need to:  

**1\. Import the required modules, including instantMeiliSearch**

```JavaScript
import { instantMeiliSearch } from '@meilisearch/instant-meilisearch'
import instantsearch from 'instantsearch.js'
import { searchBox, infiniteHits,refinementList } from 'instantsearch.js/es/widgets'
```

  
**2\. Establish a Meilisearch client with your Meilisearch host and search API key**

```JavaScript
const searchClient = instantMeiliSearch(
  'https://ms-7053a8dd7c09-72.lon.meilisearch.io',
  'meilisearchApiKey'
)

```

**3\. Set up instantsearch with your Meilisearch index name and the search client**

```JavaScript
const searchIndex = instantsearch({
  indexName: 'movies',
  searchClient
})

```

In this guide, we’ll use InstantSearch’s `refinementList` widget to map IDs to user-friendly names.

This widget comes with an optional parameter called `transformItems`. This function receives the `items` (or facets) and allows you to transform them before they are displayed on the UI. It also includes the full results data in its parameters.

Each item—or facet—includes the following properties:

*   `count`: the number of occurrences of the facet in the result set
*   `value`: the value used for refining (in our case it would be genres.id)
*   `label`: the label to display
*   `highlighted`: the highlighted label. This value is displayed in the default template

As you can see `highlighted` is the label used by default in the `refinementlList` widget.

With this information, we can use the `transformItems` function to display the `genres.name` instead of `genres.id`.

```JavaScript
transformItems(items, { results }) {
    // The 'results' parameter contains the full results data
    return items.map(item => {
      // Initialize genreName with the existing highlighted label
      let genreName = item.highlighted;
      
      // Loop through results.hits to find a matching genre
      for (let hit of results.hits) {
        const matchedGenre = hit.genres.find(genre => genre.id.toString() === item.value);
        
        // Update genreName if a match is found
        if (matchedGenre) {
          genreName = matchedGenre.name;
          break;
        }
      }
      
      // Return the updated item with the new tagName as the highlighted value
      return {
        ...item,
        highlighted: genreName
      };
    });
  }
```

With this configuration, you’ll efficiently map IDs to more user-friendly names, enhancing the search experience for your users.

The full code should look like this:

```JavaScript
import { instantMeiliSearch } from '@meilisearch/instant-meilisearch'
import instantsearch from 'instantsearch.js'
import { searchBox, infiniteHits,refinementList } from 'instantsearch.js/es/widgets'

const searchClient = instantMeiliSearch(
  'https://ms-7053a8dd7c09-72.lon.meilisearch.io',
  'meilisearchApiKey'
)
  
const searchIndex = instantsearch({
  indexName: 'movies',
  searchClient
})

const searchBox = instantsearch.widgets.searchBox({
  // ...
});

const hits = instantsearch.widgets.hits({
  // ...
});

const refinementList = instantsearch.widgets.refinementList({
  container: '#facets',
  attribute: 'genres.id',
  transformItems(items, { results }) {
    return items.map(item => {
      let genreName = item.highlighted; 
      for (let hit of results.hits) {
        const matchedGenre = hit.genres.find(genre => genre.id.toString() === item.value);
        if (matchedGenre) {
          genreName = matchedGenre.name;
          break;
        }
      }
      return {
        ...item,
        highlighted: genreName
      };
    });
  }
})

searchIndex.addWidgets([searchBox, infiniteHits, refinementList]);

searchIndex.start()

```

This example shows how to implement ID-to-name mapping with [vanilla JavaScript](https://www.algolia.com/doc/api-reference/widgets/refinement-list/js/#widget-param-transformitems), but you can achieve similar results with your preferred frontend framework. Checkout the respective documentation for [React](https://www.algolia.com/doc/api-reference/widgets/refinement-list/react/#widget-param-transformitems) and [Vue](https://www.algolia.com/doc/api-reference/widgets/refinement-list/vue/#widget-param-transform-items).

For more things Meilisearch, you can subscribe to our [newsletter](https://meilisearch.us2.list-manage.com/subscribe?u=27870f7b71c908a8b359599fb&id=79582d828e). You can learn more about our product by checking out the [roadmap](https://roadmap.meilisearch.com/) and participating in our [product discussions](https://github.com/meilisearch/product/discussions).

For anything else, join our developers community on [Discord](https://discord.meilisearch.com/).

Refining facets by ID with InstantSearch

How to boost your search results with filter scoring

Headquartered in New York and Paris, Hugging Face is an open-source provider of machine learning technologies, allowing users to train, deploy, and share AI models using Hugging Face open-source libraries and the Hub.

**By partnering with Meilisearch Cloud, Hugging Face actively fulfills its visionary commitment to advancing the democratization of AI.**

![](https://unable-actionable-car.media.strapiapp.com/ezgif_com_video_to_gif_1_e697b647e1.gif)

> _“Today, Meilisearch is used by Hugging Face to power the discoverability of 300,000+ AI models, datasets, and demos. It’s really important for AI democratization because if the knowledge is out there, but you can’t access it - what’s the point?” -_ Mishig Davaadorj, software engineer at Hugging Face

Challenge
---------

On its platform, Hugging Face enables users to upload their AI models, datasets, and demos. With a vibrant community of users constantly engaging with the [Hugging Face Hub](http://hf.co) - a platform for sharing and searching for Machine Learning artifacts - the question of discoverability takes center stage.

The Hugging Face Hub hosts over 220,000 AI [models](https://huggingface.co/models) catering to a variety of [machine-learning tasks](https://huggingface.co/tasks), all neatly stored in repositories. These model repositories are designed to make the exploration and utilization of models as seamless as possible. Each AI model in the Hugging Face repository is accompanied by a model card, a project file containing valuable metadata, which plays a crucial role in enhancing discoverability, reproducibility, and sharing. Model cards also provide important information about AI models’ biases and limitations, model descriptions, and training guidelines, and serve as comprehensive guides for users seeking models on the Hub or uploading their own.

Before the introduction of Meilsearch, Hugging Face relied on a simple filtering and keyword search solution. However, it became evident that there was a growing demand for a more flexible and typo-tolerant full-text search solution. This solution needed to ensure higher default relevancy for every search query and leverage the additional attributes and metadata stored within model cards.

Why Hugging Face chose Meilisearch Cloud
----------------------------------------

Before integrating Meilisearch into its ML model repository, Hugging Face had already been utilizing Meilisearch's free-of-charge open-source solution as a search engine for its [open-source libraries](https://huggingface.co/docs)’ documentation, including transformers & diffusers. This documentation comprised approximately 500 pages and had been in use for over a year. Because the team had already gained positive experiences from implementing and operating Meilisearch, when the need for enhanced discoverability in model card searches arose, there was no requirement for additional testing or proof of concept.  

**1\. Customizability of the ranking rules**

During the evaluation process, the Hugging Face team also considered Mongo Atlas Search. However, they weren't satisfied with the customizations available for ranking. Several factors were taken into account in order to enhance model card discoverability, such as project names, descriptions, and the number of likes or downloads on each card. Meilisearch has demonstrated greater flexibility and adaptability in accommodating these search criteria.

**2\. Transitioning to Meilisearh Cloud for its ease of use**

Having achieved successful implementation of Meilisearch in its documentation, the Hugging Face team smoothly transitioned to incorporating Meilisearch Cloud into their model cards repository, benefiting from out-of-the-box relevancy.

**3\. Quality of support and infrastructure outsourcing**

The Hugging Face team chose Meilisearch Cloud, in part due to its dedicated support capabilities. Given that achieving highly relevant search results within the repositories is of utmost importance to Hugging Face, the decision to opt for the Cloud version was further influenced by entrusting the infrastructure to the expertise of Meilisearch Cloud specialists. Outsourcing the infrastructure allows the Hugging Face team to enhance their development speed.

Implementation
--------------

With Meilisearch already implemented for Hugging Face documentation, the expansion of the search solution to other use cases was smooth, once the ranking and internal rules were in place.

Today, the Meilisearch engine powers the discovery of 220,000 model cards, 38,000 datasets, and 60,000 demos in the Hugging Face repository. The keyword filtering mechanism has already been implemented on the Hugging Face homepage for users who are already familiar with specific model names.

However, with the implementation of Meilisearch, users are given the option to perform full-text searches as well. This search functionality operates not only on the model names and IDs but also includes the entire content of model cards.

The additional button to “Try full-text search” was implemented in order to minimize changes in the search behavior, where users are free to choose the search experience that most fits their preference.

![](https://unable-actionable-car.media.strapiapp.com/ezgif_com_video_to_gif_bce9ae142e.gif)

Vision
------

With the ongoing evolution of AI, Hugging Face anticipates a shift in search behavior and the methods people use to find the projects they need. Hugging Face is looking forward to incorporating Semantic Search into its documentation and model card searches. Currently, the platform is actively testing Meilisearch [VectorDB](__GHOST_URL__/langchain-semantic-search-tutorial/) as one of the potential solutions.

Hugging Face also anticipates gaining more detailed usage insights, encompassing information about users' daily search patterns and the level of activity certain model card projects receive over time.

Hugging Face facilitates AI accessibility with Meilisearch

In this era of information overload, the efficiency of documentation is determined not just by its quality but also by how easily users can find what they're searching for. Enhancing your documentation with advanced search capabilities can significantly elevate user experience.

Meilisearch Cloud's **Documentation crawler** offers just that, bridging the gap between vast content and user-friendly searchability.

What is a crawler?
------------------

A web crawler, sometimes known as a 'spider' or 'bot', is a digital tool that roams the vast expanse of the internet, indexing and cataloging content for search engines. This ensures that the most relevant pieces of information are presented to users during their searches.

What is Meilisearch’s Documentation crawler?
--------------------------------------------

Meilisearch's Documentation crawler is not just a traditional crawler; it also functions as an efficient scraper. While it extracts vital data from web pages, it simultaneously honors the inherent structure of the documentation, ensuring precise and structured indexing.

This system allows users to integrate [search functionality](https://www.meilisearch.com/docs/learn/what_is_meilisearch/overview?utm_campaign=cloud-release&utm_source=blog&utm_medium=crawler-release#features) into their documentation, ensuring that their audiences can swiftly locate the information they need.

How to use the documentation crawler?
-------------------------------------

Using the Documentation Crawler is a breeze; all it requires is a Meilisearch Cloud project and your existing documentation's URL.

### Setting up your project

First of all, you need a running project in [Meilisearch Cloud](https://meilisearch.com/cloud?utm_campaign=cloud-release&utm_source=blog&utm_medium=crawler-release). Once you have created a project, navigate to your project's index list and create a new index.

![Step 1 of Create Index form: Enter the index name.](https://unable-actionable-car.media.strapiapp.com/create_an_index_57ca6f70f6.png)

### Crawling your content

When prompted to import your documents, choose 'Documentation Crawler.'

![Step 2 of Create Index form: Import documents via crawler or file upload.](https://unable-actionable-car.media.strapiapp.com/select_docs_crawler_e7c7fcfa52.png)

Then, input or paste your documentation's URL and click on ‘Next’.

![Step 2 of Create Index form: Import documents using a crawler by pasting the website URL](https://unable-actionable-car.media.strapiapp.com/paste_url_2f1c23072e.png)

Click on 'Run' to start crawling your documentation content and push it into a Meilisearch instance. This process may take several minutes.

![Setup interface for the Crawler with a 'Run' button.](https://unable-actionable-car.media.strapiapp.com/click_on_run_eeecb9b7eb.png)

### Post-crawling verification

Once the status updates to 'ready', you can return to your project's overview and access the 'search preview'. Click on the project’s URL or select the 'Preview search' option from the top menu.

![Project overview](https://unable-actionable-car.media.strapiapp.com/go_to_search_preview_255bd45a28.png)

Perform a few searches to ensure that your documentation has been indexed correctly. This step is especially useful for understanding the schema of your documents.

![Search preview displaying results for the query 'releva' with highlighted matches.](https://lh4.googleusercontent.com/BJ9jNV_RA4q42ONIw54vQXyCSEu41Q_6xKY5W6sMxK02XqufBV8iedNRSZZl6q2NtqKaZEjpOVDLEC7TFQmrj7nci5-FT87gFs8UnqfDa0M1PRrm-NLUD6odr2a4m1bbSIGgwlqxtyIqmEYQ3sI4YIc)

Adding a search bar to your documentation
-----------------------------------------

Once you've successfully indexed your documentation using Meilisearch's Documentation Crawler, the next step to enhancing user experience is integrating a search bar into your documentation.

Return to your project and navigate to your index settings. From there, select the 'tools' tab and then choose 'crawler'. This will reveal the crawler settings and associated resources.

![Setup interface for the Crawler with the 'UI starter kit: Doscsearch' option.](https://lh3.googleusercontent.com/woHfyr-bTDS7fbDTRnpq-GR61IwVq6fvfmCGoRDkiVORf7x6wSjSsXUgXRnmepr7YQ_E3HZHRBW3FScZSE1vS8GIJwvGs6GfUCIh0eJckapWsJViZyaZ-Bqa6Vdj_2EpXgHG4WLQTgUUN9ubYfXCQcA)

The [UI starter kit](https://github.com/tauri-apps/meilisearch-docsearch?utm_campaign=cloud-release&utm_source=blog&utm_medium=crawler-release) helps you add a functional search bar to your documentation with just a few lines of code.

You are now fully equipped to add a seamless search experience to your documentation!

\_\_\_\_\_

Stay in the loop by subscribing to our [newsletter](https://meilisearch.us2.list-manage.com/subscribe?u=27870f7b71c908a8b359599fb&id=79582d828e&utm_campaign=cloud-release&utm_source=blog&utm_medium=crawler-release). To learn more about Meilisearch's future and help shape it, take a look at our [roadmap](https://roadmap.meilisearch.com/?utm_campaign=cloud-release&utm_source=blog&utm_medium=crawler-release) and come participate in our [Product Discussions](https://github.com/meilisearch/product/discussions/?utm_campaign=cloud-release&utm_source=blog&utm_medium=crawler-release).

For anything else, join our developer community on [Discord](https://discord.gg/meilisearch?utm_campaign=cloud-release&utm_source=blog&utm_medium=crawler-release).

Introducing Documentation Crawler — Meilisearch Cloud

This feature enhances your dashboard experience by offering a comprehensive view of Meilisearch's [asynchronous operations](https://www.meilisearch.com/docs/learn/async/asynchronous_operations?utm_campaign=cloud-release&utm_source=blog&utm_medium=tasks-view-release).

**Core features**
-----------------

*   **Detailed task list**: the Tasks View showcases a list of your tasks, detailing their UID, status, type, index UID, duration, and enqueued date. Moreover, you can sort the list based on these parameters.
*   **JSON panel**: alongside the list, there's a panel displaying the selected task's JSON, which can easily be copied.
*   **Filtering**: you can sift through tasks based on their status, type, and date.
*   **Refresh option**: whenever a task is enqueued, the `Show new tasks` button lets you decide when to view the latest task without disrupting your current view.
*   **Customization**: customize the view further by toggling the columns' visibility according to your preferences.

![Tasks view screenshot](https://storage.noticeable.io/projects/OQ6S6bocohVRzziV6Tlc/publications/BLDwc6IdPRkf5ZsdEOoa/01h821n7ed9mje0m5y9dagk9rt-image.png)

**Compatibility notes**
-----------------------

*   **Version requirements**: this feature is exclusively available for projects that run on Meilisearch v1.0.0 or higher.
*   **Latest version perks**: for those using the [Meilisearch v1.3.0](__GHOST_URL__/v1-3-release/?utm_campaign=cloud-release&utm_source=blog&utm_medium=tasks-view-release) or above, the Tasks View also displays the count of fetched tasks.

We hope this addition enhances your project management efficiency. Enjoy exploring!

Meilisearch latest news and company updates