A step by step guide to adding site search to your Nuxt ecommerce

If you’ve just played around with Meilisearch using our quick start guide’s [movies dataset](https://www.meilisearch.com/movies.json), indexing your data may have taken Meilisearch only a few seconds. But if you worked with a larger dataset, it has probably taken a lot longer than that. In this article, we will review the best practices to help you index your data efficiently and speed up the indexing process.

Define your needs
-----------------

Meilisearch stores data in the form of discrete records, called [documents](https://docs.meilisearch.com/learn/core_concepts/documents.html), and each document must have a unique identifier—the [primary key](https://docs.meilisearch.com/learn/core_concepts/primary_key.html). Documents are grouped into collections, called [indexes](https://docs.meilisearch.com/learn/core_concepts/indexes.html).

To offer a search-as-you-type experience, Meilisearch needs to store and organize data in multiple manners so it can retrieve it in the most efficient way possible. Because of this, documents must undergo thorough processing before they are ready to be searched.

There are around twenty data structures per index in Meilisearch and constructing them is the most time-consuming part of the indexing process. Changing index settings may invalidate many of these data structures and require reindexing your data. Because of that, it’s usually a good idea to define the index settings before adding your documents.

### Searchable attributes

By default, all document fields added to Meilisearch are [searchable](https://docs.meilisearch.com/learn/configuration/displayed_searchable_attributes.html#the-searchableattributes-list). However, the words present in the fields listed in the [searchable attributes](https://docs.meilisearch.com/learn/configuration/displayed_searchable_attributes.html#searchable-fields) are the ones that require the most data structures–eleven, to be exact. A good way to speed up indexing is to make sure all the attributes in the searchable attributes list are the ones you really want to be checked for matching query words.

Let's take, for example, a document containing a field with an image URL. You probably want to display the image to the user, but I doubt that users are interested in being able to search for query terms in the URL. Don’t forget that not all [displayed fields](https://docs.meilisearch.com/learn/configuration/displayed_searchable_attributes.html#displayed-fields) need to be searchable!

It is not only important to specify in the list of searchable attributes the fields that are actually required, but it’s also essential to avoid having meaningless, random, or unique values in the searchable fields. Imagine all those databases out there full of ‘https’, ‘www’, ‘com’, or values like ‘I77lHE’—not exactly useful when trying to find a specific product or movie 😱

Speaking of which: 🤔unique values…does that ring a bell? 💡The primary key! That’s another field you can safely remove from the searchable attributes list.

#### Under the hood

To better understand the importance of customizing the searchable attributes index setting, let’s take a look at the largest data structures needed for the searchable attributes. Out of the eleven we mentioned, there are three that take the longest time to build: `WORD_DOCIDS`, `WORD_POSITION_DOCID`, and `WORD_PAIR_PROXIMITY_DOCIDS`.

To better understand how each data structure works, we’ll use the following set of documents as examples:

```JSON
{
    "id": 1,
    "description": "New York City is the most populous city in the USA"
},
{
    "id": 2,
    "description": "New York was named in honor of the Duke of York"
},
{
    "id": 3,
    "description": "Tel Aviv is the new most expensive city in the world"
}

```

In `WORD_DOCIDS`, each word is associated with the [primary key](https://docs.meilisearch.com/learn/core_concepts/primary_key.html) of the documents that contain it:

*   `“new” => [1, 2, 3]`
*   `“york” => [1, 2]`

In `WORD_POSITION_DOCID`, the keys are words together with their position in the document. The values associated with the keys are the documents where this word occupies the same position. In the documents above, `id` would be the attribute 0, and `description` the attribute 1:

*   `new(1,0) => [1, 2]` : in documents 1 and 2, the word “new” is located in attribute 1, position 0–it’s the first word of the attribute `description`
*   `new(1, 4) => [3]`: in document 3, “new” is located in attribute 1, position 4

Finally, in `WORD_PAIR_PROXIMITY_DOCIDS` Meilisearch keeps track of the distance between pairs of words across all documents in an index. Terms must be within 8 words of each other to be stored, as words further away are not considered part of the same context and, therefore, not relevant.

In the example documents above, Meilisearch would store the following pairs:

*   `newyork1 => [1, 2]`
*   `newcity2 => [1]`
*   `newcity3 => [3]`

The numbers attached to the word pairs represent the distance between them:

*   1 means the words are next to each other
*   2 means they are separated by one word
*   3 means they are separated by two words

As you can see, each new word represents extra rows in Meilisearch’s internal data structures. Values like unique ids or URL strings can make the databases grow tremendously–and most likely unnecessarily.

Refining which fields Meilisearch should search is critical to reduce indexing time. It can also lead to greater relevance and search speed, as the results won’t be contaminated with irrelevant data.

### Filterable and sortable attributes

Certain fields don’t contain any words, but might still be crucial to help your users find the results they need. This type of data might be a perfect match for filtering and sorting than regular text-based search.

[Filterable attributes](https://docs.meilisearch.com/learn/configuration/settings.html#filterable-attributes) are attributes that can be used as filters to refine search results. You can use them to restrict search results for a particular user or to create faceted search interfaces that allow the user to narrow down the list of results according to the criteria of their choice. Boolean-type values make great filters.

[Sortable attributes](https://docs.meilisearch.com/learn/configuration/settings.html#sortable-attributes) are attributes that can be used for sorting at search time, which allows users to decide which documents they want to see first. Numeric values are perfect for sorting.

As a rule of thumb, if your dataset contains documents with numeric and boolean field values, take the time to assess if they can be part of the filterable or sortable attributes lists.

### Ranking rules

Ranking rules are responsible for the relevancy of your search results. Meilisearch contains six built-in ranking rules:

```json
[
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "exactness"
]
```

You can also add custom rules for ascending and descending sort to this list:

```json
[
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "exactness",
  "price:asc"
]
```

Unlike sortable attributes, which are used to sort at search time, custom ranking rules are used to set a default order.

If you need this kind of default sorting, it is better to configure it beforehand. Adding a new rule after documents have already been indexed will trigger a reindexing and potentially your nerves!

Size down and batch up
----------------------

Index only what you really need. Are all the columns in your database necessary? The fewer columns in your dataset, the smaller the documents. The smaller the documents, the less they will weigh, and the faster they will reach Meilisearch, which will then be able to process them sooner.

Meilisearch combines consecutive document addition requests into a single batch and processes them together. This significantly speeds up the indexing process. Since the final size of each batch will depend on how much data Meilisearch received while it was processing the latest document addition request, it is therefore encouraged to send documents in groups rather than one by one.

For the same reason, consider compressing your data. Meilisearch supports the `br`, `deflate`, and `gzip` compression methods. You can find more information in our [documentation](https://docs.meilisearch.com/reference/api/overview.html#content-encoding).

Stay up to date and keep us updated
-----------------------------------

Use the latest [stable version of Meilisearch](https://github.com/meilisearch/meilisearch/releases). New releases often include performance improvements that can significantly increase indexing speed.

If you experience any indexing issues, please [report them](https://discord.gg/meilisearch)! It’s key to improving the product!

Don’t trust me, trust the data
------------------------------

While creating some benchmarks, [Many](https://github.com/ManyTheFish), software engineer of the Engine team, created the following graph. Please note that the indexing time is highly dependent on the size of the machine (CPUs, RAM) and the dataset: for a similar-sized dataset, you may obtain different results.

![Line graph that compares the indexing time with two different configurations (default and custom) in relation to the dataset size. In all cases, the speed is higher with a custom configuration.](https://lh4.googleusercontent.com/l8KRD6C64sT2wPL39Zx6EVzzqk1UOIbYUItL9uWSTT2hd1vfPMEp-j_yMCAXciebMOZQBm9IyVp5XnJHk7XWt3hVl4QUiqXHkRReBq3ERs-jZwVw6QQgU-_eircOWWxu0-VmCRGrQy3F8OTqvQOjU-Z-iCVi1ECgyqesCnTQhG4s-OWM-mz0zJQZ6oNfSw)

The horizontal axis represents the dataset's size, and the vertical axis represents the indexing time

The red line represents indexing time using default settings, and the blue line represents indexing time using a custom configuration. With the same machine and dataset, we observed a 36% gain in indexing speed when using custom settings.

We observed similar improvements in database size, which was considerably smaller when using custom settings:

![Bar graph of the database size where the database with custom settings is significantly smaller than the one with default settings.](https://lh3.googleusercontent.com/5whDEpcglxFIPRfTzHqmJudSWis4ig2BMfvSwJT5LrLVjp43PnsHXRBvJrsH9RTBkKYDjHuOPAcfu4ZWsUIuZnVNJGepYzRG_WD0zvkMoEMZyBGZcSuJcdFELNi96tzagnfe_H9Q8v7SG-kE7H8ysXfRxMTQyi-_Wmw5JPak5kwsQWdLo6QriHLyYN-n8Q)

Database size with custom settings in blue and default settings in red

* * *

Learn more about what Meilisearch can bring to your business

[Talk to a search expert](https://dub.sh/meili-sales)

* * *

And that’s all for now! We covered the best practices to speed up the indexing process. Did you know any of these tips? Have you noticed a difference in indexing speed after following them? Share your experience on our [Discord](https://discord.meilisearch.com/)!

Your feedback is key to helping us improve Meilisearch! I can't stress this enough and I never tire of repeating it, because it is the truth. Our community has built Meilisearch with us and continues to help us shape it.

[Issues](https://github.com/meilisearch/meilisearch/issues/new/choose) or [product discussions](https://github.com/meilisearch/product/discussions) on GitHub, our [roadmap](https://roadmap.meilisearch.com), our [Discord server](https://discord.meilisearch.com/)… No matter where, no matter how, we want to hear from you!

Are you indexing the smart way?

The following guide will walk you through the steps required to update your Meilisearch instance on DigitalOcean, AWS, or GCP when using the Meilisearch official images.

Before you begin, please note the following:

*   This guide does not work for versions below v0.15. Since dumps were introduced in v0.15, you’ll need to reindex all your documents and settings manually if you are on v0.14 or below
*   If you are updating to v0.28 or above, keys imported from the old version will have their `key` and `uid` fields regenerated
*   You’ll need to connect via SSH to your cloud instance, and depending on the user you are connecting with (root, admin, etc.), you may need to prefix some commands with `sudo`

Also, if you are using v0.22 or above, you can use our [migration script](https://github.com/meilisearch/meilisearch-migration) and let it do all the work for you!

Step 1: Check your Meilisearch version
--------------------------------------

You need to know your Meilisearch version. If you don’t know or are not sure, you can use the get version endpoint:

```bash
curl \
  -X GET 'http://<your-domain-name>/version' \
  -H 'Authorization: Bearer API_KEY'

```

If you get a `missing_authorization_header` error code, you might be on v0.24 or below. Change the authorization header to `X-MEILI-API-KEY` as follows:

```bash
curl \
  -X GET 'http://<your-domain-name>/version' \
  -H 'X-Meili-API-Key: API_KEY'  

```

Check your `pkgVersion` if it's “0.21.0” or higher, you can go straight to [step 3](#step-3-create-the-dump). If not, please proceed to the next step.

Step 2: Set all fields as displayed attributes
----------------------------------------------

<Callout>
  This step is only mandatory if you are on v0.20 or below.
</Callout>

‌‌

When creating dumps using Meilisearch versions below v0.21, all fields must be [displayed](https://docs.meilisearch.com/learn/configuration/displayed_searchable_attributes.html#displayed-fields) in order to be saved in the dump.

First, you need to verify the displayed attributes list.

```bash
# whenever you see {index_uid}, replace it with your index's unique id
curl \
  -X GET 'http://<your-domain-name>/indexes/{index_uid}/settings/displayed-attributes' \
  -H 'X-Meili-API-Key: API_KEY'  

```

If the response includes `{'displayedAttributes': '["*"]'}`, you can move on to [step 3](#step-3-create-the-dump).

‌‌If it's something else, save the current list to restore it after the migration is complete, and proceed to reset the list of displayed attributes to its default value (`[“*”]`):

```bash
curl \
  -X DELETE 'http://<your-domain-name>/indexes/{index_uid}/settings/displayed-attributes' \
  -H 'X-Meili-API-Key: API_KEY'  

```

This command returns an `updateId`. You can use this to track the status of the operation.

```bash
# replace {updateId} with the updateId returned by the previous request
curl \
  -X GET 'http://<your-domain-name>/indexes/{index_uid}/updates/{updateId}' \
  -H 'X-Meili-API-Key: API_KEY'  

```

Once the status is `processed`, you're good to go.

Now that all fields are displayed proceed to the next step.

Step 3: Create the dump
-----------------------

Before creating your dump, make sure that your [dump directory](https://docs.meilisearch.com/learn/configuration/instance_options.html#dumps-destination) is accessible. By default, dumps are created in a folder called dumps in the configuration file directory: `/var/opt/meilisearch/dumps`.

‌‌You can then create a dump of your Meilisearch database:

```bash
# replace the header with -H 'X-Meili-API-Key: API_KEY' if you are on v0.24 or below
curl \
  -X POST 'http://<your-domain-name>/dumps' \
  -H 'Authorization: Bearer API_KEY' 


```

‌‌If you are on v0.27 or below, dumps use a separate queue from the task queue. The response should return a dump `uid`. You can use it to track the status of the dump with the get dumps status endpoint:

```bash
# replace the header with -H 'X-Meili-API-Key: API_KEY' if you are on v0.24 or below
curl -X GET 'http://<your-domain-name>/dumps/{uid}/status' \
  -H 'Authorization: Bearer API_KEY' 


```

Once the dump status is `done`, you can move on to the next step.

```JSON
{
    "uid":"20221130-110940190",
    "status":"done",
    "startedAt":"2022-11-30T11:09:40.190772Z",
    "finishedAt":"2022-11-30T11:09:45.94484Z"
}

```

‌‌‌‌If you are on v0.28 or above, dumps are considered tasks and share the task queue. The response should then return a `taskUid` you can use to track its status with the get task endpoint:

```bash
curl \
  -X GET 'http://<your-domain-name>/tasks/{taskUid}' \
  -H 'Authorization: Bearer API_KEY’ 

```

‌‌Once the `dumpCreation` task shows `"status": "succeeded"`, you're ready to move on to the next step.

```json
{
  "uid": 1,
  "indexUid": null,
  "status": "succeeded",
  "type": "dumpCreation",
  "canceledBy": null,
  "details": {
	"dumpUid": "20220621-161029217"
  },
  "error": null,
  "duration": "PT0.025872S",
  "enqueuedAt": "2022-06-21T16:10:29.217688Z",
  "startedAt": "2022-06-21T16:10:29.218297Z",
  "finishedAt": "2022-06-21T16:10:29.244169Z"
}

```

‌Step 4: Stop the Meilisearch instance
--------------------------------------

If you haven’t done it yet, connect via SSH to your cloud instance and execute the following command to stop Meilisearch. Remember you may need to prefix it with `sudo` if you are not connected as root.

```bash
systemctl stop meilisearch
```

‌‌Step 5: Save the current binary and database for backup
---------------------------------------------------------

Move the binary of the current Meilisearch version and the database to the tmp/ folder:

```bash
mv /usr/bin/meilisearch /tmp
mv /var/lib/meilisearch/data.ms /tmp/

```

‌Step 6: Install the desired version of Meilisearch
---------------------------------------------------

‌‌‌‌You can use this command to download the Meilisearch binary. Replace `{meilisearch_version}` with the version of your choice formatted like this: `vX.X.X`.

```json
curl "https://github.com/meilisearch/meilisearch/releases/download/{meilisearch_version}/meilisearch-linux-amd64" --output meilisearch --location --show-error
```

Make the meilisearch binary executable:

```bash
chmod +x meilisearch
```

Move the new Meilisearch binary to the directory containing the executable files:

```bash
mv meilisearch /usr/bin/meilisearch
```

Step 7: Launch Meilisearch and import the dump
----------------------------------------------

‌Now that you’ve got the desired Meilisearch version, execute the command below to import the dump at launch.

Don’t forget to replace the `dump_uid.dump` with the actual dump file name.

```json
meilisearch --db-path /var/lib/meilisearch/data.ms --import-dump "/var/opt/meilisearch/dumps/dump_uid.dump"
```

Importing a dump requires indexing all the documents it contains. Depending on the size of your dataset, this process can take a long time and cause a spike in memory usage.

Step 8: Restart Meilisearch as a service
----------------------------------------

Once your dump has been correctly imported, press `Ctrl`+`C`  to stop Meilisearch. Next, execute the command below to run the script to configure Meilisearch and restart it as a service:

```json
meilisearch-setup
```

Don’t forget to set `displayedAttributes` back to its previous value if necessary. You can do this using the [update displayed attributes endpoint](https://docs.meilisearch.com/reference/api/settings.html#update-displayed-attributes).

🎉 Congratulations! You have successfully migrated your Meilisearch database to the latest version!

Step 9: Clean files or rollback
-------------------------------

### Clean files

If you’ve gone through all the previous steps and Meilisearch is up and running, it’s time to do some cleanup. Remember those files we saved for backup? You can delete them with the following commands:

```bash
rm /tmp/meilisearch
rm -r /tmp/data.ms
```

‌Since you no longer need it, you can also delete the dump file:

```bash
rm /var/opt/meilisearch/dumps/{dump_uid.dump}
```

### Ro‌‌llback

If for some reason, something went wrong, you can always roll back to the previous version. Move the files back to their previous location using:

```bash

mv /tmp/meilisearch /usr/bin/meilisearch
mv /tmp/data.ms /var/lib/meilisearch/data.ms
```

‌And run the configuration script:

```bash
meilisearch-setup
```

‌‌Everything should be as it was. Phew!

I hope this guide has helped you to enjoy all the advantages of the latest version of Meilisearch. Don’t forget our support team is always ready to help! We have a dedicated support channel on our brand new [Discord](https://discord.gg/meilisearch) server!

‌‌‌‌‌‌‌‌‌‌

How to update your app to the latest Meilisearch version

v0.30 of Meilisearch was released earlier this month. With it, our primary goal was to make the Meilisearch workflow as smooth as possible. After all, we are on the road to v1, and our destination is closer than ever. For that, having index deployment with zero downtime was a crucial step. We’re happy to say that v0.30 solves this problem, making it easier than ever to update an index in production. Read on to learn more about how the feature works!

  
The challenge
----------------

Suppose you have changes in your database that you need to synchronize with your Meilisearch index in production. What do you do? Well, if you were working on Meilisearch v0.29, you might:

### Update your index

🙅‍♀️  Simple, right? But if you’ve ever tried it, then you should already know…

![It's a trap!](https://media.tenor.com/FtNhFA1nSo0AAAAC/star-wars-its-a-trap.gif)

Updating your production index while it receives search queries can result in inconsistencies with results or even missing information. You don’t want to offer that search experience, do you? Otherwise, you wouldn't be using Meilisearch 😁

### Delete the index, create a new index with the same name, and re-index the data

⌛ Each step will take some time. Even if it’s just a few seconds, it’s a few seconds of downtime… And that’s at least three requests! A few seconds here plus a few seconds there can result in minutes of downtime! No, thank you very much.

### Create a new index with another name, stage the changes there, then modify all the clients to point to the new index

🤔 Well, it’s not the worst option. But again, updating the clients leads to downtime 😞 In some cases, it isn’t even up to the developer when the client update will be pushed to production. Take an iOS app for example: Apple has to review the new version before you can release it, which can be a major drag on your release plan.

### Create an intermediate redirection layer to avoid downtime

🧞 Very clever! While this is a good approach, it's not the most straightforward. It requires architectural knowledge, time, and extra tools.

Aren't you glad you never have to do any of these things again?

The silver bullet
-----------------

Meilisearch has always been committed to offering the best developer experience.

Our team has been working hard for the past months, and after several iterations, they’ve come up with a solution that integrates seamlessly into the developer’s stack: **index swapping**.

Let me show you how it works.

Let’s say you have an index in production—`indexA`—in which your clients search. You want to sync the changes in your primary database with Meilisearch. To do so, you would follow the steps below.

### Step 1: Create a new index with up-to-date data

First, you need to create an index—let’s call it `indexA_new`—representing the new version of `indexA` that you want to deploy to your search clients. Add up-to-date documents from your database, and update the index settings if necessary.

Don’t forget to check that all the tasks related to the index creation have successfully completed, including `indexCreation`, `settingsUpdate`, and `documentAdditionOrUpdate` task types. You can use the `/tasks` [route](https://docs.meilisearch.com/reference/api/tasks.html#tasks) to get information about their progress.

### Step 2: Test the new index

Before sending your index to production, you want to be sure everything is working as expected.

![Meme: image of a city on fire in the middle of a thunderstorm, the text reading: "text in production" they said, "what could go wrong" they said ](https://unable-actionable-car.media.strapiapp.com/test_in_production_meme_1_63b857925c.jpg)

Make sure to update the settings for any new fields you may have introduced with the updated data. For example, you may want to add new fields to `searchableAttributes`, `filterableAttributes`, and/or `sortableAttributes`. Don't forget to double-check the relevancy of search results any time you add new data!

👉 Keep in mind that the `searchableAttributes` list not only designates the fields that are searchable, but also dictates the [attribute ranking order](https://docs.meilisearch.com/learn/core_concepts/relevancy.html#attribute-ranking-order). Make sure any new fields you may have introduced are added to the list in the right order.

### Step 3: Swap indexes

Once your `indexA_new` has been successfully created, filled with data, and tested, it’s ready to be deployed with an **index swap**. To do so, send a `POST` request to the `/swap-indexes` endpoint. Specify the indexes you want to swap in the payload. Since it’s a swap, the order doesn’t matter.

```bash
curl \
-X POST 'http://localhost:7700/swap-indexes' \
-H 'Content-Type: application/json' \
--data-binary '[
	{ "indexes": ["indexA", "indexA_new"] }
]'
```

👉 In a [protected](https://docs.meilisearch.com/learn/security/master_api_keys.html#protecting-a-meilisearch-instance) Meilisearch instance, the API key used to swap indexes must have access to the `indexes.swap` action as well as the indexes you want to swap. If not, Meilisearch will throw an `invalid_api_key` [error](https://docs.meilisearch.com/reference/errors/error_codes.html#invalid-api-key). For more information about creating API keys with specific permissions, see the [documentation](https://docs.meilisearch.com/learn/security/master_api_keys.html#creating-an-api-key).

You can use the response's `taskUid` to track the status of your request with the `GET /tasks/{task_uid}` [endpoint](https://docs.meilisearch.com/reference/api/tasks.html#get-tasks). A successful index swap should look like this:

```JSON
{
  "uid": 23,
  "indexUid": null,
  "status":"succeeded",
  "type":"indexSwap",
  "details":{
	"swaps": [
  	     {"indexes": ["indexA", "indexA_new"]},
	]
  },
  "duration": "PT1S",
  "enqueuedAt": "2021-08-10T14:29:17.000000Z",
  "startedAt": "2021-08-10T14:29:18.000000Z",
  "finishedAt": "2021-08-10T14:29:19.000000Z"
}

```

Your indexes have been swapped without any downtime! The documents, settings, and task history of `indexA`—except for any enqueued tasks—have been swapped with those of `indexA_new`. Every mention of `indexA` in the task history has been replaced by `indexA_new` and vice-versa (`enqueued` tasks are left unmodified).

![Animation illustrating index swapping: an index receives search queries while the another is being created in the background. When the second index is ready, they swap, then the unnecessary index is deleted.](https://unable-actionable-car.media.strapiapp.com/ezgif_4_520c610091_8f72080b3b.gif)

After the swap, `indexA_new` holds the outdated content. You can delete it or keep it as a backup, should something go wrong and you need to swap back. Better safe than sorry!

And that’s it! Only three steps, two if you like to live dangerously. Could this get any better?

The cherries—yes, plural—on the cake 🍰
---------------------------------------

What if I tell you that you can swap several indexes with just one request?

I am not kidding. A single request can swap as many index pairs as you wish. Meilisearch can deploy all changes at the same time. Clients will access the new version of all indexes at once without any downtime.

```bash
curl \
  -X POST 'http://localhost:7700/swap-indexes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    {
        "indexes": ["indexA", "indexA_new"]
    },
    {
        "indexes": ["indexB", "indexB_new"]
    },
    {
        "indexes": ["indexC", "indexC_new"]
    }
]'

```

In the example above, three swap operations will occur simultaneously and atomically.

Wait, what?

Yes, you can read that again. It’s atomic! Either all indexes are successfully swapped, or none are. Either all the content is swapped, or none is.

Why is that important? It prevents partial changes in the database, ensuring consistency and, thus, a top-notch search experience.

Conclusion
----------

As I mentioned earlier, this feature has been in the works for several months, and it all started with user feedback. The [“swap indexes” card](https://roadmap.meilisearch.com/c/65-swap-indexes) on our roadmap got 38 votes and almost as many comments explaining use cases where this feature is a must-have. Here are some of our favorites:

*   “It would be very useful when trying to change rules on production database to tweak for the best results”
*   “Would help if index was accidentally created with wrong name or need to rename/change it for various reasons.”
*   “We need it to clean out all deleted items.”

These are just a few examples. This kind of insight is extremely helpful for our team, as it allows us to shape the product to fit the users' needs.

While very convenient—you can have an overall view of all the feature ideas submitted, in the making, and released—the [roadmap](https://roadmap.meilisearch.com/) is just one of the options to provide feedback.

The [product discussions](https://github.com/meilisearch/product/discussions) on GitHub are, in my opinion, one of the best places to explain your needs. You can have direct contact with the Meilisearch product team, and, being public, it allows anyone to participate and enrich the process.

The last option is our brand-new [Discord server](https://discord.gg/meilisearch). Don’t hesitate to join us and talk about what you’ve built with Meilisearch, your use case, and your specific needs.

No matter which option you choose, we look forward to hearing from you!

Zero downtime index deployment

<Callout>
  This post was originally published in May 2020 by guest author [Riccardo Giorato](/blog/author/riccardo/)t the time, Meilisearch was on v0.09. It has been updated by [Carolina Ferreira](/blog/author/carolina/)o work with Meilisearch v1. You can find the first version of the post on [GitHub](https://github.com/meilisearch/tutorials/tree/main/src/react-decathlon/original-tutorial/original-tutorial.md).
</Callout>

Introduction
------------

In this tutorial, you'll learn how to easily create a search-based web app with instant and reliable results thanks to the power of Meilisearch.

We will cover the basic steps to add our data to Meilisearch, create a custom front-end search, and move on to customization at the end.

For this tutorial, we are going to create an instant search experience for a sports brand. Here is a preview of what you will be building:

![Searching for multiple items on the decathlon demo using Meilisearch](https://unable-actionable-car.media.strapiapp.com/decathlon_d14c32764d.gif)

Prerequisites
-------------

Before getting started, ensure that you have [Node.js](https://nodejs.org/en/) >= 18 installed on your machine.

You can follow this tutorial and write the code as you go through the steps, using this [GitHub project](https://github.com/meilisearch/tutorials/tree/main/src/react-decathlon).

Finally, this tutorial assumes that you are already familiar with React. If that is not the case, you can check the [React Documentation](https://reactjs.org/docs/getting-started.html) to learn more.

Getting Started
---------------

### Clone the repository

Clone the GitHub repository using the following command:

```json
git clone https://github.com/meilisearch/tutorials.git
cd src/react-decathlon

```

### Run a new Docker image

If you cloned the repository to set up the Meilisearch instance, just execute the following commands inside the main folder:

```json
npm install
npm run setup_meili
```

If you didn't clone the repository and want to launch Meilisearch using Docker, execute this command:

```json
docker run -it --rm \
    -p 7700:7700 \
    -e MEILI_ENV='development' \
    -v $(pwd)/meili_data:/meili_data \
    getmeili/meilisearch:v1.0
```
<Callout>
  By default, Meilisearch's API is unprotected. You will need a master key in production. You can learn more about it in our [documentation](https://docs.meilisearch.com/learn/security/master_api_keys.html).
</Callout>

You can check if Meilisearch is running by visiting: [http://localhost:7700/](http://localhost:7700/)

Want to avoid a local installation? To quickly create a best-in-class search experience, we offer the convenience of [Meilisearch Cloud](https://cloud.meilisearch.com/?ref=blog.meilisearch.com), a hosted and fully‑managed version of Meilisearch. There's a free 14-day trial, no credit card required 😉

### Create an index in Meilisearch

An index is an entity where documents are stored, like an array of objects with some specific settings attached to it, and a unique [primary key](https://docs.meilisearch.com/learn/core_concepts/primary_key.html#primary-key).

Each document indexed must have a primary field, a special field that must be present in all documents. This field holds the unique value of the document: its id.

Meilisearch can infer the primary key from your dataset, provided that it contains the `id` substring. You can also set it explicitly.

Below is a sample document to add to Meilisearch.

```javascript
{
  "id": 100013768717,
  "name": "Fitness Foldable Shoe Bag",
  "url": "https://www.decathlon.com/products/gym-foldable-shoe-bag",
  "vendor": "Domyos",
  "category": "Sport bag",
  "tags": [
    "Artistic Gymnastics",
    "Boy's",
    "CARDIO_FITNESS_ACCESSORIES",
    "CARDIO_FITNESS_BAGS",
    "CODE_R3: 11782"
  ],
  "images": "https://cdn.shopify.com/s/files/1/1330/6287/products/sac_20a_20chaussure_20kaki_20_7C_20001_20_7C_20PSHOT_20_490180e6-44e4-4340-8e3d-c29eb70c6ac8.jpg?v=1584683232",
  "creation_date": "2020-04-03T15:58:48-07:00",
  "price": "2.49"
}

```

You can easily create this index with a REST client like [Postman](https://www.postman.com/), but in this tutorial, we will use the [Meilisearch Javascript SDK](https://github.com/meilisearch/meilisearch-js/) to do it directly from Node.js.

```javascript
const { MeiliSearch } = require('meilisearch')

;(async () => {
  try {
    const config = {
      host: 'http://localhost:7700'
    };

    const meili = new MeiliSearch(config);
    
    await meili.createIndex('decathlon'); 
    
    // or you can set the primary key explicitly: 
    // await meili.createIndex({ uid: "decathlon", primaryKey: "id" });
        
  } catch (e) {
    console.error(e);
    console.log("Meili error: ", e.message);
  }
})();

```

You can read more about the properties of indexes in the [Meilisearch documentation](https://docs.meilisearch.com/learn/core_concepts/indexes.html).

### Index documents

Meilisearch receives documents in JSON format and stores them for searching purposes. These documents are composed of fields that can hold any type of data. Meilisearch also accepts datasets in the following formats: NDJSON and CSV. You can read more about the format in the [documentation](https://docs.meilisearch.com/learn/core_concepts/documents.html#upload).

For this tutorial, you can download this dataset full of sportswear items: [**decathlon.json**](https://github.com/meilisearch/tutorials/tree/main/src/react-decathlon/backend/decathlon.json)

Use the following script to upload all the objects from this JSON file to Meilisearch. Remember to change the path to your JSON file before running it!

```javascript
const { MeiliSearch } = require('meilisearch')

;(async () => {
  try {
    const config = {
      host: 'http://localhost:7700'
    };

    const meili = new MeiliSearch(config);

    const decathlon = require("../decathlon.json"); // path to json file

    const index = meili.index("decathlon");
    
    await index.addDocuments(decathlon);
        
  } catch (e) {
    console.error(e);
    console.log("Meili error: ", e.message);
  }
})();

```

Prepare the React app
---------------------

We'll need a standard React app. You can use the project you cloned before in the [Getting started](/blog/instant-search-react-app/#getting-started)ection.

If you prefer to start from an empty app, you can create your own using [Create React App](https://create-react-app.dev/) with the command below. You can name the application however you desire.

```json
npx create-react-app meili_react_demo
cd meili_react_demo

```

### Include Tailwind CSS

To speed up the styling process, add [Tailwind CSS](https://tailwindcss.com/) style directly into the `<head>` element of the index.html file:

```html
  <script src="https://cdn.tailwindcss.com"></script>

```

### Configure App.js state

Then, modify the `App.js` file using this code to set up a simple search form and a few state variables to handle every aspect of the search.

```javascript
import React, { useState, useEffect } from 'react'
import { MeiliSearch } from 'meilisearch'
import Item from './components/Item'

// TODO configure the MeiliSearch Client

const index = client.index('decathlon')

function App () {
  const [searchedWord, setSearch] = useState('')
  const [resultSearch, setResults] = useState([])

  // TODO add function to send searchedWord to Meilisearch

  return (
    <div className='mx-auto'>
      <div className='header font-sans text-white items-center justify-center'>
        <header className='py-12'>
          <img
            className='h-20 w-auto items-center justify-center p-2 mx-auto'
            src='/wide_logo.png'
            style={{ filter: 'invert(0%)' }}
            alt='Decathlon logo'
          />
          <h1 className='flex flex-wrap flex-grow text-3xl w-full justify-center p-4'>
            Stop looking for an item — find it and work hard!
          </h1>
          <div className='border rounded overflow-hidden w-full flex justify-center mx-auto searchBox mt-6'>
            <button className='flex items-center justify-center px-4 shadow-md bg-white text-black'>
              <svg
                className='h-4 w-4 text-grey-dark'
                fill='currentColor'
                xmlns='http://www.w3.org/2000/svg'
                viewBox='0 0 24 24'
              >
                <path d='M16.32 14.9l5.39 5.4a1 1 0 0 1-1.42 1.4l-5.38-5.38a8 8 0 1 1 1.41-1.41zM10 16a6 6 0 1 0 0-12 6 6 0 0 0 0 12z' />
              </svg>
            </button>
            <input
              type='text'
              value={searchedWord}
              onChange={(event) => setSearch(event.target.value)}
              className='px-6 py-4 w-full text-black'
              placeholder='Product, sport, color, …'
            />
          </div>
        </header>
      </div>
      <div>
        <div className='flex flex-wrap searchResults'>
          // TODO iterate over the search results to display them with the Item component
        </div>
      </div>
    </div>
  )
}

export default App


```

This code should output this beautiful header with a search form.

![Decathlon header with a search bar](https://unable-actionable-car.media.strapiapp.com/download_60983dd13f.png)

Search results in React
-----------------------

Connecting React with Meilisearch using the [Javascript SDK](https://github.com/meilisearch/meilisearch-js/) is a simple operation that can be done in just a few steps.

### Meilisearch client

Install the Meilisearch SDK using the following command:

```json
// if you use npm
npm install meilisearch
// if you use yarn
yarn add meilisearch

```

Set up the Meilisearch client with the server URL. In our case, it was the localhost Docker machine. Finally, load the right index from the backend.

Replace this comment in `App.js` with the code snippet below:

"// TODO configure the Meilisearch Client"

```javascript
import { MeiliSearch } from "meilisearch";

const client = new MeiliSearch({
  host: "http://localhost:7700/",
});

const index = client.index("decathlon");

```

### Send the search query

Add a `useEffect` hook to execute the search of the typed words into Meilisearch. All the results will be set to a simple state variable called `resultsSearch`.

Replace this comment in `App.js` with the code snippet below:

"// TODO add function to send searchedWord to Meilisearch"

```javascript
  useEffect(() => {
    // Create a scoped async function in the hook
    async function searchWithMeili() {
      const search = await index.search(searchedWord);
      setResults(search.hits);
    }
    // Execute the created function directly
    searchWithMeili();
  }, [searchedWord]);

```

### Showcase the results

You will iterate over the JSON objects returned by Meilisearch —they'll have the same structure as the uploaded JSON objects— and you'll display them in an `Item` component, linking to the product pages.

Let's create the `Item` component that will help us display our products. Create a components folder with an `Item.js` file inside, and copy-paste the following code snippet:

```javascript
function Item ({ url, image, name, category, vendor, price, id }) {
  return (
    <div className='flex w-full sm:w-1/2 md:w-1/3 lg:w-1/4 xl:w-1/6 p-3' key={id}>
      <a className='flex-1 rounded overflow-hidden shadow-lg' href={url}>
        <img
          className='w-full h-48 object-cover'
          src={image}
          alt={name}
          onError={(e) => {
            e.target.onerror = null
            e.target.src = '/wide_logo.png'
          }}
        />
        <div className='px-6 py-3'>
          <div className='font-bold text-sm mb-1 text-gray-600 capitalize'>
            {category}
          </div>
          {name}
          <div className='font-bold text-xl mb-2 text-gray-800'>
            {vendor} -
          </div>
          <p className='text-black text-xl font-bold text-base py-2'>
            $ {price}
          </p>
        </div>
      </a>
    </div>
  )
}

export default Item

```

Then, replace this comment in `App.js` with the code snippet below:

```javascript
{resultSearch?.map((result) => (
    <Item
      url={result.url}
      image={result.images}
      name={result.name}
      category={result.category}
      vendor={result.vendor}
      price={result.price}
      key={result.id}
      />
))}

```

You can have a look at the fullcode on [GitHub](https://github.com/meilisearch/tutorials/tree/main/src/react-decathlon/src/App.js).

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

Configure the search
--------------------

With Meilisearch, you get a ton of customization options for fine-tuning your search experience. We will take a look at a few features here. You can read more about them in the [documentation](https://docs.meilisearch.com/learn/getting_started/customizing_relevancy.html).

### Search Ranking

We will start with changing the ranking rules, the criteria Meilisearch uses to sort the documents you uploaded whenever a search query is made. The order of the ranking rules influences the relevancy of your search results. You can learn more about it in the [documentation](https://docs.meilisearch.com/learn/core_concepts/relevancy.html#ranking-rules).

Let's use the following order:

```json
[
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "exactness",
  “creation_date:desc”
]

```

This uses the default order along with a custom rule: `creation_date`. This rule ranks items by their creation date if all previous values are identical.

### S**earchable attributes**

You can also configure [searchable attributes](https://docs.meilisearch.com/learn/configuration/displayed_searchable_attributes.html#searchable-fields). These are attributes whose values Meilisearch searches for matching query words. By default, all attributes are searchable, but you can configure it so that it only searches the `name`, `vendor`, `category`, and `tags` fields, leaving out `images` and `URL`:

```json
searchableAttributes: ["name", "vendor", "category", "tags"]
```

### Displayed attributes

Displayed attributes are attributes that Meilisearch can return to the user in the front-end application with the [displayedAttributes](https://docs.meilisearch.com/learn/configuration/displayed_searchable_attributes.html#displayed-fields) array. Like searchable attributes, all attributes are displayed by default.

```json
    "displayedAttributes": [
      "name",
      "vendor",
      "category",
      "tags",
      "images",
      "url"
    ]
```

### Upload the new settings to Meilisearch

It’s time to customize our Meilisearch index with the search settings explained above.

```javascript
const { MeiliSearch } = require('meilisearch')

;(async () => {
  try {
    const config = {
      host: 'http://localhost:7700'
    };

    const meili = new MeiliSearch(config);
    
    const index = meili.index("decathlon");

    const newSettings = {
      rankingRules: [
        "words",
        "typo",
        "proximity",
        "attribute",
        "sort",
        "exactness",
        "creation_date:desc"
      ],
      searchableAttributes: ["name", "vendor", "category", "tags"],
      displayedAttributes: [
        "name",
        "vendor",
        "category",
        "tags",
        "images",
        "url"
      ]
    };

    await index.updateSettings(newSettings);
        
  } catch (e) {
    console.error(e);
    console.log("Meili error: ", e.message);
  }
})();


```

Conclusion
----------

This quick search wouldn’t be possible without an incredible team working on this great project night and day! If you enjoy contributing to the Meilisearch family, check out the following repositories:

*   [Meilisearch](https://github.com/meilisearch/MeiliSearch)
*   [meilisearch-js](https://github.com/meilisearch/meilisearch-js)

* * *

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.meilisearch.com/?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).

How to implement instant search in your React app

Meilisearch v0.29 is out and comes with a new feature: matching strategy customization!

Consider the following situation: a user sends a two-word search request. What happens when there are not enough documents to meet the requested `limit`? Should the engine only return documents with all the query terms? Or should it return more documents? If so, which criteria should it apply to return them?

That’s where  matching strategies come in. A matching strategy is used to match query terms when the engine has not found enough documents containing all query terms. It’s not an easy decision to make, and it’s highly dependent on the type of data the user is searching for. Fortunately, now you can choose the strategy to apply at search time 🎉

**A little bit of history**
---------------------------

Back in 2021, all versions pre v0.21 only returned documents where all the query terms were present. So if I searched for “Peter Parker”, it would just return documents in which both terms —“peter” and “parker”— were present. This matching strategy is called: `all` because **all** query terms must be present in the document for it to be returned.

![You're welcome GIF](https://unable-actionable-car.media.strapiapp.com/image_8205358452.gif)

[Ranking rules](https://www.meilisearch.com/docs/learn/core_concepts/relevancy#ranking-rules) are one of Meilisearch’s most important features for  ensuring relevant results. The _[words](https://www.meilisearch.com/docs/learn/core_concepts/relevancy#1-words)_ ranking rule states the following:

Results are sorted by decreasing number of matched query terms. Returns documents that contain all query terms first.

This rule had been lying around in our documentation for a while, coupled with the following warning message:

For now, it is mandatory that all query terms are present in returned documents. Therefore, this rule does not impact search results yet.

With v0.21, the words rule started working, so this warning disappeared with the all-query-terms-present constraint.

From that point on, if there were not enough documents containing all query terms, Meilisearch removed one term at a time, starting from the end of the query. So if I searched for “Peter Parker”, it would first return documents in which both terms were present, followed by documents with just “Peter”

This type of matching strategy is called `last` because Meilisearch removes the **last** term of the query.

![Nailed it GIF](https://unable-actionable-car.media.strapiapp.com/image_1_533740ccdb.gif)

It turned out that many users were pretty content with the previous matching behavior. Unfortunately, this change did not allow them to migrate to a newer version of Meilisearch, which prevented them from benefiting from its many improvements: sorting at search time, geosearch, granular API keys rights, multi-tenancy, etc. Not only were they missing all that, but they were going to miss all the awesome features to come! 😱

Don’t panic! Version 0.29 has come to the rescue!

**Closing the feedback loop**
-----------------------------

Now, it’s possible to choose your desired matching strategy at search time. The default strategy is `last`; if you want to use `all`, all (wink wink) you need to do is specify it in the search body as follows:

```bash
curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "peter parker", "matchingStrategy": "all" }'
```

This feature has been in the works since September 2021, when [Guillaume Mourier](https://github.com/gmourier/), our Product Manager, started the [“Policy for matching query words” discussion](https://github.com/meilisearch/product/discussions/255) to collect feedback on the matter. We would like to thank everyone involved for taking the time to share their input 🙏 Meilisearch would not exist as it does today without the support from our community 🥰

There are as many reasons to use either strategy as there are many use cases. Not sure yet which one to choose? I’ve created a demo so you can test both strategies to help you make up your mind 😊

<Callout>
  For more in-depth information on matching strategy customization, you can read the [dedicated section](https://www.meilisearch.com/docs/reference/api/search#matching-strategy) of the documentation.
</Callout>

**The demo**
------------

This demo uses the [movies dataset](https://www.meilisearch.com/movies.json), used in Meilisearch’s [quick start guide](https://www.meilisearch.com/docs/learn/getting_started/quick_start) and widely throughout the [documentation](https://www.meilisearch.com/docs).

I have made no changes whatsoever to the settings. I have simply indexed the dataset and have kept the default configuration. Pure as the driven snow ❄️

When performing a search, you can click on the button to modify the `matchingStrategy` search parameter and see the different results depending on the strategy used.

Try it here 👉 [matching-strategy.meilisearch.com](http://matching-strategy.meilisearch.com)

If you lack ideas or need some inspiration for query terms, I have listed some query ideas, ranging from 2 to 10-word queries:

*   forrest gump
*   big fat liar
*   return to never land
*   the purple rose of cairo
*   the curious incident of the dog in the night time

![When searching for "the hateful eight", Meilisearch finds 28412 results with the "last" matching strategy versus one result with the "all" matching strategy](https://unable-actionable-car.media.strapiapp.com/matching_strategy_488f3d6b7a.gif)

**Conclusion**
--------------

I hope this demo has helped you better comprehend the differences between the two strategies and their impact on search results. As usual, you can find [the code on GitHub](https://github.com/meilisearch/demos/tree/main/src/matching-strategy).

There are numerous ways of fine-tuning the relevancy of your search results. This is just one of the many options available. We know every project is different and has its own requirements; that’s why your feedback is so important to us. We work to make it easy to customize your instance so that you can deliver the best search experience to your users.

Don’t hesitate to check our [product repo](https://github.com/meilisearch/product/discussions) and make a suggestion or join an existing discussion on improving the product.

If you like Meilisearch and want to support us, a star on [GitHub](https://github.com/meilisearch/meilisearch) means a lot 😇

Are you returning the search results your users want?

<Callout>
  This tutorial was originally published in November 2021, when the latest Meilisearch version was 0.24. It has now been updated to be **compatible with Meilisearch v1.0**.
</Callout>

Introduction
------------

In this tutorial, you'll learn how to integrate Meilisearch with your Rails application database and quickly create a front-end search bar with a search-as-you-type experience using React.

We will create a very basic application; our main focus will be the search. Therefore we won't go into much detail about Rails or React.

Prerequisites
-------------

To follow this tutorial, you need:

*   [Node.js](https://nodejs.org/) >=16.10
*   [yarn](https://yarnpkg.com/) 1
*   [Ruby](https://www.ruby-lang.org) >= 2.7
*   [Ruby on Rails](https://guides.rubyonrails.org/getting_started.html#creating-a-new-rails-project-installing-rails) 7.0

Ideally, you are familiar with Ruby on Rails and have already created a simple RoR app. If that's not the case, you can still follow this tutorial, but as we stated in the introduction, explanations will focus on the search.

Step 1. Installing Meilisearch
------------------------------

There are [several ways](https://www.meilisearch.com/docs/learn/getting_started/installation#download-and-launch) to install Meilisearch. The easiest way to run a Meilisearch instance is using [Meilisearch Cloud](https://cloud.meilisearch.com/?ref=blog.meilisearch.com), there's a free 14-day trial, no credit card required. Meilisearch is open-source. In this tutorial, we'll run it locally with [cURL](https://curl.se/), a tool that allows you to make HTTP requests and transfer data from the command line.

Open your terminal and paste the following lines of code:

```bash
# Install Meilisearch
curl -L https://install.meilisearch.com | sh

# Launch Meilisearch
./meilisearch
```

Step 2. Creating and setting up your Rails app
----------------------------------------------

Now that you've got Meilisearch up and running, let's create our RoR app.‌‌ We will create a simple recipe app named `delicious_meals`. Run the following command on the terminal:

```bash
rails new delicious_meals -j esbuild
```

‌Let's generate our model `Recipe`. It will have four attributes:

1.  `title`
2.  `ingredients`
3.  `directions`
4.  `diet`

Go into the project folder and run the following command:

```bash
bin/rails g model Recipe title:string ingredients:text directions:text diet:string
```

This command also generates the migration file inside the `db/migrate` directory. Let's add the `null: false` option next to each column of the table so that no recipe is saved to the database if a field is empty.

```ruby
class CreateRecipes < ActiveRecord::Migration[7.0]
  def change
    create_table :recipes do |t|
      t.string :title, null: false
      t.text :ingredients, null: false
      t.text :directions, null: false
      t.string :diet, null: false

      t.timestamps
    end
  end
end

```

The `timestamps` column method adds two extra fields to the table: `created_at` and `updated_at`.

You can now create the database and run the migration above with the following commands:

```bash
# Creates the database 
bin/rails db:create 

# Runs the migration 
bin/rails db:migrate
```

Next, you need to generate the controller with its `index` action.

```bash
bin/rails g controller Recipes index
```

We will use the `index` view to show our recipes and search through them with our search bar. We won't generate the rest of the CRUD actions, as it would exceed the purpose of this tutorial.

Once the controller is created, modify the `config/routes.rb` file to look like this:

```ruby
Rails.application.routes.draw do
  # Maps requests to the root of the application to the index action of the 'Recipes controller'
  root "recipes#index"
end
```

Now, the `root` route is mapped to the `index` action of `RecipesController`. That way, the content of `app/views/recipes/index.html.erb` will be rendered at the root of your application.

You can check that everything is working as intended by starting the application with the following command:

```bash
bin/dev
```

Open your browser window and navigate to [`http://127.0.0.1:3000`](http://127.0.0.1:3000). You should see your index view displaying a message such as:

Recipes#index
=============

Find me in app/views/recipes/index.html.erb

Step 3. Adding Meilisearch to your app
--------------------------------------

Now that we have the back-end basics of our application, let's connect it to our running Meilisearch instance using the `meilisearch-rails` gem.

Install it by running the following command:

```ruby
bundle add meilisearch-rails
```
<Callout>
  When this tutorial was last updated, the latest version of the gem was 0.8.1. You can check the latest version in the [meilisearch-rails GitHub repository](https://github.com/meilisearch/meilisearch-rails) or on [Meilisearch finds rubygems](https://rubygems.meilisearch.com/?q=meilisearch-rails).
</Callout>

Create a file named `meilisearch.rb` inside the `config/initializers/` folder to setup your `MEILISEARCH_HOST` and `MEILISEARCH_API_KEY`:

```bash
touch config/initializers/meilisearch.rb
```

If you have followed [step 1](/blog/how-to-integrate-an-extremely-fast-and-relevant-search-into-your-rails-app-using-meilisearch-and-react/#step-1-installing-meilisearch) to the letter, your Meilisearch host should be [`http://localhost:7700`](http://localhost:7700). Since we did not set any API key, we will comment out the line with the `meilisearch_api_key` field:

```ruby
MeiliSearch::Rails.configuration = {
    meilisearch_url: 'http://localhost:7700',
    # meilisearch_api_key: ''
}
```
<Callout>
  You will need a master or a private key in production, you can learn more about it [here](https://www.meilisearch.com/docs/learn/security/master_api_keys#protecting-a-meilisearch-instance).
</Callout>

If you did set a master key, you have to update your configuration accordingly before running Meilisearch ([see step 1](/blog/how-to-integrate-an-extremely-fast-and-relevant-search-into-your-rails-app-using-meilisearch-and-react/#step-1-installing-meilisearch)et's open our `app/models/recipe.rb` file and add the following line inside the `Class` declaration:

```ruby
include MeiliSearch::Rails
```

We also need to add a `meilisearch block`. Note that the settings inside the Meilisearch block are not mandatory.

```ruby
class Recipe < ApplicationRecord
    include MeiliSearch::Rails
    
    meilisearch do
        # all attributes will be sent to Meilisearch if block is left empty
        displayed_attributes [:id, :title, :ingredients, :directions, :diet]
        searchable_attributes [:title, :ingredients, :directions, :diet]
        filterable_attributes [:diet]
    end
end

```

Let's break down each line of code:

### Setting displayed attributes

```ruby
displayed_attributes [:id, :title, :ingredients, :directions, :diet]
```

By default, Meilisearch displays all the attributes. Here, we are instructing Meilisearch to only display the specified attributes in the search response, this setting prevents Meilisearch from displaying the `created_at` and `updated_at` fields.

<Callout>
  You can learn more about `displayed attributes` in our [documentation](https://www.meilisearch.com/docs/learn/configuration/displayed_searchable_attributes#displayed-fields).
</Callout>

### Setting searchable attributes

```ruby
searchable_attributes [:title, :ingredients, :directions, :diet]
```

With the above line of code, we are doing two things:

1.  We first tell Meilisearch to only search among the specified attributes when performing a search query. So it won't try to find matches in the `id`, `created_at` and `updated_at` fields.
2.  We are also specifying the order of importance of the attributes. We are telling Meilisearch that a document with a matching query word found in its `title` is more relevant than a document with a matching query word found in `directions`. The first document is more relevant and is returned first in the search results.

<Callout>
  Learn more about `searchable fields` in our [documentation](https://www.meilisearch.com/docs/learn/configuration/displayed_searchable_attributes#searchable-fields).
</Callout>

### Setting filterable attributes

```ruby
filterable_attributes [:diet] 
```

Finally, we are telling Meilisearch that we want to be able to **refine our search results** based on the `diet` type. That will allow us to search only for vegetarian recipes, for instance.

<Callout>
  Visit our [documentation](https://www.meilisearch.com/docs/learn/advanced/filtering) to know more about filtering.
</Callout>

Step 4. Seeding the database
----------------------------

To test our application, we need some data in our database. The quickest way is to populate the database with dummy data using a gem called [_faker_](https://github.com/faker-ruby/faker)_._

Add the following line to your `Gemfile` inside the development group, save and run `bundle install`:

```ruby
gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'master' 
```

Then open the `./db/seeds.rb` file and add the following code to populate your database with 1000 recipes:

```ruby
# Deletes existing recipes, useful if you seed several times
Recipe.destroy_all

# Creates 1000 fake recipes
1000.times do
    Recipe.create!(
        title: "#{Faker::Food.dish} by #{Faker::Name.unique.name}",
        ingredients: "#{Faker::Food.ingredient}, #{Faker::Food.ingredient}, #{Faker::Food.ingredient}",
        directions: Faker::Food.description,
        diet: ['omnivore', 'pescetarian', 'vegetarian', 'vegan'].sample
    )
end 

# Displays the following message in the console once the seeding is done
puts 'Recipes created'
```

Now, run `bin/rails db:seed` in the command line.

Step 5. Testing search with the search preview
----------------------------------------------

Meilisearch delivers an out-of-the-box web interface to test it interactively. Open your browser and go to the Meilisearch HTTP address, which should be [`http://localhost:7700`](http://localhost:7700), unless you specified it otherwise [at launch](https://www.meilisearch.com/docs/learn/configuration/instance_options#http-address-port-binding).

<Callout>
  Adding documents to an index is an asynchronous operation, don't worry if you don't see the 1000 documents right away. It might take some time for the updates to process. Learn more about asynchronous updates [here](https://www.meilisearch.com/docs/learn/advanced/asynchronous_operations).
</Callout>

Make sure the `Recipe` index is selected in the menu located at the top right, next to the search bar.

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

As you can see, the data has been automatically added to our Meilisearch instance. The only visible and searchable attributes are the ones [we specified in our model file](/blog/how-to-integrate-an-extremely-fast-and-relevant-search-into-your-rails-app-using-meilisearch-and-react/#setting-displayed-attributes)nside the `meilisearch block`. Please note that your search results may be different from those shown in the GIF, since _faker_ randomly generates data.

This is great for testing Meilisearch and some of its features, but it doesn't showcase the `filterable_attributes` we specified in our block. We need a custom UI for production.

Step 6. Adding React to the Rails app
-------------------------------------

There are several ways of using ReactJS with Rails. We have chosen the most straightforward one: installing it as a JavaScript dependency in our Rails application.

Run the following command to install **ReactJS** and its **react-dom** package for working with the DOM:

```bash
yarn add react react-dom
```

Let's create the folders and files for our React code.

```bash
mkdir app/javascript/recipes 
touch app/javascript/recipes/index.jsx 
touch app/javascript/recipes/App.jsx
```

Let's open `app/javascript/recipes/index.jsx` and add the required code to render our React elements:

```jsx
import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

const container = document.getElementById('app');
const root = createRoot(container); 
root.render(<App/>);

```

Open the `app/javascript/application.js` and import the file we just created:

```JavaScript
import "./recipes"
```

Step 7. Integrating a front-end search bar
------------------------------------------

To integrate a front-end search bar, you need to install two packages:

*   **[React InstantSearch](https://github.com/algolia/react-instantsearch)**: an open-source library that provides all the front-end tools you need to customize your search bar environment
*   **[Instant Meilisearch](https://github.com/meilisearch/meilisearch-js-plugins/tree/main/packages/instant-meilisearch)**: the Meilisearch client to establish the communication between your Meilisearch instance and the React InstantSearch library

```bash
yarn add react-instantsearch-dom @meilisearch/instant-meilisearch
```

You can now open your `app/javascript/recipes/App.jsx` file and replace the existing code with the code from the `meilisearch-react` [Getting Started](https://github.com/meilisearch/meilisearch-react/#getting-started) guide. We only need to modify the `searchClient` with our Meilisearch host and Meilisearch API key, as well as the `indexName`. It should look like this:

```jsx
import React from "react"
import { InstantSearch, Highlight, SearchBox, Hits } from 'react-instantsearch-dom';
import { instantMeiliSearch } from '@meilisearch/instant-meilisearch';

const searchClient = instantMeiliSearch(
  "http://localhost:7700", // Your Meilisearch host
  "" // Your Meilisearch API key, if you have set one
);

const App = () => (
  <InstantSearch
    indexName="Recipe" // Change your index name here
    searchClient={searchClient}
  >
    <SearchBox />
    <Hits hitComponent={Hit} />
  </InstantSearch>
);

const Hit = ({ hit }) => <Highlight attribute="title" hit={hit} />

export default App
```

Now, go to your `views` folder and replace the content of the `app/views/recipes/index.html.erb` with the code below:

```html
<div id="app"></div>
```

Now you can run the `bin/dev` command, open your browser and navigate to [`http://127.0.0.1:3000`](http://127.0.0.1:3000) and see the result:‌

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

Well, the search works, but it's not very pretty. Luckily, InstantSearch provides a [CSS theme](https://www.algolia.com/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react/#loading-the-theme) you can add by inserting the following link into the `<head>` element of your `app/views/layouts/application.html.erb`:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@7.4.5/themes/satellite-min.css" integrity="sha256-TehzF/2QvNKhGQrrNpoOb2Ck4iGZ1J/DI4pkd2oUsBc=" crossorigin="anonymous">
```

You can also customize the widgets or create your own if you want to. Check the [React InstantSearch documentation](https://www.algolia.com/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react/) for more details.

Let's check the rendering:

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

Not bad, right? But once again we lack the possibility of filtering the results by type of diet.

Step 8. Adding faceted search
-----------------------------

It's as simple as importing the `RefinementList` widget in your `App.jsx` file:

```jsx
import { InstantSearch, Highlight, SearchBox, Hits, RefinementList } from 'react-instantsearch-dom';
```

and adding it inside our `InstantSearch` widget, specifying the attribute we want to filter by:

```jsx
<RefinementList attribute="diet" />
```

To make it more aesthetic and practical, let's create two `<div>` elements to divide our components. On the left, we'll find the filters, and the search bar and results on the right.

You can also add a "Type of diet" heading along with the `ClearRefinements` widget. It allows you to clear all the filters just by clicking on it, instead of having to uncheck them one by one.

The file should now look like this:

```jsx
import React from "react"
import { InstantSearch, Highlight, SearchBox, Hits, RefinementList, ClearRefinements } from 'react-instantsearch-dom';
import { instantMeiliSearch } from '@meilisearch/instant-meilisearch';

const searchClient = instantMeiliSearch(
  "http://localhost:7700",
  ""
);

const App = () => (
  <InstantSearch
    indexName="Recipe" // Change your index name here
    searchClient={searchClient}
  >
    <div className="left-panel">
      <ClearRefinements />
      <h2>Type of diet</h2>
      <RefinementList attribute="diet" />
    </div>
    <div className="right-panel">
      <SearchBox />
      <Hits hitComponent={Hit} />
    </div>

  </InstantSearch>
);

const Hit = ({ hit }) => <Highlight attribute="title" hit={hit} />

export default App


```

For this to work we need to add some CSS. Let's create a `app/assets/stylesheets/recipes.css` file and add the following lines of code:

```css
.right-panel {
    margin-left: 210px;
}
  
.left-panel {
    float: left;
    width: 200px;
}
```

And just to make it even prettier, let's add some padding and margin to the body and the search bar, and change the font:

```json
/* app/assets/stylesheets/recipes.css */

body { 
    font-family: sans-serif; 
    padding: 1em; 
}

.ais-SearchBox { 
    margin: 1em 0; 
}

.right-panel {
    margin-left: 210px;
}

.left-panel {
    float: left;
    width: 200px;
}
```

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

And tada! 🎉  You have a nice search bar with a search-as-you-type experience ready! 🥳

⚠️ Because we used fake data to seed our database, the recipes' `title`s, `ingredients`, `directions`, and `diet` type are not necessarily consistent.

### Conclusion

We have learned how to synchronize our Ruby on Rails database with Meilisearch and customize our search settings directly on our Rails app, allowing us to search through our data in milliseconds. To top it all off, we have also created a faceted search interface with a search-as-you-type experience using React.

We have achieved all this seamlessly, thanks to [Meilisearch Rails](https://github.com/meilisearch/meilisearch-rails) and [Instant Meilisearch](https://github.com/meilisearch/meilisearch-js-plugins/tree/main/packages/instant-meilisearch). Meilisearch has integrations for almost every popular language or framework. Take a look at the complete list in the [Meilisearch integration guides](https://github.com/meilisearch/integration-guides/).

If you have any questions, please join us on [Discord](https://discord.gg/meilisearch); we are always happy to hear from you. For more information on Meilisearch, check out our [Github repository](https://github.com/meilisearch/meilisearch/) and [official documentation](https://www.meilisearch.com/docs/).

How to integrate an extremely fast and relevant search into your Rails app using Meilisearch and React

**Introduction**
----------------

If there's one feature Firebase is missing, it’s a good and efficient way for searching through data. Their [documentation](https://firebase.google.com/docs/firestore/solutions/search) suggests using a third-party solution:

> "Cloud Firestore doesn't support native indexing or search for text fields in documents. \[…\] To enable full-text search of your Cloud Firestore data, use a dedicated third-party search service."

[Firestore-meilisearch](https://github.com/meilisearch/firestore-meilisearch), Meilisearch’s official Firebase extension, synchronizes documents between a Cloud Firestore collection and a Meilisearch index, monitoring each time you create, update, or remove documents from that index. This ensures the data in Meilisearch mirrors your content in Cloud Firestore, effectively enabling you to create a fully-featured search experience.

In this tutorial, we'll show you how to install the `firestore-meilisearch` extension on your Firebase instance and add full-text search to your Cloud Firestore.

Tools
-----

*   **Firebase:** Firebase is a platform developed by Google to help developers create mobile and web applications. It is a fully managed back-end service that provides an infrastructure for web applications that handles everything from user authentication and server scaling to crash analytics and reliable testing environments.
*   **Meilisearch:** Meilisearch is a fast, open-source search engine that's a joy to use and deploy. Meilisearch allows you to create a relevant search experience out of the box in very few steps and with no configuration needed.

**Requirements**
----------------

**To run this project, you will need:**

*   A Google account with a billing profile set up
*   An open [terminal or command prompt](https://www.ionos.com/help/email/troubleshooting-mail-basicmail-business/access-the-command-prompt-or-terminal)
*   [Node.js](https://nodejs.org/en/download/) {">= 14 && <= 17"}
*   [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) >= v7

**Steps**
---------

Here's a summary of what we're going to do to create a nice search interface with Firebase and Meilisearch:

1.  Deploy Meilisearch
2.  Create a Firebase project
3.  Install Meilisearch’s Firebase extension
4.  Set up a search interface

**Deploy Meilisearch**
----------------------

For this tutorial, you will need a Meilisearch instance running on a cloud service. There are many ways [to deploy a Meilisearch instance](https://docs.meilisearch.com/learn/getting_started/quick_start.html#cloud-deploy). The easiest way to spawn a Meilisearch instance is using [Meilisearch Cloud](https://cloud.meilisearch.com/login), there's a free 14-day trial, no credit card required.

**Create Firebase project**
---------------------------

**Note:** you can skip this step if you already have a Firebase Project with a Firestore Database containing your documents.

Once we have our Meilisearch instance up and running, we can create a Firebase project, configure it, and add a Firestore database.

### Create **a project**

Follow the [Firebase documentation](https://firebase.google.com/docs/web/setup#create-project) to start your own project.

You should now have a project on your Firebase account that looks a bit like this:

![A look at a fresh new Firebase account settings](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_04_at_15_24_56_1_491fb374a2.png)

Once we have created a Firebase account and our project, we will need to add a Firestore Database to our project. Consult [Firebase’s documentation](https://firebase.google.com/docs/firestore/quickstart) for more instructions.

**Install Meilisearch extension**
---------------------------------

We now are ready to install the Meilisearch extension on our project.

### ⚠️  **Billing**

To install an extension, [your Firebase project must be on a special billing plan](https://github.com/meilisearch/firestore-meilisearch#billing) that will charge you at least 1 cent a month.

### Install and authorize `firestore-meilisearch`

To install the [`firestore-meilisearch`](https://github.com/meilisearch/firestore-meilisearch) extension on your Firebase project just follow this [link that will redirect you to your Firebase console](https://console.firebase.google.com/project/_/extensions/install?ref=meilisearch%2Ffirestore-meilisearch@0.1.3).

Select the project in which you want to install the extension. You will then have access to the installation panel. The panel consists of three main steps, with a final extension configuration section at the end:

1.  **Early Access Partner extension:** find `firestore-meilisearch` under Extensions Publisher Early Access Program, select it, and click on “Next”
2.  **Review billing and usage:** Firebase will inform you about the charges incurred by using extensions, which we recommend you read carefully. If Firebase offers the option, click on “Update project to continue;” otherwise, click on “Next”
3.  **Review APIs enabled and resources created:** Firebase will also give you more information about [Cloud Functions](https://firebase.google.com/docs/functions), a set of Firebase functionality we use in this extension. These instructions explain how Cloud Functions are triggered and their key capabilities

### **Configure `firestore-meilisearch`**

The fourth and final step for activating `firestore-meilisearch` is configuring it.

![Configuring the Meilisearch extension in Firebase](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_04_at_13_57_34_8e12fb4018.png)

1.  **Cloud Functions location:** select the region where the backend code will be called whenever a document is added, updated, or deleted from Firestore. We recommend selecting regions close to your users and your Meilisearch instance
2.  **Collection path:** the name of the Firestore collection you want to mirror in a Meilisearch index
3.  **Fields to index in Meilisearch (Optional):** optional setting gives you the possibility to only index some of the fields in the documents contained in your Firestore database
4.  **Meilisearch Index Name:** the name of the Meilisearch index containing your Firestore data. Meilisearch will automatically created this index if it doesn’t exist
5.  **Meilisearch host:** the URL of your Meilisearch instance
6.  **Meilisearch API key (Optional):** a Meilisearch API key with permission to perform actions on indexes. For more info on API keys, consult our [security guide](https://docs.meilisearch.com/learn/security/master_api_keys.html).

You can also install this extension via the command line. To do so, make sure you've got the [Firebase Command-Line tools installed](https://firebase.google.com/docs/cli), then run the following command:

```bash
firebase ext:install meilisearch/firestore-meilisearch --project=(your project ID)

```

### Check if everything is working!

Suppose we are creating an application that allows users to search through a database of movies. Our first step is to create a collection named `movies` in Firestore:

![Starting a collection on Firebase](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_21_at_18_49_25_c4de0afa47.png)

We can use Firestore Database’s access panel to manually add a movie document:

![Adding a document to Firebase](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_21_at_12_50_35_1_d5f5577498.png)

This is the data we are using in our example:

```raw
title
    The Hobbit: An Unexpected Journey

poster
    <https://image.tmdb.org/t/p/w500/yHA9Fc37VmpUA5UncTxxo3rTGVA.jpg>

overview
    Bilbo Baggins, a hobbit enjoying his quiet life, is swept into an epic quest by Gandalf the Grey and thirteen dwarves who seek to reclaim their mountain home from Smaug, the dragon.

release_date
    1353888000
```

Once you added this movie, you should be able to see it when accessing your instance’s [search preview](https://www.meilisearch.com/docs/learn/what_is_meilisearch/search_preview):

![Search preview of Meilisearch with a first document](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_21_at_12_51_45_2_7a422f3d42.png)

**Well done! You have successfully installed the Meilisearch Firestore extension!**

From now on, whenever you add, update, and delete documents from your Firestore collection they will be mirrored in the same way in your Meilisearch instance.

<Callout>
  This extension does not export all existing documents in Meilisearch unless they have been modified or created after its installation. You can run the import script provided by this extension to retrieve your dataset in Meilisearch with all documents present in your Firestore collection. For more information, check the [dedicated guide](https://github.com/meilisearch/firestore-meilisearch/blob/main/guides/IMPORT_EXISTING_DOCUMENTS.md) in our `firestore-meilisearch` repository.
</Callout>

### Managing your extension

To access the overview panel of the extension, first click on the “Extensions” tab on Firebase’s sidebar menu, then find the Meilisearch extension and click on “Manage.”

![Finding the Extensions tab in Firebase](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_04_at_18_42_52_58b56d1e77.png)

![Finding the Manage settings of meilisearch extension](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_04_at_18_29_51_1_c0cfafa489.png)

You will be directed to a page where you can access all the information about your extension, change its configuration, or even delete it.

![Configuring the Meilisearch extension for Firebase](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_04_at_18_30_06_e35e907ca8.png)

Accessing your logs allows you to monitor your cloud functions and obtain different levels of information. You may access an extension’s logs via the “Extensions” tab. Alternatively, you can also visit the “Functions” tab, then select “Logs,” as indicated in the image below.

![Finding the Functions tab in Firebase](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_04_at_18_34_39_3eee0c3654.png)

![Finding the Logs tab in the Function menu of Firebase](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_04_at_18_34_23_a40c6dba99.png)

![Looking at the logs to monitor Cloud Functions](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_04_at_18_33_57_561839c8a6.png)

![Isolating an interesting log of our Firebase extension](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_05_at_16_13_16_358ff97a54.png)

Set up a search interface
-------------------------

We are done with installing and configuring the `firestore-meilisearch` extension, but it's no fun if we don't get to try the search in an actual front-end application. In this optional part, we will see how to create a search bar for your project using [instant-meilisearch](https://github.com/meilisearch/meilisearch-js-plugins/tree/main/packages/instant-meilisearch).

### **Populating your Firestore collection with data**

The first thing we need to do is add more documents to our Firestore database. In our case, we are going to use this [collection of movies](https://www.meilisearch.com/movies.json). Consult Firebase documentation for more information on [how to add and manage data](https://firebase.google.com/docs/firestore/manage-data/add-data).

Once you are finished adding content to your Firestore database, visit your instance’s [search preview](https://www.meilisearch.com/docs/learn/what_is_meilisearch/search_preview) to check your documents have been successfully indexed by Meilisearch.

![Search preview of the Firestore database](https://unable-actionable-car.media.strapiapp.com/Screenshot_2022_04_04_at_18_10_11_4e741a00b9.png)

### **Search in your document**

Now let's create a great search experience! There are many ways to do this, but we’ll keep it simple this time and use `instant-meilisearch`, our plugin for the `instant-search` JavaScript library. Read our article on [instant-meilisearch](/blog/instant-meilisearch/)o learn more.

Create an`index.html`file in your preferred development environment. This HTML page should contain a search bar and a box to contain the returned search results:

```bash
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Meilisearch demo</title>
    <link rel="stylesheet" href="<https://cdn.jsdelivr.net/npm/instantsearch.css/themes/algolia-min.css>" />
</head>
<body>
    <div>
        <div id="searchbox"></div>
        <div id="hits"></div>
      </div>
  
      <script src="<https://cdn.jsdelivr.net/npm/@meilisearch/instant-meilisearch/dist/instant-meilisearch.umd.min.js>"></script>
      <script src="<https://cdn.jsdelivr.net/npm/instantsearch.js@4>"></script>
      <script>
          const searchClient = instantMeiliSearch(
              'your Meilisearch url',
              'your Meilisearch API key'
            )
            const search = instantsearch({
              indexName: 'movies',
              searchClient
            })

            search.addWidgets([
              instantsearch.widgets.searchBox({
                container: '#searchbox',
              }),
              instantsearch.widgets.hits({
                container: '#hits',
                templates: {
                  item: `
                    <div style="text-align:center;">
                      <div class="hit-name">
                        {{#helpers.highlight}}{ "attribute": "title" }{{/helpers.highlight}}
                      </div>
                      </br>
                      <div>
                        <img src="{{poster}}" width="200px" />
                      </div>
                    </div>
                  `,
                },
              }),
            ])

            search.start()
      </script>
</body>
</html>

```

Don’t forget to replace the example’s configuration with your own data. This might include the `indexName`, if you named your index something other than `movies`, your instance’s URL, and your API key.

If everything went well, you should be able to access your `index.html` file and start searching right away:

![Showing how the search functionality works](https://unable-actionable-car.media.strapiapp.com/Apr_05_2022_12_55_55_66890e7900.gif)

**Congrats!** You have added full-text search capability to your Cloud Firestore. Your Firebase collection and your Meilisearch index will automatically stay in sync as long as the `firestore-meilisearch` extension is installed.

Thanks for following this little tutorial! Questions, comments, suggestions? Don't hesitate to [get in touch with us on GitHub](https://github.com/meilisearch/firestore-meilisearch)—trust us, we love your feedback.

Create a search interface with Firebase and Meilisearch

Oyez, oyez! A new version of Meilisearch is out and brings you a bunch of cool new features including a long-requested one: typo tolerance customization!

We have been receiving feedback from users on wanting to disable or fine-tune typo tolerance for some time. Meilisearch v0.21 introduced phrase search, which returns documents containing the exact query terms if they are enclosed within double-quotes like: `“african-american poet”`.

It was a big step towards meeting our users’ needs, but it was not enough. After carefully studying the matter, the time has come: **the customization of typo tolerance** is a reality 🎉

But hang on, what does custom typo tolerance really mean? And even more important, what does typo tolerance mean?

The good old default behavior
-----------------------------

Meilisearch is typo tolerant, meaning it understands your search even if there are typos. But with great power comes great responsibility, which means setting boundaries to keep results relevant. This translates into the following three rules:

1.  No typo is allowed if the query word is less than 5 characters long
2.  Only 1 typo is allowed if the query word is between 5 and 8 characters long
3.  2 typos are allowed if the query word is more than 8 characters long

So if you are looking for `lost` but accidentally type `last`, you wouldn't get the desired result because it’s 4 characters long.

But, typing `greeec`instead of `greece` would retrieve the expected documents because it’s 6 characters long, so one typo is allowed.

These rules are applied by default and are part of the out-of-the-box configuration of Meilisearch, providing a powerful and relevant search. Yet, as they say, rules are meant to be broken...

Customization: a new horizon of possibilities
---------------------------------------------

We know every project is different, and some users need to configure typo tolerance to suit their projects’ particularities. We hear you!

Let’s take a look at the new typo tolerance settings:

```json
"typoTolerance": {
    "enabled": true, 
    "minWordSizeForTypos": {
        "oneTypo": 5,
        "twoTypos": 10
    },
    "disableOnWords": [],
    "disableOnAttributes": []
}

```

Looking at the `typoTolerance` object above, you can now:

*   Disable typo tolerance entirely by setting `"enabled": false` 😱
*   Disable typo tolerance partially on a set of specific terms using `"disableOnWords"`
*   Disable typo tolerance on desired document attributes `"disableOnAttributes"`

You can also fine-tune the typo tolerance settings by modifying the minimum size of a word to accept one or two typos.

In sum, you have complete control of the feature.

<Callout>
  For more in-depth information on typo tolerance customization, you can read the [dedicated section](https://docs.meilisearch.com/learn/configuration/typo_tolerance.html) of the documentation.
</Callout>

Try it out and see
------------------

They say a picture is worth a thousand words (I can't stop with the catchphrases, sorry); that’s why I’ve created a demo to show how different typo tolerance configurations can impact the returned search results. **You can test it [here](https://typo-tolerance.meilisearch.com/).**

We will be using [Hakan Özler](https://github.com/ozlerhakan)'s [dataset of books](https://github.com/ozlerhakan/mongodb-json-files/blob/master/datasets/books.json). I made some changes to the original dataset for demo purposes, you can find the [transformed dataset](https://github.com/meilisearch/demos/blob/main/src/typo-tolerance/setup/books.json) on GitHub. You can search a book by its title, [ISBN](https://en.wikipedia.org/wiki/ISBN) (the ID of the book), author, or by the words in its description.

I have created two identical indexes with different typo tolerance settings. One index uses the out-of-the-box typo tolerance settings, whereas the other uses the following:

```JavaScript
const customTypoTolerance = {
    disableOnAttributes: ['isbn'],
    minWordSizeForTypos: {
        oneTypo: 2,
        twoTypos: 4
    }
}
```

Typo tolerance is disabled on `isbn`, and typos are allowed on shorter words: one typo for words that are 2 and 3 characters long, two typos for any longer word.

![Meilisearch returns different search results depending on the typo tolerance configuration for the same query](https://unable-actionable-car.media.strapiapp.com/typo_tolerance_1_gif_c23f105edf.gif)

It's usually better to provide the end-user with some results than with none. That’s why I set the threshold to the [minimum recommended](https://docs.meilisearch.com/learn/configuration/typo_tolerance.html#minwordsizefortypos). Try typing `flx` and see what happens!

Sometimes, however, it is preferable to return only exact matches. For example when searching documents by their unique identifier. The ISBN is precisely that: the ID of a book. Therefore, I disabled the typo tolerance on the `isbn` attribute.

Let’s try to find a book called “Well-Grounded Rubyist” by its ISBN; type `1933988657` into the search bar.

![When searching for an ISBN, Meilisearch returns only one document when typo tolerance has been disabled on the isbn field](https://unable-actionable-car.media.strapiapp.com/typo_tolerance_2_gif_0119353162.gif)

As you can see, we get the desired book with both settings. However, we get more than one result when typo tolerance is enabled. Searching for an invalid ISBN like `1933988676` still returns results when typo tolerance is enabled; this can be confusing and misleading.

Conclusion
----------

I didn’t disable the typo tolerance on any word because I did not deem it necessary given this dataset, did you? If you want to make some modifications and try to get more relevant results, be my guest: you can find [the code on GitHub](https://github.com/meilisearch/demos/tree/main/src/typo-tolerance).

But, if you like real challenges, I've got one for you. [Literal](https://literal.club/), an online platform for book readers, uses Meilisearch to search through bookshelves. They have been kind enough to share the recipe they've been using to deliver relevant search results:

```json
{
   "displayedAttributes":[
      "id",
      "title",
      "workId",
      "authors",
      "categories",
      "popularity"
   ],
   "searchableAttributes":[
      "authors",
      "title",
      "categories"
   ],
   "filterableAttributes":[
      "isbn10",
      "isbn13",
      "language"
   ],
   "distinctAttribute":"workId",
   "rankingRules":[
      "words",
      "typo",
      "popularity:desc",
      "proximity",
      "attribute",
      "sort",
      "exactness"
   ]
}

```

Can you come up with a better configuration? Can you think of the perfect typo tolerance settings to enhance the relevancy?

As you may have noticed, we take user feedback very seriously. Please don’t hesitate to check our [public roadmap](https://roadmap.meilisearch.com/) and upvote for any feature you'd like to see in future versions or submit a new feature idea. You can also check our [product repo](https://github.com/meilisearch/product/discussions) and make a suggestion or join an existing discussion on improving the product.

If you like Meilisearch and want to support us, a star on [GitHub](https://github.com/meilisearch/meilisearch) means a lot 🥰

Meilisearch latest news and company updates