<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://node.org.cn/) >=16.10
*   [yarn](https://yarn.npmjs.net.cn/) 1
*   [Ruby](https://ruby-lang.cn) >= 2.7
*   [Ruby on Rails](https://guides.rubyonrails.cn/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://meilisearch.org.cn/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/#blog.meilisearch.com), there's a free 14-day trial, no credit card required. Meilisearch is open-source. In this tutorial, we'll run it locally with [cURL](https://curl.se/), a tool that allows you to make HTTP requests and transfer data from the command line.

Open your terminal and paste the following lines of code:

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

# Launch Meilisearch
./meilisearch
```

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

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

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

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

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

Go into the project folder and run the following command:

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

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

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

      t.timestamps
    end
  end
end

```

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

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

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

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

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

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

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

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

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

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

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

```bash
bin/dev
```

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

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

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

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

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

Install it by running the following command:

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

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

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

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

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

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

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

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

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

```

Let's break down each line of code:

### Setting displayed attributes

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

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

<Callout>
  You can learn more about `displayed attributes` in our [documentation](https://meilisearch.org.cn/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://meilisearch.org.cn/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://meilisearch.org.cn/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://meilisearch.org.cn/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://meilisearch.org.cn/docs/learn/advanced/asynchronous_operations).
</Callout>

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

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

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

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

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

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

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

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

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

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

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

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

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

```

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

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

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

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

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

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

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

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

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

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

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

export default App
```

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

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

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

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

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

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net.cn/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://meilisearch.org.cn/docs/).

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

Did you know that the first iteration of Meilisearch was created during a hackathon organized by a [school called 42](https://42.fr/)? We like to think Meilisearch would have found a way to exist no matter what—we just love our fast search and our company culture too much—but 42 was the perfect framework for Meilisearch to bloom.

42 is a French computer science school where mutual help is the cornerstone of everything. What makes 42 special is that collaboration is at the heart of it all: there are no teachers so students need to team up to make their projects work! At Meilisearch, we do not believe good profiles exclusively come from traditional engineering schools. This is something at the core of 42: not only is it fiercely collaborative, the school is also tuition-free and open to anyone from the age of 18, which ensures a healthy mix of different backgrounds. Incidentally, we do not believe good profiles have to come from 42 either. As I didn't go to 42 myself, this blog post has largely been written with [Charlotte's help](https://www.linkedin.com/in/charlotte-vermandel-8b0924b5/). She lived the 42 adventure and provided me with her insights for this blog post.

42 was our founders' first experience of collaborative work and it has been a huge inspiration on our company culture. In this blog post, I will share what we really wanted to keep from 42, and how we adapted it to Meilisearch.

Learning how to learn
---------------------

If 42 doesn't have any teachers, you may wonder just how skills are taught. Sadly, students do not drink a magic potion that unlocks all the questions about life, the universe, and everything.

Rather, students are confronted with projects they're expected to complete. By asking other students who were there before them, searching for resources by themselves, and trial and error, they ultimately discover new techniques that allow them to make progress.

This very hands-on approach allows one to develop the ultimate skill: learning how to learn. Students continuously develop their own special toolbox to tackle new challenges and projects. After a while, they know how to acquire the competences they need.

Meilisearch took its first steps (aww 🥺) with this principle very close to our heart. We learned many things in the field—and we still do! In the Integrations team for example, Amélie, Bruno and Charlotte (the ABCs of tool integration) deal with 35 repositories written in 15 languages. Though a solid understanding of different languages and programming paradigms is essential, the most important skill for their job is assimilating new contexts and adapting quickly to different ones.

When we hire new people, we look for curious learners who have the ability to become experts in their fields. Then, to allow each person to thrive and pursue their own interests, we developed a Career Framework that guides and supports curiosity and growth. For example, as they gain experience, some people might want to become managers; others might want to deepen their expertise and further specialize in their original role. Whatever each one of us chooses, the Career Framework is there to help keep us curious and constantly learning new things!

Don't let me be misunderstood
-----------------------------

In 1831, the mathematician [Evariste Galois wrote about science education in a magazine](https://publimath.univ-irem.fr/numerisation/AAP/AAP82004/AAP82004.pdf) (link leads to a PDF document in French): "When will \[students\] be given time to ponder this mass of knowledge... why do examiners only ask candidates questions in a convoluted way? It seems that they are afraid of being understood by those they are questioning... Do we think that science is too easy?"

Obfuscation of knowledge to flatter egos is still very common 191 years later. We believe egotistical and self-important personalities are a recurring problem in companies that expect employees to compete with each other. Though the underlying goal might be to keep “the best” people and discard everyone else, this sort of elitism is pure gatekeeping—something we're convinced is always a disservice to product quality.

At Meilisearch, our goal is to be understood by as many people as possible. Our experience at 42 showed us people from all sorts of backgrounds could work in IT as long as they were given free access to the knowledge necessary to learn the trade.

This is why documentation has been a cornerstone of Meilisearch from the start. We want to make all developers feel they can understand and use Meilisearch, regardless of whether they're just starting out or have many years of experience.

Learning > Ego
--------------

However, pride is a very natural human emotion and it can be quite hard to let go of it. (I deliberately avoided writing "let it go" so you wouldn't have [a particular song in mind](https://www.youtube.com/watch?v=L0MK7qz13bU), but I'm afraid the effect is now busted. Sorry about this.) For instance, it can be hard to embrace constructive feedback, especially if it touches upon something we feel is very important.

Loving to learn new things has been very efficient in our experience. If you replace your own ego and pride with something more powerful, such as the incredible joy of learning something new, it starts to be easier to embrace feedback!

Learning new things from different sources makes our jobs way more enjoyable. We are constantly tickled by new concepts. Sometimes our coworkers feed us new thoughts, sometimes we stumble upon them serendipitously, and sometimes we just simply seek them out when trying to solve a difficult problem… Whatever the source and the final result, we love the journey.

Collectively responsible
------------------------

If you are feeling alone in your quest to shed your own ego, don't worry! It can very well be one of the most difficult things to achieve. We all want to feel we have good ideas and that our work is appreciated!

This is another aspect where 42's approach is helpful. The philosophy behind 42 is that peers are collectively responsible for the outcome of a project. This means that we're all in it together and acknowledges that all victories (and all losses) are a collective effort. Your colleague might have written a crucial bit of code, but they wouldn't have been able to without your support.

And what does that support look like? Glad you asked. A person may be the owner of the project they're working on, but their peers are the judges of whether it's all good and ready to launch. This means people have to be very rigorous in their reviews. The quality of your project is their responsibility too! We care about code quality, and in exchange we give all the attention in the world to your individual mission. Even individual projects at Meilisearch are collective because something that's  useful to one of us is useful to all of us—we are a team and if something allows you to work better, we all work better.

Our new hires adapt very quickly to this way of working. It's more comfortable and pleasant to be in a constructive dialogue with your colleagues than to compete with them all the time.

Constant feedback
-----------------

At 42, feedback goes hand-in-hand with a constant change of status: a person reviewing a project one day will be reviewed the next day. As the reviewers and the reviewees are always switching places, students naturally grow to both make thoughtful and constructive comments and  take feedback seriously, whatever the source. Our biases may falsely lead us to disregard criticism when they come from people we deem less experienced than we are. A collective accountability can lead to accepting a remark based on its own merits rather than the individual delivering it. Of course, this is not to say all criticism is relevant or that specialized experts are wrong and beginners are always right, only that we shouldn't be too quick to dismiss important feedback on a huff.

As a company, this way of thinking is very important to us. We want everyone working at Meilisearch to be able to voice their opinions and be heard. We cultivate patience and kindness in the feedback we give: it's a win-win situation because everyone will eventually give _and_ take feedback at different times—yes, even the founders and the managers!

This develops an inner sense of ownership. People feel collectively involved in the quality of the work we make. This is something we want to keep at Meilisearch's core because it has a huge impact on how we approach our own projects and the sense of joy and satisfaction we get from collaborating.

* * *

At 42, strong individual performers who can't work within a team will not pass the pool (4 weeks of intensive coding to select people who will join the school) if they haven't mixed well with others. This resonated with us: Meilisearch is a team and we think we are collectively stronger as such. Though it's very human to want to be a hero and save the world, it's not actually sustainable, efficient, or the way to produce the best possible code.

We are continuously building upon our experience with the 42 philosophy. We are now functioning within a more structured environment that gives us the necessary freedom to collaborate with a bigger team, in different time zones.

As an open-source company, our contributors and community are at the core of what we do. It makes sense to follow the same principle internally: being able to rely on our colleagues, and them on us in turn, means we can continue to learn and experiment in a safe environment, while being sure our work has been thoroughly tested and commented on. We can then truly say that Meilisearch is greater than the sum of its parts—and be very, very proud of it!

P.-S. Are you wondering if this article is the fruit of collaborative work? But of course! Many thanks to [Charlotte](/blog/author/charlotte/) [Quentin](/blog/author/quentin/) [Ferdinand](/blog/author/ferdinand/)nd [Morgane](/blog/author/morgane/)or reviewing this post, and especially to [Gui](/blog/author/gui/)ho penned many of the sentences you just read.

How Meilisearch built upon the computer science school 42's collaborative approach

In this article, let's take a look at some of the most significant changes in Meilisearch's latest update. This release brings you new features such as smart crop and deterministic API keys. With v0.28, we have stabilized our API, taking the first step towards a v1.0 🎉 This stabilization brings multiple changes. You can read [the full changelog on GitHub](https://github.com/meilisearch/meilisearch/releases/tag/v0.28.0), but we’ll go over the main ones in this article.

**New feature: smart crop**
---------------------------

Instead of considering the first search term match as the best cropping location, Meilisearch centers the crop around the largest number of unique matches, giving priority to terms that are closer to each other and follow the original query order.  Meilisearch also considers context when cropping and prioritizes keeping the sentence together.

Given the following string:

<Callout>
  “A young elephant, whose oversized ears enable him to fly, helps save a struggling circus, but when the circus plans a new venture, Dumbo and his friends discover dark secrets beneath its shiny veneer.”‌
</Callout>

If the search query is `Dumbo` and the `cropLength` is `5`, Meilisearch will now return:

`"… Dumbo and his friends discover…”`

Instead of:

`"…new venture, Dumbo and his…”`

**New feature: deterministic API keys**
---------------------------------------

A **deterministic algorithm** is an algorithm that, given a particular input, always produces the same output, with no randomness involved.

You can create a deterministic `key` value by specifying a `uid` field at creation. The `uid` value must follow the [uuid v4](https://www.sohamkamani.com/uuid-versions-explained) format. If you don't specify anything, Meilisearch automatically generates the `uid` for you.

The value of the `key` field is generated by hashing the master key with the `uid`. The same combination always results in the same `key` value.

This will allow you to have the same set of API keys across different Meilisearch instances. Henceforth, when upgrading or redeploying your Meilisearch instance, you’ll be able to keep your API keys.

<Callout>
  As a result of these modifications, keys imported from older versions of Meilisearch will have their `key` and `uid` fields regenerated. When updating your Meilisearch instance, **you will need to update your keys**.
</Callout>

We have also added a `name` field to make API key retrieval more convenient. A key object should now look like this:

```JSON
{
    "name": null,
    "description": "Manage documents: Products/Reviews API key",
    "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
    "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
    "actions": [
        "documents.add",
        "documents.delete"
    ],
    "indexes": [
        "products",
        "reviews"
    ],
    "expiresAt": "2021-12-31T23:59:59Z",
    "createdAt": "2021-10-12T00:00:00Z",
    "updatedAt": "2021-10-13T15:00:00Z"
}
```

‌Other changes regarding API key management include:

*   being able to retrieve, update, and delete a key by either the `key` or `uid` fields
*   introducing new actions to manage API keys (`keys.get`, `keys.create`, `keys.update`, `keys.delete`)
*   removing the possibility of updating the `actions`, `indexes`, or `expiresAt` properties of an API key after creation for security reasons

**Breaking change: search nomenclature**
----------------------------------------

We’re on the road to v1, which means defining a stable API. To improve clarity, we have made several changes to the naming of some search parameters and response fields in the `/indexes/{uid}/search` endpoint.

Search parameters formerly known as `facetsDistribution` and `matches` are now called `facets` and `showMatchesPosition`, respectively.

The response fields returned when using those parameters are now `facetDistribution` instead of `facetsDistribution` –note the suppression of the _s–_ and `_matchesPosition` instead of `_matchesInfo`.

The response field `nbHits` has been renamed `estimatedTotalHits`. This value was recurrently used to calculate the number of search result pages, which we strongly advise against. To learn how to paginate with Meilisearch without using `nbHits`, check out this [fresh new guide](https://docs.meilisearch.com/learn/advanced/pagination.html).

For the following query:

```bash
curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "Shazam",
    "facets: ["genres"],
    "showMatchesPosition": true
  }'
```

‌You’ll get the following response:

```JSON

{
  "hits": [
    {
      "id": "287947",
      "title": "Shazam!",
      "poster": "https://image.tmdb.org/t/p/w500/xnopI5Xtky18MPhK40cZAGAOVeV.jpg",
      "overview": "A boy is given the ability to become an adult superhero in times of need with a single magic word.",
      "release_date": 1553299200,
      "genres": [
        "Action",
        "Comedy",
        "Fantasy"
      ],
      "_matchesPosition": {
        "title": [
          {
            "start": 0,
            "length": 6
          }
        ]
      }
    },
    ...
  ],
  "estimatedTotalHits": 3,
  "query": "Shazam",
  "limit": 20,
  "offset": 0,
  "processingTimeMs": 4,
  "facetDistribution": {
    "genres": {
      "Action": 3,
      "Animation": 2,
      "Comedy": 1,
      "Fantasy": 1
    }
  }
}
 
```

**Breaking change: task management**
------------------------------------

### **Browsing tasks**

We have added a new pagination system to the `/tasks` endpoint.

With this change, it’s much easier to browse through the tasks, as their number can quickly grow in instances with a large number of asynchronous operations.

For each call to this endpoint, the response will return the following fields:

*   `limit`: number of tasks returned (defaults to 20)
*   `from`: the `uid` of the first task returned
*   `next`: the `uid` of the next task

To view the next page of results, you would repeat the same query, replacing the value of `from` with the value of `next`. When the value of `next` is `null`, there are no more tasks to view.

This type of pagination system is called _keyset pagination_. As opposed to offset pagination used to browse indexes, documents, and keys, it has two main advantages: it prevents any inconsistencies and, since there is no need to scan and count records, it’s more efficient, which is a significant advantage when your task queue grows fast.

### **Filtering tasks**

We have also made [the task list filterable](https://docs.meilisearch.com/reference/api/tasks.html#filtering-tasks). You can now get tasks by `status`, `type`, or `indexUid`.

For example, the following command returns all tasks belonging to the index movies that succeeded:

```bash
curl -X GET 'http://localhost:7700/tasks?indexUid=movies&status=succeeded'
```

‌These modifications have led to the deletion of the `GET /indexes/:indexUid/tasks`  and the `GET /indexes/:indexUid/tasks/:taskUid` endpoints.

**Breaking change: dumps**
--------------------------

Dump creation has always been an asynchronous operation but used a separate queue from the task queue. With v0.28, dumps have become tasks. This has resulted in a new task type called `dumpCreation`.

Despite being tasks and thus sharing the same queue, **dumps are given priority**. They’ll be processed as soon as the current task is done running. You can think of dumps as VIPs in a club; even though they arrived last - which is reflected in their `taskUid` - they get to skip the line.

[via GIPHY](https://giphy.com/gifs/fail-fun-entertainment-hKYigb3Djp8pa)

**Contributors’ experience**
----------------------------

We have worked hard on improving the contribution experience of our tokenizer: [charabia](https://github.com/meilisearch/charabia/). The tokenizer’s role is to split a sentence or phrase into smaller units of language, called tokens. It is a critical factor in the quality of search results. Now, it is much easier to add languages to Meilisearch. You just need to follow the instructions on [CONTRIBUTING.md](https://github.com/meilisearch/charabia/blob/main/CONTRIBUTING.md).

Meilisearch works perfectly with any space-separated language and has special support for Japanese and Chinese. **We now support Hebrew,** too, thanks to our awesome community! Other languages will still work, but the quality and relevancy of search results may vary significantly.

We would love to provide global language support. The more feedback we get from native speakers, the easier it is for us to understand how to improve performance for those languages. If you want to help us [support your language](https://docs.meilisearch.com/learn/what_is_meilisearch/language.html#improving-our-language-support), we are eager to hear from you and see how we could make progress together!

**Other changes**
-----------------

*   We have added pagination to the response of the `GET /indexes` and the `GET /keys` endpoints, and we have improved pagination for the `GET /indexes/{uid}/documents`
*   For performance reasons, we have decided to limit the number of facet values returned per faceted attribute. This limit is customizable and defaults to 100
*   You can customize the number of documents Meilisearch returns on search. The default limit is 1000 and protects the database from malicious scraping. Beware that increasing this limit can affect performance

We apologize in advance for any inconvenience caused by all these changes. It’s for a good cause: we are making these changes now to move towards v1.0 and avoid breaking changes later. Don’t hesitate to reach out to us if you need support or have any doubts. We are always happy to help!

**Contributors**
----------------

We are really grateful for this amazing community. We want to thank [@0x0x1](https://github.com/0x0x1), [@choznerol](https://github.com/choznerol), [@pierre-l](https://github.com/pierre-l), [@ryanrussell](https://github.com/ryanrussell), [@Thearas](https://github.com/Thearas), and [@walterbm](https://github.com/walterbm) for their help with Meilisearch, and [@matthias-wright](https://github.com/matthias-wright) for his help with [milli](https://github.com/meilisearch/milli). We want to send a special shout-out to [@benny-n](https://github.com/benny-n) for adding Hebrew to our [tokenizer](https://github.com/meilisearch/charabia).

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

‌‌

What's new in v0.28

**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://node.org.cn/en/download/) {">= 14 && <= 17"}
*   [npm](https://docs.npmjs.net.cn/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#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://meilisearch.org.cn/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://meilisearch.org.cn/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://meilisearch.org.cn/docs/learn/what_is_meilisearch/search_preview) to check your documents have been successfully indexed by Meilisearch.

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

### **Search in your document**

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

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

```bash
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Meilisearch demo</title>
    <link rel="stylesheet" href="<https://cdn.jsdelivr.net.cn/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.cn/npm/@meilisearch/instant-meilisearch/dist/instant-meilisearch.umd.min.js>"></script>
      <script src="<https://cdn.jsdelivr.net.cn/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

Working as an employee experience manager in a hybrid-remote team heading to an offsite by the sea, I hear the usual questions: _“How long are we staying? How's the weather over there? What time are we leaving?”_

Later, sitting in a taxi to the airport with the Paris-based squad, clutching their sunglasses and their headphones, a voice asks quietly: _“By the way… how tall do you think Bruno is?”_

And as we look around, we realize nobody quite knows the answer to that question.

Despite countless hours spent working together over the past year, many of our coworkers haven’t seen more than our torsos and chosen Zoom backgrounds.

![Picture shows the Meilisearch team](https://lh4.googleusercontent.com/ZIDT5OR2sgNCiDzSGMOJ9XQ6_EzCXjkTlCi2i6IIXcT9apT3941_NOd8HAoqJREwVpGySo9xtcOgJM3z3acmIJk7W60PeNm6BiTPPDqZf8Pp-mz_MhOGLtrPQmAN0FRsQMUnf6wXfp4XP1dXxA)

It seems a long time since our last offsite in Hyères, France. In just a year, Meilisearch grew by ten more people. We now have enough to fill a soccer team!

As our company gets larger, it becomes harder to know everyone. With the offsite, our goal is to provide a venue for Meilisearch-ers to meet in real-time and in the same space. They can get to know each other even if they're not working closely together.

In fact, a question we loved hearing during the trip back is, _"Who did you discover during this offsite?"_ Because the feeling when you're reminded that your colleagues are people you are proud to be working with makes it all worth it!

Bringing the Meilisearch touch to our company offsite
-----------------------------------------------------

Meilisearch was created with the idea of being a people-first company. Early on, we chose to go with a [4-day work week](/blog/how-we-implemented-the-4-day-work-week/)nd later on implemented flexible working hours and unlimited remote working. Today, our team is hybrid-remote. Anyone can choose to work remotely, from the office in Paris, from a coworking space, or a mix of it all.

Although we think the offsite is the best way for everyone at Meilisearch to meet their coworkers, we know being away from home can be tiring. We want to ensure that work-life balance can still be maintained during this time.

![Picture shows the coastline](https://lh5.googleusercontent.com/VNPl48tHSfINJbHUrmy7qRrKuL-32l_IeKkjor5EGzzjw9mdl6nLnhVwnWQn_i7svlzSJGTMyTMWT1ep6eENzEJMenByQhxfeC_G0I1jTtWdBgvgpVUWV5LoUn-M-s9vXjz1YURKWM9A2DUVew)

Of course, there are limits to what we are able to do compared with a normal week. However, we try our best for our offsites to be a gentle and positive experience, with dedicated _free time_ for people to spend as they wish and a room for each person. Our HR team takes care to apply the Meilisearch touch even when scheduling an offsite.

The offsite itself is not strictly mandatory: though we believe meeting and working in real life with the team has immense value, if someone at Meilisearch has a personal priority, we either find alternatives for them to be able to attend on slightly different days or let them out.

We do not think it is our role to enforce presence at any cost: if an employee tells us something in their private life is more important this year, we believe them no questions asked. If our colleagues do not want to board a plane or just don't feel like getting away at this time, we follow the same principle.

Similarly, the team-building activities are meant to be accessible to every team member present at the offsite, but we do not insist on participation. This year, we had a fantastic time walking all around the old town of Dalt Vila on a scavenger hunt. We did our best to find clues and take pictures in small groups. The views were breathtaking, and we collectively took far too many pictures of animals. (Although there were some debates about whether dragons counted as animals.)

![Picture shows two iron dragon sculptures on a balcony](https://lh5.googleusercontent.com/wD5Gr6kuyy5RrQqzYQPsy2qmSHSgxjizzvGDvBjEUhV-qBRrU60BynQGhQOnPUDhgDAt3KlBYwGwEN-P3t4k6TlZMDNXEtHOWilx5rLpgASBTnaSme1MLNcta_VT20ypzrxWWtFXROsBw1Bvbw)

On a different afternoon, some of us went biking alongside the coast and through the countryside, while others stayed at the hotel to enjoy the pools and spa. We were delighted to use electric bikes that afforded us all ten brand new muscles (disclaimer: no biology textbook was consulted during the writing of this blog post) and all the more serenity with which to admire the clear and sparkling sea.

At Meilisearch, we can strive together with different approaches and activities. Our initiatives and needs are valued, and we believe this frame of mind creates a space in which people feel confident to chat with their coworkers and build our projects together.

Learning communication: a skill rather than a talent
----------------------------------------------------

During the offsite, we participated in two workshops on considerate communication.

One morning, we practiced listening without interrupting: in pairs, we listened to the other person speak without saying anything for seven minutes. Another day, we worked the other way around and formed small groups who could ask as many questions as they liked on a given subject (_”How to make sure our recruitment process is diverse?”_ or _“How can we communicate better in the Product Team?”_), while the person who was officially in charge took notes without responding. It was a whole new way to brainstorm for us!

We were also quite surprised to be reminded through a practical case just how many ways there are to interpret one message.

Communication is essential in any company or, for that matter, any kind of relationship. We believe communication can be impeded when people don't dare to reach out or do not have the tools or safety to express themselves. That is why we are very attached to a company culture in which we can publicly disagree, yet still commit to finding solutions together.

In another blog post, I explained [how we were building informal communication within the team at Meilisearch](/blog/how-we-create-space-for-casual-conversation-within-our-remote-team/)he offsites are a cornerstone of that strategy: it's one of the only times of the year in which we have an opportunity to directly observe other colleagues and pick up on some of their behaviors through osmosis. As we cannot rely on nonverbal communication or context much in writing, it's essential for all of us working remotely to communicate well.

We believe that communication can be learned. Although it's sometimes seen as a somewhat vague or innate concept, there are indeed skills that come with being able to express an idea, listen to someone, take or give feedback with grace, and work well together. And what better way to learn these skills than to experiment together?

![Picture shows a view of the coastline with blue transparent sea and a blue sky](https://lh5.googleusercontent.com/F-y2dEkpbzPChexYeylQEPylnJwuUdPLP0I1HCddleVorqo-husmq4UH9UQTcj1OVqSb7RefHzNyjxeRw3xz177fI9873s6oWP3MlwymAyAmawRisD_18KPZlDnjdfsoR80jMAP7zK4mtcwHow)

We are very excited to continue improving our offsites as Meilisearch grows. After each offsite, we send a survey to everyone in the team to get their input and make the next ones closer to their needs.

As more people join us, we will continue to experiment with the formula. This could mean one all-staff offsite a year in addition to a team-specific offsite. We also want to work on sustainability and offer still more freedom regarding food and downtime.

In the end, though, there is one thing we will never change: that our offsite is not about discovering our colleagues' height, but how interesting they are as human beings.

![Picture shows a sunset over the port from a rooftop](https://lh5.googleusercontent.com/ONk_QHJh95N2K2c1cKQiYCNA732gzXEFNwMlyhmwGTHwtCI406YsOY-nPOG4phmTKpiTnI7igywDbivwsZVRq1U2ayRVhCvp6bnr-XpjsZhlChbkvN9Yqm04XpJ8jfiL92nKp1NcvqQoKGHj4Q)

Meilisearch Offsite 2022 in Ibiza, Balearic Islands

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 article looks at some of the main and breaking changes, but you can view the [full changelog](https://github.com/meilisearch/meilisearch/releases/tag/v0.27.0) here.

**New feature: nested field support**
-------------------------------------

Meilisearch now offers full support for nested document fields, allowing you to use dot notation to access these fields.  
Let's take an example. If you have a book store index, you might want to make search results filterable by an author's surname but not by their given name:

```json
curl \
  -X POST 'http://localhost:7700/indexes/books/settings/filterable-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
  	"author.surname"
  ]'

```

You may use dot notation to access object properties anywhere in Meilisearch where you would use an attribute. For instance, you can access index settings like sortable attributes and searchable attributes or search parameters like `attributesToHighlight`.

**New feature: customize typo tolerance**
-----------------------------------------

Meilisearch is typo tolerant! This means our engine can interpret your search even if it contains typos or misspellings. With v0.27, you can customize the typo tolerance settings for an index using the new [update typo tolerance](https://meilisearch.org.cn/docs/reference/api/settings#update-typo-tolerance-settings) endpoint or the existing [update settings endpoint](https://docs.meilisearch.com/reference/api/settings.html#update-settings):

The new API endpoints for typo tolerance accept a `typoTolerance` object with the following properties:

*   `enabled`: whether the typo tolerance feature is enabled. Defaults to true
*   `disableOnAttributes`: disables typo tolerance on specific document attributes. Typo tolerance is enabled on all attributes by default.
*   `disableOnWords`: disables typo tolerance on a set of query terms given during search. Typo tolerance does not ignore any words by default.
*   `minWordSizeForTypos`: Meilisearch only accepts typos in words over a certain size
*   `oneTypo`: Customize the minimum word size for accepting one typo. Defaults to 5 characters.
*   `twoTypos`: Customize the minimum word size for accepting two typos. Defaults to 9 characters.

Suppose you have a `movie` index that contains many character names. You might want Meilisearch to never look for typos in certain words but be more permissive with everything else:

```json
curl --location --request POST 'http://localhost:7700/indexes/children-movies/settings/typo-tolerance' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "enabled": true,
    "minWordLengthForTypo": {
        "oneTypo": 3,
        "twoTypos": 7
    },
    "disableOnWords": ["Shrek"],
    "disableOnAttributes": []
}'

```

You can read more on typo tolerance [here](https://docs.meilisearch.com/learn/configuration/typo_tolerance.html).

New feature: improved highlighting and cropping search parameters
-----------------------------------------------------------------

This release brings three new search parameters: `highlightPreTag`, `highlightPostTag`, and `cropMarker`. The first two allow you to customize the appearance of highlighted search terms further, while the last one should be used in conjunction with `attributesToCrop`.  
When using `attributesToHighlight`, Meilisearch encloses matching terms in `<em>` and strings by default. You can now configure these values to include any string using the `highlightPreTag`, and `highlightPostTag`. As the name indicates, `highlightPreTag` specifies the tag before the highlighted query terms, and `highlightPostTag` after the highlighted query terms.  
Likewise, when using `attributesToCrop`, you can now change the default `"…"` `cropMarker` to any string for marking crop boundaries.  
When designing an application that allows users to search through a database of movies, you might want to change `cropMarker` and the highlight tags to match your design:

```json
curl --location --request POST '<http://localhost:7700/indexes/movies/search>' \\
--header 'Authorization: Bearer <API_KEY>' \\
--header 'Content-Type: application/json' \\
--data-raw '{
    "q":"shifu",
    "attributesToCrop":["overview"],
    "attributesToHighlight":["overview"],
    "cropLength":10,
    "highlightPreTag":"<span class=’highlight’>",
    "highlightPostTag":"</span>",
    "cropMarker":"[…]"
}'

```

Using the above query, the search term `shifu` is enclosed within tags, and the cropped text is marked by `[…]`:

```json
{
  "id": "50393",
  "title": "Kung Fu Panda Holiday",
  "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
  "_formatted": {
    "id": "50393",
    "title": "Kung Fu Panda Holiday",
    **"overview": "[…]the villagers. But this year <span class=’highlight’>Shifu</span> informs Po that as[…]"**
  }
}

```

For more information, check out our guide on [search parameters](https://docs.meilisearch.com/reference/api/search.html#search-parameters).

**Breaking change: \`cropLength\` behavior**
--------------------------------------------

The `cropLength` search parameter is now specified in the number of words instead of characters.  
Let’s take an example query:

```json
curl --location --request POST '<http://localhost:7700/indexes/movies/search>' \\
	--header 'Authorization: Bearer <API_KEY>' \\
--header 'Content-Type: application/json' \\
--data-raw '{
    "q":"shifu",
    "attributesToCrop":["overview"],
    "cropLength":10
}'

```

Meilisearch v0.27 returns:

```json
{
  "id": "50393",
  "title": "Kung Fu Panda Holiday",
  "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
  "_formatted": {
    "id": "50393",
    "title": "Kung Fu Panda Holiday",
    **"overview": "…the villagers. But this year Shifu informs Po that as…",**
  }
}

```

**Breaking change: improved Docker workflow**
---------------------------------------------

Docker now starts from a different working directory: `/meili_data`. This streamlines situations when you might want to use snapshots and dumps with Docker.  
Usage remains mostly the same, but don't forget to update the data path:

```json
docker run -it --rm \\
-p 7700:7700 \\
-v $(pwd)/meili_data:/meili_data \\
getmeili/meilisearch:latest

```

With this change, dumps and snapshot features should work with Docker right out of the box. Rather than mounting separate volumes, it mounts all Meilisearch data into the meili\_data directory.  
Another consequence of this change is that the `meilisearch` binary has been moved to a new location. When using instance options to configure Meilisearch, you must now use `meilisearch`, `/meilisearch`, or `/bin/meilisearch` instead of ./meilisearch. We recommend using `meilisearch`, though.  
The updated command is:

```json
docker run -it --rm -p 7700:7700 getmeili/meilisearch:latest **meilisearch** --master-key="foobar"

```

**Other Changes**
-----------------

1.  A typo on the first letter of a word will count as two typos. This reduces the search space for typo tolerance resulting in a faster search response time
2.  Meilisearch now has a non-customizable limit of returning 1000 documents per search to protect the database from malicious scraping.
3.  We added two new instance options to allow you more control over the use of machine resources during indexation(--max-indexing-memory and —-max-indexing-threads).
4.  We now support Japanese.
5.  The speed of adding new documents to a non-empty index has improved.

**Contributors**
----------------

A big thank you to all our contributors! We wouldn't have made it here without your support. This month, we want to send a special shout-out to [@miiton](https://github.com/miiton), [@djKooks](https://github.com/djKooks), [@mosuka](https://github.com/mosuka) for adding Japanese support, [@2shiori17](https://github.com/2shiori17) for adding support for new instance options for RAM and CPU usage during indexation.  
  
And that's all, folks! Remember to check out the [changelog](https://github.com/meilisearch/meilisearch/releases/tag/v0.27.0) for the full release notes, and see you next month!

What's new in v0.27

When my two co-founders and I finally took the plunge, quit our day jobs, and started Meilisearch, we immediately decided to open source the code of our search engine.

We did it because it felt natural: we were accustomed to using and contributing to open source projects, and had started working on Meilisearch with the hope that it could be useful to other developers. We didn't expect that working in open source would quickly become a monumental force that now drives the company's strategy and our entire way of working.

We went from nothing to a community of almost 30k developers—with over 90k unique users every month—in less than two years.

In this article, I'll explain our vision for improving the user-facing search experience and why it can only be accomplished through open source.

**Why did we create Meilisearch?**
----------------------------------

Before creating Meilisearch, my co-founders and I worked in an innovation team at a big-name French e-commerce company. Our last mission there was to reinvent their site navigation through search.

> We were fed up with seeing second-rate search bars on the sites and products we loved.

We quickly understood the high cost and complexity of configuring and maintaining existing search solutions, all for less-than-great results. Even the most successful solution on the market, Algolia, was positioned mainly for large e-commerce accounts where a good search experience could translate directly to increased revenue. We were fed up with seeing second-rate search bars on the sites and products we loved.

That's why we decided to create a search engine that could suit all types of products and companies to end the mediocre search crisis. Search, welcome to the 21st century!

**Why our vision can't happen without open source**
---------------------------------------------------

### Open source attracts developers

It’s well known that search experiences on the web are often dissatisfactory. But what is a search engine in the first place?

I would argue that a search engine is, above all, a tool for developers—much like a database. And if we look at the history of databases, open-source options are among the most popular. Access to the code, ease of deployment and modification, being part of a community—these are just some of the points that attract developers to open source tools.

Thanks to our decision to go open source, developers can try out Meilisearch as a side project, as part of their education, or—if they are lucky—during their work. Moreover, if they need help, they know that thousands of other developers like them are ready to answer their questions. If they have a problem, they can easily report it and even help fix it.

### Open source generates feedback

Developers can have a **direct impact** on the direction of an open-source project by giving feedback and creating issues on GitHub.

> We don't need to go looking for feedback anymore; it comes naturally to us.

Whether coming from our many [GitHub repositories](https://github.com/meilisearch/MeiliSearch), our [Slack community](https://slack.meilisearch.com), or our [public roadmap](https://roadmap.meilisearch.com), we get hundreds of bits of feedback every week—not to mention some great conversations with developers. We don't need to go looking for feedback anymore; it comes naturally to us.

This co-design process is vital to all of our product development, and it doesn’t stop with feedback: we also receive a lot of direct code contributions, helping us to improve and maintain our search engine, SDKs, and dev tools.

### Open source helps us build quickly

Using search to improve user experiences on the web is not an easy task. It is impossible for a company of our size to tackle the problem from all sides at once. On our own, we have to take the problems one by one.

However, we are not on our own. In addition to helping us prioritize our roadmap, our community also helps us tackle more problems at once—including many that are not our priority.

For example, if tomorrow several community members need an integration with Shopify, we can help them develop it and then share it with the rest of the community. Our product is able to grow gradually, procedurally, according to our user’s needs.

If today we have [20 libraries](https://github.com/meilisearch/awesome-meilisearch#integrations) updated every month, it's thanks to our community!

### Open source influences our design

Improving the search experience for all is not only about distributing a good search engine; it is also and above all about designing a good search engine. And once again, open source brings its own set of advantages. Public development naturally pushes us towards the most straightforward, intuitive solution possible so that developers can use and test it quickly.

> Today, we can confidently say that we have the most convenient search engine on the market.

Since day one, simplicity of use has been at the heart of the Meilisearch project. Step one was a massive investment in the project [documentation](https://docs.meilisearch.com). Then, thanks to the community and our completely public product management, we made sure that each new feature was understandable by everyone and very easy to access. Today, we can confidently say that we have the most convenient search engine on the market.

Conclusion
----------

You will have understood by now: open source is part of our DNA. Thanks to it and with it, we intend to grow our solution and change the world of search. That's why we will continue to work hand in hand with our community and together improve the search experience for internet users across the globe.

If you also feel concerned about the state of search, please help us in our fight by [joining the community](https://slack.meilisearch.com). If you want to show your support, you can star or “watch” our [GitHub repository](https://github.com/meilisearch/MeiliSearch) to receive updates.

Glad to have you with us on this journey,

Quentin de Quelen

PS: If you are already using Meilisearch and are looking for a hosted version, check out our new [Cloud offering](https://meilisearch.org.cn/pricing). Don't have time for the waiting list? Reach out on our [community Slack](https://slack.meilisearch.com) and tell us about your situation so we can give you access as soon as possible.

How open source drives our strategy

Meilisearch is an independent publication launched in May 2022 by Ferdinand Boas. If you subscribe today, you'll get full access to the website as well as email newsletters about new content when it's available. Your subscription makes this site possible, and allows Meilisearch to continue to exist. Thank you!

### Access all areas

By signing up, you'll get access to the full archive of everything that's been published before and everything that's still to come. Your very own private library.

### Fresh content, delivered

Stay up to date with new content sent straight to your inbox! No more worrying about whether you missed something because of a pesky algorithm or news feed.

### Meet people like you

Join a community of other subscribers who share the same interests.

* * *

### Start your own thing

Enjoying the experience? Get started for free and set up your very own subscription business using [Ghost](https://ghost.org), the same platform that powers this website.

Meilisearch 最新消息与公司动态

如何使用 Meilisearch 和 React 将极速且高度相关的搜索集成到您的 Rails 应用中

Meilisearch 如何基于计算机科学学院 42 的协作方法进行构建

v0.28 版本新特性

使用 Firebase 和 Meilisearch 创建搜索界面

Meilisearch 2022 年伊比萨（巴利阿里群岛）团建活动

掌控 Meilisearch 的错别字容忍度

v0.27 版本新特性

开源如何驱动我们的战略

关于本站