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](__GHOST_URL__/author/riccardo/). At the time, Meilisearch was on v0.09. It has been updated by [Carolina Ferreira](__GHOST_URL__/author/carolina/) to 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](__GHOST_URL__/instant-search-react-app/#getting-started) section.

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](__GHOST_URL__/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](__GHOST_URL__/how-to-integrate-an-extremely-fast-and-relevant-search-into-your-rails-app-using-meilisearch-and-react/#step-1-installing-meilisearch)).

Let'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](__GHOST_URL__/how-to-integrate-an-extremely-fast-and-relevant-search-into-your-rails-app-using-meilisearch-and-react/#setting-displayed-attributes) inside 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](__GHOST_URL__/instant-meilisearch/) to 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 🥰

Take control of Meilisearch's typo tolerance

This tutorial will show you how to integrate Meilisearch with Strapi v4 to create a search-based web app. We are going to use Strapi’s quick start guide to create a restaurant collection, and then use Meilisearch to search through our collection data.

Introducing our tools
---------------------

### What is Strapi?

[Strapi](https://strapi.io/) is a headless CMS. It provides a quick way to create a back-end where we can add and store data. The data is then available through a REST or GraphQL API without having to code anything or configure our database.

### What is Meilisearch?

[Meilisearch](https://www.meilisearch.com/docs/learn/what_is_meilisearch/overview#what-is-meilisearch) is a fast, open-source search engine that's easy to use and deploy. The aim of Meilisearch is to create an out-of-the-box relevant search experience in very few steps, with no configuration needed.

Pre-requisites for integrating Meilisearch and Strapi
-----------------------------------------------------

To be able to follow this tutorial on Strapi and Meilisearch integration, you'll need the following:

*   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 <= 18"}
*   NPM and NPX (v6 only) (installed with Node.js): package managers that help you access and use JS libraries

Create a directory for our app
------------------------------

Let’s create a directory called `my-app` where we will add our back and front-end parts of the application.

```bash
mkdir my-app
cd my-app

```

Create a back-end using Strapi
------------------------------

Our first step is to generate a back-end API using Strapi. Go to your open terminal window and run the following command:

```bash
npx create-strapi-app@latest back --quickstart

```

This command creates a Strapi app in a new directory called `back` and opens the admin dashboard. Create an account or log in so that you have access to it.

![Strapi signup form](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2022_04_08_a_11_27_18_1_3e4dd92cf4.png)

Once you have created your account, you should be redirected to Strapi's admin dashboard. This is where we will configure our back-end API.

Our next step is to create a new collection type. A collection is like a blueprint of your content—in this case, it'll be a collection of restaurants. We will create another collection called "Category" to organize our restaurants later.

![Strapi dashboard with side menu 'Content-Type Builder' option circled](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2022_04_08_a_11_34_17_2_1_2b9259cf7e.png)

To follow along, complete the first 4 steps of "Part B: Build your content" from [Strapi's quick start guide](https://docs.strapi.io/developer-docs/latest/getting-started/quick-start.html). These will include:

*   creating collection types
*   creating new entries
*   setting roles & permissions
*   publishing the content

After finishing step 4 of Strapi's quick start guide, two new collections named `Restaurant` and `Category` should have appeared under `Content Manager` > `Collection Types`. If we click on `Restaurant`, we can see that there is only one. Let's add more by clicking the `+ Create new entry` button in the upper-right corner of the dashboard!

![Strapi dashboard: Content manager side menu, arrow indicating the location of the Restaurant Collection Type ](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2022_04_08_a_18_27_41_copie_1_1_70c8af5070.png)

We’ll add three restaurants, one by one. For each restaurant, you need to press `Save` and then `Publish`.

*   Name: `The Butter Biscotte.` Description: `All about butter, nothing about health.`  
    Let’s add the `French food` category on the bottom right corner of the page 👇

![Strapi dashboard: create an entry form, arrow indicating the location of the categorie's location in the right side menu](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2022_04_08_a_18_33_44_2_9695c0fc90.png)

Name: `The Slimy Snail` Description: `Gastronomy is made of garlic and butter.` Category: `French food`

Name: `The Smell of Blue` Description: `Blue Cheese is not expired, it is how you eat it. With a bit of butter and a lot of happiness.` Category: `French food`

Once the three restaurants have been added, you should end up with the following page:

![Strapi dashboard: list of the existing restaurant entries in the Restaurant Collection Type page](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2022_04_08_a_18_42_35_1_0d0b1abef2.png)

Our Strapi back-end is now up and running! Strapi automatically creates a REST API for our `Restaurants` collection. Check out Strapi's documentation for all available [API endpoints](https://strapi.io/documentation/developer-docs/latest/developer-resources/content-api/content-api.html#api-endpoints).

Now, it's time to bring Meilisearch into the mix.

Install and launch Meilisearch
------------------------------

To integrate Meilisearch into our Strapi-based web app, you first need to install Meilisearch. There are multiple ways to [download and run a Meilisearch instance](https://www.meilisearch.com/docs/learn/getting_started/installation#download-and-launch), we will be using [Docker](https://www.docker.com/) here.

If you want to avoid a local installation, **[try Meilisearch Cloud](https://www.meilisearch.com/pricing)**, a hosted and fully‑managed version of Meilisearch with a **free** 14-day trial, **no credit card required**.

**Open a second terminal window** and move to the `my-app` directory. This window will be used to run Meilisearch. Execute the command below to download and [install Meilisearch with Docker](https://www.meilisearch.com/docs/learn/cookbooks/docker). If Docker doesn't work for you, consider trying one of the [many other methods](https://www.meilisearch.com/docs/learn/getting_started/installation#download-and-launch).

```bash
# Fetch the latest version of Meilisearch image from DockerHub
docker pull getmeili/meilisearch:latest

# Launch Meilisearch
docker run -it --rm \
    -p 7700:7700 \
    -e MEILI_ENV='development' \
    -v $(pwd)/meili_data:/meili_data \
    getmeili/meilisearch:latest

```

You should see a big chunk of text (including some ASCII art) confirming that Meilisearch is up and running.

![Meilisearch startup message, arrow pointing the location of the address](https://unable-actionable-car.media.strapiapp.com/Screenshot_2023_02_23_at_15_02_41_e904f789b5.png)

Find the line titled `Server listening on`. This lets us know where Meilisearch is being served. Once you've found it, open this address in your browser.

![Meilisearch search preview, aka, mini-dashboard](https://unable-actionable-car.media.strapiapp.com/Screenshot_2023_02_23_at_15_08_38_b0c8b8b2a8.png)

This is the Meilisearch [search preview](https://www.meilisearch.com/docs/learn/what_is_meilisearch/search_preview). It will remain empty until we add some data to our Meilisearch instance.

It’s time to connect Strapi and Meilisearch and start searching through our data.

Connect Strapi and Meilisearch
------------------------------

In order to add the Meilisearch plugin to Strapi, we need to quit our Strapi app. Go to the terminal window running Strapi (_make sure it's not the one running Meilisearch!_) and push `Ctrl+C` to kill the process.

Once you've done that, install the plugin in the `back` directory.

```json
cd back
npm install strapi-plugin-meilisearch

```

After the installation, we have to rebuild our Strapi app before starting it again in development mode, since it makes configuration easier.

```json
npm run build
npm run develop

```

At this point, our Strapi app should be running once again on the default address: [http://localhost:1337/admin/](http://localhost:1337/admin/). Visiting it in your browser, you should see an admin sign-in page; enter the same credentials as before.

Once connected, you should see the new `meilisearch` plugin on the left side of the screen.

![Strapi dashboard with plugins side menu: arrow pointing at the 'meilisearch' option](https://unable-actionable-car.media.strapiapp.com/Capture_d_e_cran_2022_04_08_a_19_01_53_1_a30c95c406.png)

To add your Meilisearch credentials, click on the `Settings` tab on the meilisearch plugin page so that Strapi knows where to send our data.

For example, using the credentials from the **Launch and start Meilisearch** section above, add the address serving Meilisearch in the `Meilisearch Host` field, then click the `Save` button.

![Strapi dashboard with Meilisearch plugin selected: arrow pointing to the location of the settings tab](https://unable-actionable-car.media.strapiapp.com/Screenshot_2023_02_23_at_15_30_11_c882741ba9.png)

Note that we leave `Meilisearch API Key` blank because we launched Meilisearch without a [master key](https://www.meilisearch.com/docs/learn/configuration/instance_options#master-key).

Now it's time to add your Strapi collection to Meilisearch. In the `Collections` tab on the `meilisearch` plugin page, you should see the `restaurant` and `category` content-types.

By clicking on the checkbox next to `restaurant`, the content-type is automatically indexed in Meilisearch.

![GIF showing the mouse clicking on 'restaurant' in the Meilisearch collections tab](https://unable-actionable-car.media.strapiapp.com/strapi_gif_ce383289e9.gif)

As you can see in the GIF above, the word “Hooked” appears when you click on the restaurant's checkbox in the `Collections` tab. This means that each time you add, update or delete an entry in your restaurant content-types, Meilisearch is automatically updated!

Once the indexing finishes, your restaurants are in Meilisearch. We can now go back to our Meilisearch host address: [http://localhost:7700](http://localhost:7700). After refreshing, you should observe that the page is no longer empty. Try typing “butter” in the search bar and see what happens 😉

![GIF showing the word 'butter' being typed in the search bar and search results appearing instantly](https://unable-actionable-car.media.strapiapp.com/butter_1_72fa85eb2f.gif)

As you can see, your Strapi entries are sent to Meilisearch as is. You can modify the data before sending it to Meilisearch, for instance by removing a field. Check out all the customization options on the [strapi-plugin-meilisearch](https://github.com/meilisearch/strapi-plugin-meilisearch/#-customization) page.

Next steps after integrating Strapi and Meilisearch
---------------------------------------------------

Now that you have successfully added your Strapi collections in Meilisearch, you can start using the [search capabilities](https://www.meilisearch.com/docs/learn/what_is_meilisearch/overview#features) to their full extent.

Learn how to [set up instant-meilisearch](__GHOST_URL__/instant-meilisearch/) to integrate a search-as-you-type experience into your front end in no time at all!

If you have any questions about integrating Meilisearch with Strapi, please join us on [Discord](https://discord.gg/meilisearch). If you like Meilisearch, [a star on GitHub](https://github.com/meilisearch/meilisearch) means a lot.

How to integrate a relevant search into Strapi v4 using Meilisearch

### ****What is multitenancy?****

In software development, multitenancy means that multiple users - also called tenants - share the same computing resources but have different access to system-wide data. In Meilisearch, you might have one index containing data belonging to many distinct tenants. In such cases, your tenants must only be able to search through their own documents.

You can achieve this using tenant tokens.

### **Tenant Token**

Tenant tokens are small packages of encrypted data presenting proof a user can access a certain index. They contain security credentials and instructions on which documents within that index the user is allowed to see.

The primary use case for tenant tokens is to enforce restrictions based on user permissions.

A user can generate a tenant token using [Meilisearch SDKs](https://docs.meilisearch.com/learn/security/tenant_tokens.html#generating-tenant-tokens-with-an-sdk) or [custom code](https://docs.meilisearch.com/learn/security/tenant_tokens.html#generating-tenant-tokens-without-a-meilisearch-sdk).

**Tenant tokens** do not require you to configure any specific instance options or index settings. They are also meant to be short-lived—Meilisearch does not store nor keep track of generated tokens.

When using an SDK to generate a tenant token, you need four parameters:

*   **Search rules**: Search rules are a set of instructions defining search parameters that will be enforced in every query made with a specific tenant token.
*   **API key**: A token has access to the same indexes as the API key used to generate it.
*   **API key uid**: The uid of the API key used to generate the token allows checking that the API key used is valid.
*   **Expiration date**(optional): The expiration date of the tenant token

You can read more about the tenant token payload in the [documentation](https://docs.meilisearch.com/learn/security/tenant_tokens.html#tenant-token-payload-reference).

### ****Requirements****

1.  [Node.js](https://nodejs.org/en/download/)
2.  [npm](https://www.npmjs.com/)
3.  [Meilisearch JavaScript SDK](https://github.com/meilisearch/meilisearch-js)

### ****Creating a tenant token****

A **tenant token** can be created using the `generateTenantToken` function available in the Meilisearch Javascript SDK.

Here’s a simple example for creating a **tenant token** using the Meilisearch SDK

```jsx
client = new Meilisearch({
	host: "<http://localhost:7700>",
	apiKey: "masterKey"
})
// We have created a Meilisearch instance in JavaScript and we will use this to create the tenant token. 

const apiKey = 'rkDxFUHd02193e120218f72cc51a9db62729fdb4003e271f960d1631b54f3426fa8b2595';
const apiKeyUid = '85c3c2f9-bdd6-41f1-abd8-11fcf80e0f76'
const expiresAt = new Date("2025-01-01")
// Now we have declared the API Key, its uid, as well as the expiration date for the token. 

searchRules = {
	"*": {
		"filter": "user_id = 1"
	}
}
// Here we have defined the search rules that will apply restrictions on the search results. 

tenantToken = client.generateTenantToken(apiKeyUid, searchRules, {
	expiresAt: expiresAt,
	apiKey: apiKey,
})
// Now the generateTenantToken function will create a tenant token and Meilisearch can validate this token with the apiKey.

```

When Meilisearch gets a search query with a tenant token, it decodes it and applies the search rules to the search request.

### **Application Usage**

Let's say we have a medical record system in a Meilisearch instance with the `patient_medical_record` index. This index contains a list of patients along with their details. We can use tenant tokens to restrict access to this data.

Sample dataset:

```json
[
	{
	    "patient": "John",
	    "description": "John is in room number 2 and is suffering from Covid",
	    "roomNumber": 1,
	    "isDoctorAppointed": true
	},
	{
	    "patient": "Zia",
	    "description": "Zia is in room number 3 and is suffering from Dengue",
	    "roomNumber": 2,
	    "isDoctorAppointed": true
	},
	{
	    "patient": "Kevin",
	    "description": "Kevin is in room number 4 and is suffering from Typhoid",
	    "roomNumber": 3,
	    "isDoctorAppointed": false
	}
]

```

In the above dataset, we have three patients: John, Zia, and Kevin. The aim is to restrict Zia from accessing Kevin and John's data. To achieve this, we need to create a **tenant token** for her with a set of search rules.

For this case, the search rules can be specified as:

```jsx
"searchRules": {
      "patient_medical_record": {
          "filter": "patient = Zia"
      }
  }

```

Zia's tenant token will be applied at the time of the search request, which returns:

```json
[
	{
	    "patient": "Zia",
	    "description": "Zia is in room number 3 and is suffering from Dengue",
	    "roomNumber": 2,
	    "isDoctorAppointed": true
	}
]

```

This is a simple use case, but we can modify the rule to meet more complex requirements.

### ****Integrating the multitenancy feature in your application****

We will use the above example to create an [application](https://tenant-token.meilisearch.com/) for displaying patients in a Meilisearch index. We will then use multitenancy to restrict access to this data.

1.  **Download the application**
    
    Clone the boilerplate code for the demo application from the Meilisearch tutorials repository on Github.
    
    Use the following command:
    
    ```jsx
    git clone https://github.com/meilisearch/tutorials
    
    ```
    
    The boilerplate code exists in the `src/tenant-token-tutorial` directory.
    
    ```jsx
    cd src/tenant-token-tutorial
    
    ```
    
    This code contains a frontend application built in `React.js` and a backend server in `Express.js/Node.js`.
    
2.  **Start Meilisearch**
    
    There are multiple ways to [download and run a Meilisearch instance](https://docs.meilisearch.com/learn/getting_started/quick_start.html#download-and-launch). The easiest way to run a Meilisearch instance is using [Meilisearch Cloud](https://cloud.meilisearch.com/), there's a free 14-day trial, no credit card required. Meilisearch is open-source, in this demo, we'll run it locally using Docker:
    
    ```bash
    docker pull getmeili/meilisearch:v1.0
    
    
    docker run -it --rm \
        -p 7700:7700 \
        -e MEILI_MASTER_KEY='masterKey'\
        -v $(pwd)/meili_data:/meili_data \
        getmeili/meilisearch:v1.0 \
        meilisearch --env="development"
    
    ```
    
    _Don't forget to define a [master key](https://docs.meilisearch.com/learn/security/master_api_keys.html#protecting-a-meilisearch-instance) as shown above when launching Meilisearch. It will create the API keys needed to generate the tenant tokens._
    
    The Meilisearch instance will run on the IP address: `http://localhost:7700`.
    
3.  **Adding data to Meilisearch**
    
    There is a `data.json` file in the `seed` folder of the base directory with a list of 10 patients suffering from multiple conditions with 100 entries, each with a room number and some patient details. We'll enter the information into Meilisearch.
    
    Change the terminal directory to the `seed` folder and add the given data to the Meilisearch instance, using the following command:
    
    ```bash
    npm install     #  This command will install node dependencies
    
    npm start         # This command will add all the data from data.json to Meilisearch
    
    ```
    
4.  **Start frontend server**
    
    Navigate to the `frontend` folder, and install all the application dependencies, and Meilisearch Javascript SDK
    
    ```bash
    npm install                # To install all the react application dependency
    
    npm install meilisearch    # To install the Meilisearch SDK
    
    ```
    
    It can take a while to install all the dependencies of the project.
    
    Let's get the frontend React server up and running with the command:
    
    ```jsx
    npm start
    
    ```
    
    The app will run on the IP address: `http://localhost:3000`.
    

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

1.  **Adding the functionality to create tenant tokens**
    
    Navigate to the `backend` folder and install all dependencies using the following command:
    
    ```jsx
    npm install
    
    ```
    
    In the `backend` folder, open the `index.js` file. It contains the APIs' route and logic.
    
    An endpoint is already defined for generating the **Tenant token**:
    
    ```jsx
    app.get("/create-tenant-token", async (req, res) => {
      const { value: patientName } = req.query;
    
      /* Add functionality to create Tenant token */
    });
    
    ```
    
    Now, we'll add the functionality below the comment in the function.
    
    We need an API Key, search rules, and an expiration date to generate a tenant token.
    
    The API Key can be obtained from the `getKeys` method in the Javascript SDK. The `getKeys` method returns a list of API Keys from which we can select one to use in the **tenant token** generation process. To do so, add the following code to the API method stated above:
    
    ```jsx
     const { results } = await client.getKeys();
     const apiKey = results.filter((res) => res.name === "Default Search API Key")[0].key;
     const apiKeyUid = results.filter((res) => res.name === "Default Search API Key")[0].uid;
    
    ```
    
    We can also use the `createKey` function to generate a new API Key.
    
    You can read more on API keys in the [Meilisearch documentation](https://docs.meilisearch.com/reference/api/keys.html).
    
    By specifying search rules, we can now generate a payload. Use the following code to define a payload:
    
    ```jsx
    const payload = {
      patient_medical_record: {
        filter: `patient = ${patientName}`,
      },
    };
    
    ```
    
    If we need the token to expire after a year, we can set an expiration date when creating the token, as shown below.
    
    ```jsx
    const expiresAt = new Date(
      new Date().setFullYear(new Date().getFullYear() + 1)
    );
    
    ```
    
    To generate the token, we can now use the `generateTenantToken` function from the Meilisearch Javascript SDK, and return the generated token using `res.json(`) function.
    
    ```jsx
    const tenantToken = client.generateTenantToken(apiKeyUid, payload, {
      apiKey,
      expiresAt,
    });
    
    return res.json({ token: tenantToken });
    
    ```
    
    This is how the endpoint should be implemented:
    
    ```jsx
     app.get("/create-tenant-token", async (req, res) => {
      const { value: patientName } = req.query;
    
      /* Add functionality to create Tenant token */
      const { results } = await client.getKeys();
      const apiKey = results.filter((res) => res.name === "Default Search API Key")[0].key;
      const apiKeyUid = results.filter((res) => res.name === "Default Search API Key")[0].uid;
    
    
      const payload = {
        patient_medical_record: {
          filter: `patient = ${patientName}`,
        },
      };
    
      const expiresAt = new Date(
        new Date().setFullYear(new Date().getFullYear() + 1)
      );
    
      const tenantToken = client.generateTenantToken(apiKeyUid,payload, {
        apiKey,
        expiresAt,
      });
    
      return res.json({ token: tenantToken });
    });
    
    ```
    
    The frontend requested endpoint will look like this:
    
    ```bash
    http://localhost:5001/create-tenant-token?value=John
    
    ```
    
    A payload containing the search rules is created using the value `John` from the API.
    
    Let's use the `npm start` command to start the express API server. The server will run at `http://localhost:5001.`
    
2.  **Connect your APIs with the Frontend code**
    
    Enter the patient's name in the text box. On submitting the input form, an API call is sent to the backend, which should return a tenant token. We can pass this token to the Meilisearch instance when we need data on a certain patient.
    
    The frontend code must now be configured to request a tenant token from the server. We'll use the [axios library](https://www.npmjs.com/package/axios) to get the token from the `/create-tenant-token` API that we've developed, and we'll pass the patient name in the API's params.
    
    Open the file `index.js` in the `/src/utils` folder and look for the `getTenantToken` function. This function makes a request to the server and receives a tenant token back.
    
    Add the following code to the getTenantToken method:
    
    ```jsx
    export const getTenantToken = async (patientName) => {
      const response = await axios({
        url: `${apiHost}/create-tenant-token`,
        method: 'GET',
        params: {
          value: patientName,
        },
      })
    
      return response.data.token
    }
    
    ```
    
3.  **Test out the implemented functionality**
    
    Let's test the implementation; start by clicking the **`Create a Tenant token`** button.
    
    ![drawing](https://unable-actionable-car.media.strapiapp.com/tenant1_b0077452fb.png)
    
    Type the name `Kevin` in the given text box, and click **`Create a Tenant token` button**. This generates the tenant token.
    
    ![meili-create-token](https://unable-actionable-car.media.strapiapp.com/meili_create_token_76fc8c30f6.gif)
    
    Meilisearch will get data based on the tenant token provided by the patient, acting as an authenticator in the process.
    

### Conclusion

We have restricted access to medical records based on the names of the patients. Using Meilisearch's multitenancy capabilities, we were able to execute all of this with ease. This is a pretty basic use case scenario that comes to mind. The functionality can be as complex as you want it to be. For example, we can implement multitenancy in an e-banking application where the central authority is the bank and the customers are tenants having access to distinct bank accounts.

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

Meilisearch latest news and company updates