Announcing Meilisearch v0.13.0  

=================================

Meilisearch v0.13.0 introduces a bunch of new features and changes. Bugs have  
been fixed and some behavior have changed for more consistency, here what's new in meilisearch:

Placeholder search
------------------

  
We've been asked for a placeholder search feature a lot, and it's landed in  
v0.13.0. It allows you to perform a search without specifying query strings,  
and get "placeholder" search results. The results are sorted according to the  
ranking rules you specified, and it supports faceting and filtering.

Post Route search
-----------------

  
A new route has been added to allow you to perform search with a `POST` route instead of `GET`. This will improve performance for searches that require token  
authentication, by allowing [preflight request](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) caching.  
  
This is now the recommended way to perform searches with Meilisearch.

New settings behavior
---------------------

  
We have made a couple of changes to the way settings work in order to make them easier to use and intuitive. `searchableAttributes` and `displayedAttributes` now default to all attributes (`*` ). This means that unless you specify otherwise, all attributes will be searchable by default. This removes the need for the `acceptNewField`, that no longer exists.

Sys-info route removal
----------------------

  
We decided not to support the sys-info route anymore, and remove it. This was motivated by the fact that there already are better tools to do this job, and it was not worth the time maintaining this part of the code.

Check that Meilisearch is launched with the correct database version
--------------------------------------------------------------------

  
We added a check to ensure that Meilisearch is launched with a database that's compatible with the engine version. Meilisearch will refuse to start unless versions match.

Bug fixes
---------

*   `facetDistribution` returning the values in lowercase, instead of the correct case.
*   Bug that caused Meilisearch to add documents with the same document id twice, if they were added in the same batch.

Special thanks
--------------

  
We'd like to give a special thank to our external contributors on this release.  
Their involvement means a lot to us!

*   [@balajisivaraman](https://github.com/balajisivaraman) for his help on making our tests faster and cleaner
*   [@Rio](https://github.com/Rio) for his work on authentication and analytics
*   [@aeriksson](https://github.com/aeriksson) for finding and fixing typos in our code

If you feel like contributing, and don't know where to start, ping us on [slack](https://slack.meilisearch.com/).

What's new in 0.13.0

Value in Open #1 - PostHog

The v0.11 version of Meilisearch introduces a highly anticipated feature: **faceted search**. Every modern search experience includes faceted search. We were eager to offer this experience to our users, and we are excited to have finally achieved this critical step.

Faceted search
--------------

If you're not familiar: Faceted search lets you search by including or excluding some attributes from categories called facets. You have probably come across faceted search during your online consumerist life. It is often presented as a sidebar with checkboxes. Giving me, as a woman, the possibility to show only 8.5 size shoes and see my possible choices decrease to oblivion.

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

In this case the facet is `size`, the attribute is `UK 8 ½`, and the number of products found `2`

Faceted search is not easy to understand. It is often confused with Filters. However, filtering is used to filter the returned results by adding constraints. **Facets**, on the other hand, are used to categorize the data into subsets that will be searched upon: **they reduce the number of documents to process**.

We didn’t see any reason to reinvent the wheel; if you’re familiar with how Algolia does facets, you’ll see we’ve gone with a very similar API. We improved a bit on the usage to reduce furthermore all possible friction in the hope that it is accessible for all users.

To set up faceted search, only two steps are required:

**Add facets in the settings**. For an attribute to be used as a facet it must be added in the `attributesForFaceting` list.

```bash
$ curl \
  -X POST 'http://localhost:7700/indexes/movies/settings' \
  --data '{
      "attributesForFaceting": [
          "director",
          "genres"
      ]
  }'
```

**Declare** director and genres as **facets**.

**Use facets during search**. By using the query parameter `facetFilters` it is possible to add the chosen facets attributes to narrow down the results:

```bash
$ curl --get 'http://localhost:7700/indexes/movies/search' \
    --data-urlencode 'q=Get' \
    --data-urlencode 'facetFilters=["director:Jordan Peele"]'
```

Search for movies by a specific director

This is all explained in our [guide on Faceting](https://docs.meilisearch.com/reference/features/faceted_search.html#faceted-search).

SSL support
-----------

All the configuration options to enable SSL are now available.

[Learn more about it in our configuration guide.](https://docs.meilisearch.com/reference/features/configuration.html#ssl-authentication-path)

Max payload size
----------------

In the early versions of Meilisearch, there was no limit to the size of the body Meilisearch accepted. This version introduces the standard default limit of a **maximum payload of 10 Megabytes** and the possibility of changing the limit.

```bash
$ ./meilisearch --http-payload-size-limit=107374182400
```

Change the upload limit to 100 Megabytes

Improved analytics
------------------

To further understand how our users use Meilisearch and how to improve it, more analytics are added.

[A complete list can be found here.](https://docs.meilisearch.com/reference/features/configuration.html#analytics)

Users can deactivate analytics by using the following command line option:

```json
$ ./meilisearch --no-analytics
```

Conclusion
----------

Those are the main changes in this version. For a more thorough list, please visit the [changelogs of this version](https://github.com/meilisearch/MeiliSearch/blob/master/CHANGELOG.md#v011).

We are eager to hear some feedback. Feel free to come and [talk to us any way you prefer](https://docs.meilisearch.com/learn/what_is_meilisearch/contact.html). We are thrilled by all the support given to our search engine and the never-ending growth in users and stars.

Thanks a lot,

The Meilisearch team and the girl with big feet. 🦶

####

Meilisearch v0.11: What’s new?

> This is the spiritual sequel to our [Open Business Plan](/blog/meilisearch-open-business-plan-v0-1/)hese open documents are continuously iterated on in our publicly available [Project Handbook](https://www.notion.so/meilisearch/Project-Handbook-e818a836dd3f4df1bde7c3989c9a0ae4).

Being a young project, our values are not yet fully formed. As such, we take our value cues from established organizations that we are closely aligned with. To date, these are: Mozilla, World Wide Web Foundation, Open Organization (Red Hat) and the UN's Sustainable Development Goals.

With the decades of experience and thinking that has gone into the principles we've adopted from the giants, we found it difficult to add anything original or especially representative of Meilisearch as a company. But in the past week, a recurring theme in tech and open source circles resurfaced once more on the Rust Users forum: [Can technology be apolitical?](https://users.rust-lang.org/t/rust-says-tech-will-always-be-political/43627)

The Meilisearch team unanimously agrees that the answer to this question is a resounding **'no'**. For some apt argumentation in favor of this conclusion, see the posts of [XAMPPRocky](https://users.rust-lang.org/t/rust-says-tech-will-always-be-political/43627/15?u=erlend_sh), [kornel](https://users.rust-lang.org/t/rust-says-tech-will-always-be-political/43627/17?u=erlend_sh) and [IsaacWoods](https://users.rust-lang.org/t/rust-says-tech-will-always-be-political/43627/27?u=erlend_sh).

> _XAMPPRocky said:_  
>   
> The Rust project is a real world community and organisation of people that works on building new versions and provides support. Which is done mostly by volunteers and a lot of whom are people who are underrepresented in tech. This organisation of volunteers has the agency to try to build the type of community it wants to be a part of and participate in. Since the very start the Rust project has had a [Code Of Conduct](https://www.rust-lang.org/policies/code-of-conduct) which states the following in the very first line.  
>   
> "We are committed to providing a friendly, safe and welcoming environment for all"  
>   
> This is an inherently political statement when we live in a world where there has been significant systemic injustice against people of colour and queer folk, both in tech and in the world at large. Working towards providing a welcoming environment for all requires an active voice to push back.

See also the [introductory text](https://firstdonoharm.dev/) of the Hippocratic License:

> Politics and software are so tangled that they cannot be reasonably separated. Consider the GPS software that tells you how to get to a restaurant; it’s also used to direct military drones to their targets. The facial recognition software  that unlocks your phone? It’s being  used to record, track, and target the activities of political  dissenters.

The goal of this declaration is to clearly state our strongly held principles, and the way we want to contribute to our environment. Thinking of technology as inherently apolitical is incompatible with our values as a company, and  we will focus our efforts on interacting and collaborating with those who share this principle with us.

* * *

Our Core Values (v0.1)
======================

Homegrown Principles
--------------------

As we mature as a project, our ideological identity will become more defined. We are starting with a single principle of our own making:

### Technology is political

Every new creation (for work, art, pleasure...) is necessarily based in previous knowledge, paradigms and tools that aren't anything but the  result of political and social constructions and history. The scope of  "what is possible" is necessarily defined by how our field has evolved  in a determined economic and political context, and any intention to transform it is necessarily political.

By acknowledging this, we recognize that neutrality is not an option for us as a values-driven company and participant in the open source movement.

Mozilla Manifesto
-----------------

We are committed to an internet that catalyzes collaboration among diverse communities working together for the common good.

We are inextricably linked to the Mozilla Foundation through our deep involvement with Rust. We greatly admire the Mozilla foundation’s work and we commit ourselves to upholding the 10 principles set forth in their [Manifesto](https://www.mozilla.org/en-US/about/manifesto/). Especially relevant to us are principles 5-9:

> **Principle 5**  
> Individuals must have the ability to shape the internet and their own experiences on it.

> **Principle 6**  
> The effectiveness of the internet as a public resource depends upon interoperability (protocols, data formats, content), innovation and decentralized participation worldwide.

> **Principle 7**  
> Free and open source software promotes the development of the internet as a public resource.

> **Principle 8**  
> Transparent community-based processes promote participation, accountability and trust.

> **Principle 9**  
> Commercial involvement in the development of the internet brings many benefits; a balance between commercial profit and public benefit is critical.

Contract for The Web
--------------------

We endorse the [Contract for The Web](https://contractfortheweb.org/). Most relevant to us are its Company Principles (addendum in \[brackets\]):

> **Principle 4**  
> Make \[essential technology on\] the internet affordable and accessible to everyone

> **Principle 5**  
> Respect and protect people’s privacy and personal data to build online trust

> **Principle 6**  
> Develop technologies that support the best in humanity and challenge the worst

Open Organization
-----------------

We adopt the [Open Organization Definition](https://opensource.com/open-organization/resources/open-org-definition) by Red Hat in its entirety:

*   Transparency ([Project Handbook](https://www.notion.so/meilisearch/Project-Handbook-e818a836dd3f4df1bde7c3989c9a0ae4) and [Open Business Plan](/blog/meilisearch-open-business-plan-v0-1/)   Inclusivity ([Contact us - Communication conventions](https://docs.meilisearch.com/learn/what_is_meilisearch/contact.html))
*   Adaptability
*   Collaboration (Contribution Guidelines coming soon)
*   Community ([To open source, and beyond!](/blog/to-open-source-and-beyond/)N Sustainable Development Goals
--------------------------------

As a distributed, internet-based project, it can feel like we are one step removed from the “real world” and our impact on it. But as technology becomes ever more pervasive in our economy, infrastructure and communities, our actions have very real and immediate consequences.

We acknowledge our place in the interconnected world, and in our own small way we are committed to its betterment. None of our activities should have adverse effects on the [UN Sustainable Development Goals](https://www.un.org/sustainabledevelopment/sustainable-development-goals/), and we'll do what we can to advance Goals 8, 9 and 10 (addendum in \[brackets\]):

> **Goal 8**  
> Decent Work and Economic Growth; Sustainable economic growth will require societies to create the conditions that allow people to have quality jobs.

> **Goal 9**  
> Industry, Innovation, and Infrastructure; Investments in \[technological, open source\] infrastructure are crucial to achieving sustainable development

> **Goal 10**  
> Reduced Inequalities; To reduce inequalities, policies should be universal in principle, paying attention to the needs of disadvantaged and marginalized populations.

Meilisearch Values v0.1: Tech is political

> This is the first of a series of posts that will present our publicly developed [Project Handbook](https://www.notion.so/meilisearch/Project-Handbook-e818a836dd3f4df1bde7c3989c9a0ae4).

Any open source project with the intention to commercialize its value creation should be able to answer this question: **How will you make money?**

Seth Godin's "[The Modern Business Plan](https://seths./blog/2010/05/the-modern-business-plan/)" provides a very useful, prose-focused template that lends itself well to consumption by the general public. This is the v0.1 release of our _Open Business Plan_.

> It’s not clear to me why business plans are the way they are, but  they’re often misused to obfuscate, bore and show an ability to comply with expectations. If I want the real truth about a business and where  it’s going, I’d rather see something else. I’d divide the modern  business plan into five sections:  
>   
> **1\. Truth**  
> **2\. Assertions**  
> **3\. Alternatives**  
> **4\. People**  
> **5\. Money**

Truth
-----

> The truth section describes the world as it is.  Footnote if you want to, but tell me about the market you are entering, the needs that already exist, the competitors in your space, technology standards, the way others have succeeded and failed in the past. The more specific the better. The more ground knowledge the better. The more visceral the stories, the better. The point of this section is to be sure that you’re clear about the way you see the world, and that you and I agree on your assumptions. This section isn’t partisan, it takes no positions, it just states how things are. Truth can take as long as you need to tell it. It can include spreadsheets, market share analysis and anything I need to know about how the world works.

If you want to set up an advanced content search for your website or app _today_, the leading options are [Algolia](https://docs.meilisearch.com/learn/what_is_meilisearch/comparison_to_alternatives.html#meilisearch-vs-algolia) and [Elastic](/blog/why-should-you-use-meilisearch-over-elasticsearch/) both great products, but neither can service a large segment of small to medium-sized businesses that are operating on a tight budget and/or need an easily maintainable setup for on-premises management.

We are not setting out to _kill_, _crush_ or _destroy_ our competitors. We are here to _question_, _challenge_, and _elevate_ the status quo.

Meili SAS is in large part modeling itself after Algolia and Elastic. We also take loads of inspiration from the business strategies of WordPress, Discourse, Sentry, CockroachDB and TimescaleDB. Like them, we are building a [Commercial Open Source Company](https://coss.media/coss-company-value-creation-capture-fundamentals/).

One of our most important competitive advantages is [Rust](https://www.rust-lang.org/). It enables us to confidently engineer the highly complex machinery of a search engine without crippling risk of technical debt or dead-ends. With Rust we can fearlessly explore the next frontier of search, safe in the knowledge that our code can always be refactored without bringing the whole foundation down.

Assertion
---------

> The assertions section is your chance to describe how you’re going to change things. We will do X, and then Y will happen. We will build Z with this much money in this much time. We will present Q to the market and the market will respond by taking this action. This is the heart of the modern business plan. The only reason to launch a project is to change something, and I want to know what you’re going to do and what impact it’s going to have.

We are going to spend the next year building _trust_, starting with an extensive **developer community**. We intend to rally this community around our out-in-the-open construction of Meilisearch as the easiest search engine of its kind to set up and modify to your application's needs.

Eventually, customers will get to choose between the instant value of SaaS, or the full control of self-hosted.

SaaS will be our initial focus as a company. It's the more proven model available to us. But we won't build any exclusives into our offering; any search feature we build for our SaaS offering will either be open source or source-available (i.e. freely available for non-commercial use; purchasable license for commercial use).

### Incentives for self-hosting

We intend to structure our business in a way that incentivizes a continued investment in the self-hosting capabilities of Meilisearch. Many open source companies with a SaaS offering end up with inverse incentives to continue improving their user-facing installation story because it competes with their SaaS business. By exploring fair ways to monetize our on-premises offering in commercial contexts we will ensure an ongoing equilibrium in our incentives.

### Self-hosting as a self-negotiator on pricing

A SaaS product that can be alternatively self-hosted with ease is inherently pricing-transparent. When discerning customers can effortlessly compare the experience of our managed SaaS versus our on-premises package, it keeps our pricing honest.

Alternatives
------------

> Of course, this \[assertion\] section will be incorrect. You will make  assertions that won’t pan out. You’ll miss budgets and deadlines and  sales. So the alternatives section tells me what you’ll do if that happens. How much flexibility does your product or team have? If your assertions don’t pan out, is it over?

The likes of Elastic, CockroachDB and GitLab have proven that there is not a singular best option for product delivery. Many customers just want the simplicity of SaaS, but many others **must** have on-premise services. We do not yet know which there will be more appetite for when it comes to Meilisearch, but we are prepared to follow the path of least resistance.

People
------

> The people section rightly highlights the key element… who is on your team, who is going to join your team. ‘Who’ doesn’t mean their resume, who means their attitudes and abilities and track record in shipping.

[Meet the team](https://meilisearch.notion.site/MeiliSearch-Team-b7f24733f4944fa9b09fd518d6fc3eff) (WIP)

Money
-----

> And the last section is all about money. How much do you need, how will you spend it, what does cash flow look like, P&Ls, balance sheets, margins and exit strategies.

We raised a pre-seed round in may, and are backed by LocalGlobe, Seedcamp and Kima. We have already partnered with industry heavyweights like Louis Vuitton and [Platform.sh](http://platform.sh/).

Next step is to create pages similar to these:

*   [https://docs.opencollective.com/help/about/investors](https://docs.opencollective.com/help/about/investors)
*   [https://docs.opencollective.com/help/about/the-open-collective-way/core-contributors-compensation](https://docs.opencollective.com/help/about/the-open-collective-way/core-contributors-compensation)

* * *

We hope you enjoyed this _[very early](https://en.wikipedia.org/wiki/Release_early,_release_often)_ v0.1.0 release of our Open Business Plan. You'll notice that Seth's article asks for several items of information that we have not yet addressed here. We hope to share more over time, but this requires more dialogue with our investors and other stakeholders.

Please let us know what information you'd most like us to share, and we will prioritize it. Come talk to us in the comments on [/r/opensource](https://www.reddit.com/r/opensource/comments/gv7kht/meilisearch_open_business_plan_v01/), [/r/rust](https://www.reddit.com/r/rust/comments/gv7ugp/meilisearch_open_business_plan_v01/), or find us on our [default community channels](https://docs.meilisearch.com/learn/what_is_meilisearch/contact.html).

> Interested in what Meilisearch could do for your business? If you [answer this survey](https://meilisearch.typeform.com/to/tsTOTw) you will be the first to know when our initial service offering is operational.

Meilisearch - Open business plan v0.1

Integrate a relevant search bar to your documentation
=====================================================

You might have noticed the search bar in [our documentation](https://docs.meilisearch.com/).

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

MeiliSearch docs search bar demo

And you are probably wanting the same for your own documentation!

This tutorial will guide you through the steps of building a relevant and powerful search bar for your documentation 🚀

1.  Run a MeiliSearch Instance
2.  Scrape your content
3.  Integrate the Search Bar

Run a MeiliSearch Instance
--------------------------

First of all, you need your documentation content to be scraped and pushed into a MeiliSearch instance.

You can install and run MeiliSearch on your machine using `curl`.

```bash
$ curl -L https://install.meilisearch.com | sh
$ ./meilisearch --master-key=myMasterKey

```

There are [other ways to install MeiliSearch](https://docs.meilisearch.com/reference/features/installation.html#download-and-launch).

MeiliSearch is open-source and can run either on your server or on any cloud provider.

> **Note:** The host URL and the API key you will provide in the next steps correspond to the credentials of this MeiliSearch instance.  
> In the example above, the host URL is `http://localhost:7700` and the API key is `myMasterKey`.

Scrape your Content
-------------------

The Meili team provides and maintains a [scraper tool](https://github.com/meilisearch/docs-scraper) to automatically read the content of your website and store it into an index in MeiliSearch.

### Configuration File

The scraper tool needs a configuration file to know what content you want to scrape, this is done by providing selectors (e.g. the HTML tag).

Here is an example of a basic configuration file:

```json
{
  "index_uid": "docs",
  "start_urls": ["https://www.example.com/doc/"],
  "sitemap_urls": ["https://www.example.com/sitemap.xml"],
  "stop_urls": [],
  "selectors": {
    "lvl0": {
      "selector": ".docs-lvl0",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": {
      "selector": ".docs-lvl1",
      "global": true,
      "default_value": "Chapter"
    },
    "lvl2": ".docs-content .docs-lvl2",
    "lvl3": ".docs-content .docs-lvl3",
    "lvl4": ".docs-content .docs-lvl4",
    "lvl5": ".docs-content .docs-lvl5",
    "lvl6": ".docs-content .docs-lvl6",
    "text": ".docs-content p, .docs-content li"
  }
}

```

The `index_uid` field is the index identifier in your MeiliSearch instance in which your website content is stored. The scraping tool will create a new index if it does not exist.

The `docs-content` class is the main container of the textual content in this example. Most of the time, this tag is a `<main>` or an `<article>` HTML element.

`lvlX` selectors should use the standard title tags like `h1`, `h2`, `h3`, etc. You can also use static classes. Set a unique `id` or `name` attribute to these elements.

Every searchable `lvl` elements outside this main documentation container (for instance, in a sidebar) must be `global` selectors. They will be globally picked up and injected to every document built from your page.

If you use VuePress for your documentation, you can check out the [configuration file](https://github.com/meilisearch/documentation/blob/master/.vuepress/docs-scraper/docs-scraper.config.json) we use in production. In our case, the main container is `theme-default-content` and the selector the titles and sub-titles are `h1`, `h2`...

### Run the Scraper

You can run the scraper with Docker. With our local MeiliSearch instance set up at the first step, we run:

```bash
$ docker run -t --rm \
    --network=host \
    -e MEILISEARCH_HOST_URL='http://localhost:7700' \
    -e MEILISEARCH_API_KEY='myMasterKey' \
    -v <absolute-path-to-your-config-file>:/docs-scraper/config.json \
    getmeili/docs-scraper:latest pipenv run ./docs_scraper config.json

```

> **Note:** If you don't want to use Docker, here are [other ways to run the scraper](https://github.com/meilisearch/docs-scraper#installation-and-usage).

`<absolute-path-to-your-config-file>` should be the **absolute** path of your configuration file defined at the previous step.

The API key you must provide should have the permissions to add documents into your MeiliSearch instance. In a production environment, we recommend providing the private key instead of the master key, as it is safer and it has enough permissions to perform such requests.

_More about [MeiliSearch authentication](https://docs.meilisearch.com/reference/features/authentication.html)._

> **Tip:** We recommend running the scraper at each new deployment of your documentation, [as we do for the MeiliSearch's one](https://github.com/meilisearch/documentation/blob/master/.github/workflows/gh-pages-scraping.yml).

Integrate the Search Bar
------------------------

If your documentation is not a VuePress application, you can skip the "For a VuePress Documentation" section and go directly to "For All Kinds of Documentation".

### For a VuePress Documentation

If you use VuePress for your documentation, we provide a [VuePress plugin](https://github.com/meilisearch/vuepress-plugin-meilisearch). This plugin is used in production in the MeiliSearch documentation.

![VuePress plugin example](https://unable-actionable-car.media.strapiapp.com/vuepress_plugin_example_ba1e4b4668.png)

VuePress plugin example

In your VuePress project:

```bash
$ yarn add vuepress-plugin-meilisearch
# or
$ npm install vuepress-plugin-meilisearch

```

In your `config.js` file:

```js
module.exports = {
  plugins: [
    [
      "vuepress-plugin-meilisearch",
      {
        "hostUrl": "<your-meilisearch-host-url>",
        "apiKey": "<your-meilisearch-api-key>",
        "indexUid": "docs"
      }
    ],
  ],
}

```

The `hostUrl` and the `apiKey` fields are the credentials of the MeiliSearch instance. Following on from this tutorial, they are respectively `http://localhost:7700` and `myMasterKey`.

`indexUid` is the index identifier in your MeiliSearch instance in which your website content is stored. It has been defined in the config file.

These three fields are mandatory, but more [optional fields are available](https://github.com/meilisearch/vuepress-plugin-meilisearch#customization) to customize your search bar.

> **Warning:** Since the configuration file is public, we strongly recommend providing the MeiliSearch public key in a production environment, which is enough to perform search requests.  
>   
> Read more about [MeiliSearch authentication](https://docs.meilisearch.com/reference/features/authentication.html#authentication).

### For All Kinds of Documentation

If you don't use VuePress for your documentation, we provide a [front-end SDK](https://github.com/meilisearch/docs-searchbar.js) to integrate a powerful and relevant search bar to any documentation website.

![docs-searchbar.js example](https://unable-actionable-car.media.strapiapp.com/docs_searchbar_example_83b1557e12.png)

docs-searchbar.js example

```html
<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docs-searchbar.js@{version}/dist/cdn/docs-searchbar.min.css" />
  </head>

  <body>
    <input type="search" id="search-bar-input">
    <script src="https://cdn.jsdelivr.net/npm/docs-searchbar.js@{version}/dist/cdn/docs-searchbar.min.js"></script>
    <script>
      docsSearchBar({
        hostUrl: '<your-meilisearch-host-url>',
        apiKey: '<your-meilisearch-api-key>',
        indexUid: 'docs',
        inputSelector: '#search-bar-input',
        debug: true // Set debug to true if you want to inspect the dropdown
      });
    </script>
  </body>
</html>

```

The `hostUrl` and the `apiKey` fields are the credentials of the MeiliSearch instance. Following on from this tutorial, they are respectively `http://localhost:7700` and `myMasterKey`.

`indexUid` is the index identifier in your MeiliSearch instance in which your website content is stored. It has been defined in the config file.  
`inputSelector` is the `id` attribute of the HTML search input tag.

> **Warning:** We strongly recommend providing the MeiliSearch public key in a production environment, which is enough to perform search requests.  
> Read more about [MeiliSearch authentication](https://docs.meilisearch.com/reference/features/authentication.html).

The default behavior of this library fits perfectly for a documentation search bar, but you might need [some customizations](https://github.com/meilisearch/docs-searchbar.js#customization).

> **Note:** For more concrete examples, you can check out this [basic HTML file](https://github.com/meilisearch/docs-searchbar.js/blob/master/scripts/playground.html) or [this more advanced Vue file](https://github.com/meilisearch/vuepress-plugin-meilisearch/blob/master/MeiliSearchBox.vue).

What's next?
------------

At this point you should have a working search engine on your website, congrats! 🎉

You can check [this tutorial](https://docs.meilisearch.com/running-production/) if you now want to run MeiliSearch in production!

How to integrate a relevant search bar to your documentation

A quick introduction
--------------------

Hopefully, you already know that [MeiliSearch](https://github.com/meilisearch/MeiliSearch) is a powerful and fast open-source search engine built in [Rust](https://www.rust-lang.org). It was designed to provide users with a very useful and customizable search experience including out-of-the-box features such as typo-tolerance, filtering, and synonyms for any kind of project.

Running a Meilisearch instance for testing purposes is incredibly easy and can be done in [many ways](https://docs.meilisearch.com/learn/tutorials/getting_started.html): using Docker, brew, aptitude, binaries, a simple curl, or even the source code. If you are new to MeiliSearch, we suggest that you take a tour around the documentation.

Using MeiliSearch on your own machine for your weekend project is fun, let's agree on that. However, you may want to go live and deploy a project in production, to take it to the next level. What steps and details would you need to **deploy MeiliSearch in production** and ensure it is **safe and ready to use**?

Get your MeiliSearch ready for production
-----------------------------------------

For this tutorial, we will be using a Debian 10 server, running on DigitalOcean. You can easily try it on your own, with plans starting at $5/month. And if you want some credits to start running your MeiliSearch and are not already registered on DigitalOcean, you can get $100 for free using [this referral link](https://m.do.co/c/7c67bd97e101).

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

*   An up-to-date server that runs Debian 10
*   An ssh keypair to connect to that machine
*   MeiliSearch is a database which means that it needs a file system it can write to, and which must be persistent.

> _TIPS:_ learn how to connect via SSH to your [DigitalOcean droplet](https://www.digitalocean.com/docs/droplets/how-to/connect-with-ssh/) or any [Linux or windows server](https://phoenixnap.com/kb/ssh-to-connect-to-remote-server-linux-or-windows)

Step 1: Install MeiliSearch
---------------------------

Installing and running MeiliSearch is easy and straightforward. In order to keep this tutorial as simple as possible, let's use a script that will carry out the installation process. It will copy a binary of MeiliSearch to your machine and enable you to use it immediately.

Once you are logged in into your machine via SSH, ensure your system and its dependencies are up-to-date before proceeding with the installation.

```bash
# Update the list of available packages and their versions
$ apt update
# Install curl which is required to install MeiliSearch in the next step
$ apt install curl -y
# Install MeiliSearch latest version from the script
$ curl -L https://install.meilisearch.com | sh

```

> The different options to achieve a MeiliSearch installation are detailed in **[this guide](https://docs.meilisearch.com/reference/features/installation.html#download-and-launch)**.  
> It is important to know that there are different ways to get MeiliSearch running on your machine. As an open source project, you can always compile the latest stable release of MeiliSearch from the source code to ensure the binary uses your achitecture in the best possible way.

You can always check the latest MeiliSearch stable version, and get MeiliSearch for the Operating System of your choice, by visiting the following link:

**[Latest MeiliSearch Stable Version](https://github.com/meilisearch/MeiliSearch/releases/latest)**

MeiliSearch is finally installed and ready to use. To make it accessible from everywhere in your system, move the binary file into your system binaries folder:

```bash
# Move the MeiliSearch binary to your system binaries
$ mv ./meilisearch /usr/bin/

```

You can now start using MeiliSearch! In your terminal, run:

```bash
$ meilisearch

# --- Expected output for v0.10.1 ---
888b     d888          d8b 888 d8b  .d8888b.                                    888
8888b   d8888          Y8P 888 Y8P d88P  Y88b                                   888
88888b.d88888              888     Y88b.                                        888
888Y88888P888  .d88b.  888 888 888  "Y888b.    .d88b.   8888b.  888d888 .d8888b 88888b.
888 Y888P 888 d8P  Y8b 888 888 888     "Y88b. d8P  Y8b     "88b 888P"  d88P"    888 "88b
888  Y8P  888 88888888 888 888 888       "888 88888888 .d888888 888    888      888  888
888   "   888 Y8b.     888 888 888 Y88b  d88P Y8b.     888  888 888    Y88b.    888  888
888       888  "Y8888  888 888 888  "Y8888P"   "Y8888  "Y888888 888     "Y8888P 888  888

[2020-05-04T11:47:13Z INFO  meilisearch] Database path: "./data.ms"
[2020-05-04T11:47:13Z INFO  meilisearch] Start server on: "127.0.0.1:7700"

```

Step 2: Run MeiliSearch as a service
------------------------------------

In Linux environments, a `service` is a process that can be launched when the operating system is booting and which will keep running in the background. One of its biggest advantages is making your program available at any moment. Even if some execution problems or crashes occur, the service will be restarted and your program will be run again.

> If you are new to services and `systemd`, you can learn more about the basics of Linux services [here](https://www.hostinger.com/tutorials/manage-and-list-services-in-linux/).

In Debian and other Linux distributions, `systemd` allows you to create and manage your own custom services. In order to make sure that MeiliSearch will always respond to your requests, you can build your own service. This way, you will ensure its availability in case of a crash or in case of system reboot. If any of these occur, `systemd` will automatically restart MeiliSearch.

### 2.1 Create a service file

Service files are text files that tell your operating system how to run your program, and when. They live in the `/etc/systemd/system` directory, and your system will load them at boot time. In this case, let's use a very simple service file that will run MeiliSearch on port `7700`.

To run MeiliSearch in a production environment, use the `--env` flag. To generate a master key that will let MeiliSearch create reading and writing keys, use the `--master-key` flag. With those keys, you can easily control who can access or create new documents, indexes, or change the configuration. You can change the `Master Key` to any value in the following command. However, for security concerns, it's better to choose a safe and random key, never share it and, just, **keep it safe**.

```bash
$ cat << EOF >/etc/systemd/system/meilisearch.service
[Unit]
Description=MeiliSearch
After=systemd-user-sessions.service

[Service]
Type=simple
ExecStart=/usr/bin/meilisearch --http-addr 127.0.0.1:7700 --env production --master-key Y0urVery-S3cureAp1K3y

[Install]
WantedBy=default.target
EOF


```

> For more information on MeiliSearch authentication and API keys see the **[Authentication Docs](https://docs.meilisearch.com/reference/features/authentication.html)**. For more information on MeiliSearch options and flags see the **[MeiliSearch configuration options](https://docs.meilisearch.com/reference/features/configuration.html)**

As for now, it is not time yet to expose your MeiliSearch instance to the external world. To keep running it safely inside your own environment, make it available locally at `127.0.0.1`. This means that only programs running on your machine are allowed to make requests to your MeiliSearch instance.

### 2.2. Enable and start service

The service file you just built is all you need for creating your service. Now you must `enable` it to tell the operating system that we want it to run MeiliSearch at every boot. You can then `start` the service to make it run immediately. Ensure everything is working smoothly by checking the service `status`.

```bash
# Set the service meilisearch
$ systemctl enable meilisearch

# Start the meilisearch service
$ systemctl start meilisearch

# Verify that the service is actually running
$ systemctl status meilisearch

-# --- Expected output ---
● meilisearch.service - MeiliSearch
   Loaded: loaded (/etc/systemd/system/meilisearch.service; enabled; vendor preset: enabled)
   Active: active (running) since Fri 2020-04-10 14:27:49 UTC; 1min 8s ago
 Main PID: 14960 (meilisearch)

```

At this point, MeiliSearch is installed and running. It is protected from eventual crashes, system restarts, and most of the problems it could find while running. But it is still hidden and protected inside the walls (or firewalls) of your machine, and unreachable from the outside world. You can stop here if all the requests you do to MeiliSearch are done by another application living in the same machine.

But you probably want to open your MeiliSearch to the outside world, and for now, it is isolated. Let's fix that in a safe way.

Step 3: Secure and finish your setup. Using a Reverse Proxy, domain name and HTTPS
----------------------------------------------------------------------------------

It's time to safely make your brand new MeiliSearch available to be requested from the outside world. For this purpose, you will use two of the main technologies available on the web: a Reverse Proxy and SSL/TLS.

### 3.1. Creating a Reverse Proxy with [Nginx](https://www.nginx.com/)

A reverse proxy is basically an application that will handle every communication between the outside world and your internal applications. Nginx will receive external HTTP requests and redirect them to MeiliSearch. When MeiliSearch has done its amazing job, it will communicate its response to Nginx, which will then transfer the latter to the user who originally sent the request. This is a common way to isolate and protect any application by adding a robust, secure, and fast gate-keeper such as Nginx, one of the safest and most efficient tools available online, and of course, open-source!

> Reverse proxies are very useful regarding security, performance, scalability, and logging concerns. If you are new to Reverse proxies, you may enjoy this article explaining the why and the how of [reverse proxies](https://www.keycdn.com/support/nginx-reverse-proxy).

Configuring Nginx as a proxy server is really simple. First of all, install it on your machine.

```bash
# Install Nginx on Debian
$ apt-get install nginx -y

```

First, deleting the default configuration file is important as the default port for HTTP, the `port 80`, is used by Nginx by default. Thus, trying to use it for MeiliSearch will create a conflict. Replace the default file by your own configuration file. You can also make MeiliSearch listen to another port by specifying it in the Nginx configuration file, but we will not cover this option in this tutorial.

```bash
# Delete the default configuration file for Nginx
$ rm -f /etc/nginx/sites-enabled/default

# Add your configuration file specifying the Reverse Proxy settings
$ cat << EOF > /etc/nginx/sites-enabled/meilisearch
server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name _;
    location / {
        proxy_pass  http://127.0.0.1:7700;
    }
}
EOF

```

Finally, enable and start the Nginx service again to make sure it is still available.

```bash
# Reload the operating system daemons / services
$ systemctl daemon-reload

# Enable and start Nginx service
$ systemctl enable nginx
$ systemctl restart nginx

```

MeiliSearch is now up, deployed in a production environment, using a safe API key, and being served by a Reverse Proxy Nginx. You should now be able to send requests to your server from the outside world. Open your web browser and visit: ([http://your-ip-address](http://your-ip-address)). The IP address is the same you used to connect to your machine via SSH in Step 1.

> If you want to learn more about using Nginx as a Reverse Proxy, see [this dedicated documentation](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/).

The only remaining problem is that MeiliSearch processes requests via HTTP without any additional security. The content that is being transmitted over HTTP could easily be read or modified by attackers, and someone could get full or partial access to your data. In order to prevent this to happen, it's important to use the HTTPS, which will enable you to use a SSL/TLS certificate, and securely transmit data.

### 3.2. Set up SSL/TLS for your MeiliSearch

SSL will let the user or client establish an authenticated connection to MeiliSearch. In this way, a user can verify server's identity before sending sensitive data or making any request to it. Then, data is sent in an encrypted way that only MeiliSearch server will be able to decrypt, providing you a fast, reliable, and automatic layer of security.

In most cases, when enabling SSL, you may want to use your own domain name (or a sub-domain). The first step you need to follow is to register your own domain name and change the DNS records. To make your domain name point to your newly installed MeiliSearch server, you just need to add an `A record` pointing to the IP address used to connect to your own server. This process is simple and fast but can vary for every domain name provider. Thus, we will not cover that process in this article.

> When you register a domain name and add an `A record`, you should be automatically able to request MeiliSearch directly by using that domain name.  
> To illustrate this, if you had registered your domain name `example.com`, requesting indexes would be done at [http://example.com/indexes](http://example.com/indexes)

Once your domain name has been set up, you are ready to configure SSL/TLS and use HTTPS. You have two different options to achieve this goal. The first one is using [Certbot](https://certbot.eff.org/), an amazing, free, and very easy to use tool. If you already have SSL certificates issued from a `Certificate Authority or CA` for your domain name, the second option covers the steps you need to follow. Then, you will be ready to use MeiliSearch safely in production!

#### 3.2. Option A: Certbot

Using certbot in your Linux server is very easy and straightforward. This tool will generate a free SSL/TLS certificate for your domain name, and automatically handle its installation on your server. The certbot documentation contains detailed instructions for many operating systems and servers, but we will follow the instructions for [Certbot on Debian with Nginx](https://certbot.eff.org/lets-encrypt/debianbuster-nginx).

First of all, install the packages on your system:

```bash
$ sudo apt-get install certbot python-certbot-nginx -y

```

Let's run the Certbot script to be guided through the installation process:

```bash
certbot --nginx

```

Enter your email address, agree to the Terms and Conditions, and input your domain name. You will then be prompted with these options:

```bash
Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: No redirect - Make no further changes to the webserver configuration.
2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
new sites, or if you're confident your site works on HTTPS. You can undo this
change by editing your web server's configuration.

```

We recommend that you choose option 2, to redirect HTTP to HTTPS and always use a secure connection. You should be able to request your domain name with SSL as in `https://example.com` or `https://example.com/indexes`.

#### 3.2. Option B: Custom SSL/TLS Certificates

When a `Certificate Authority` issues a SSL certificate for you, you receive at least two files with encrypted keys:

*   Your **certificate** (commonly named `your_domain_name.pem` or `example.pem`)
*   Your **key** (commonly named `your_domain_name.key` or `example.key`)

> `example.pem` and `example.key` will be used in the following examples. Make sure to replace `example` by the names of your own certificate files.

All you need to do is store the certificate files in a secure location and use appropriate file system security permissions. Then, set the location of the certificates in Nginx configuration. It is also strongly recommended to redirect all HTTP requests to HTTPS (port 80 to 443).

First, let's copy your certificate files in their conventional directory so the server can find them:

```bash
# Create a directory /etc/ssl/example to store the certificate files
$ mkdir -p /etc/ssl/example

# Move your files to /etc/ssl/example. We will suppose that your
# files are called example.pem and example.key

$ mv path-to-your-files/example.pem /etc/ssl/example/
$ mv path-to-your-files/example.key /etc/ssl/example/

```

Finally, we create a new Nginx configuration file, and restart the daemons and Nginx service

> Remember to replace `example.com` in both `server_name` fields with your **own domain name**

```bash

# Replace example.com in both `server_name` fields with your own domain name

$ cat << EOF > /etc/nginx/sites-enabled/meilisearch
server {
      listen 80 default_server;
      listen [::]:80 default_server;

      server_name example.com;

      return 301 https://\$server_name\$request_uri;
}
server {
    server_name example.com;

    location / {
        proxy_pass  http://127.0.0.1:7700;
    }

    listen [::]:443 ssl ipv6only=on;
    listen 443 ssl;

    access_log /var/log/nginx/nginx.vhost.access.log;
    error_log /var/log/nginx/nginx.vhost.error.log;
    ssl_certificate /etc/ssl/example/example.pem;
    ssl_certificate_key /etc/ssl/example/example.key;
}
EOF

$ systemctl restart nginx

```

Your SSL certificates should be working and Nginx should be able to find them. Every request to `http://example.com` will now be redirected to `https://example.com`

Conclusion
----------

You have followed the main steps to provide a safe and stable service. Your MeiliSearch instance should be up and running, in a safe environment and ready to stay available even when the most common issues occur. In addition, it is protected by a reverse proxy with your own domain name and API key, so your data and configuration are accessible only to trusted clients. Communication with your server is now encrypted. Furthermore, its identity will be verified every time before sending sensitive data in a fast and automated manner.

You are now ready to start using your **Production-ready MeiliSearch**!

MeiliSearch in production: taking it to the next level

We have just released our new version which development has been driven by our desire for simplicity of use.

We realized that some features were not easy to use because of design choices. The whole team gathered around the table and debated the API routes and their RESTfulness until everyone agreed on a proposal. We hope to strike a good balance between simplicity and customization.

So what is new in the v0.9?

*   Schema deletion!
*   Included web interface to try out your search
*   New settings handling
*   Simplified custom ranking rules
*   Added primary key
*   New built-in ranking rule names
*   Simplified authentication
*   Production and development mode
*   Bug fixes, syntax changes and, improvements

Schemaless
----------

The schemaless idea was in our mind for quite a while. When getting started, the user shouldn’t be required to specify how Meilisearch should handle every field, but only when their needs are really specific and out of the ordinary.  
Now, by default, Meilisearch will display every documents field, make them all searchable and will infer the document's primary key based on the provided documents structure.  
This solution causes way less friction when starting using Meilisearch.

Web interface
-------------

In the previous version, once you had started your Meilisearch engine and inserted some documents into it, the smooth experience stopped there. In order to try out the search, you had to either submit requests using curl or an SDK, either creating a front-end search bar connected to Meilisearch.

Now that a web interface is shipped with Meilisearch, all you need to do is open your web browser and enter Meilisearch’s address to visit it locally. This will lead you to a web page with a search bar that will allow you to search in a selected index.

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

Since the production environment requires an API-key for searching, the web interface is only available in development mode.

Settings
--------

Anything that isn’t necessary to make your Meilisearch instance up and running can now be configured in the settings.

For each setting there is a route, thus making it possible to only update a specific setting. The global setting route gives you the possibility to post a configuration file describing your customizations, which will facilitate the creation of similar Meilisearch instances based on the same settings.

#### Example

```json
{
  "rankingRules": [
      "typo",
      "words",
      "proximity",
      "attribute",
      "wordsPosition",
      "exactness",
      "desc(release_date)"
  ],
  "distinctAttribute": null,
  "searchableAttributes": [
      "title",
      "description",
      "uid"
  ],
  "displayedAttributes": [
      "title",
      "description",
      "release_date",
      "rank",
      "poster"
  ],
  "stopWords": null,
  "synonyms": {
      "wolverine": ["xmen", "logan"],
      "logan": ["wolverine", "xmen"]
  },
  "indexNewFields": false
}

```

[All the settings can be found here](https://docs.meilisearch.com/reference/api/settings.html)

Simplified custom ranking rules
-------------------------------

In the previous version, creating your own rules could be confusing. We simplified this task! All you have to do now is add an ascending (`asc()`) or descending (`desc()`) rule on one of your fields in the ranking rules list.

```json
 "rankingRules": [
      "typo",
      "words",
      "proximity",
      "attribute",
      "wordsPosition",
      "exactness",
      "desc(release_date)"
  ]

```

If you update your ranking rules following this example, you will note that your changes have been taken into account by Meilisearch immediately. This means that once all the other rules have been applied, Meilisearch will consider documents with more recent release\_date's more relevant than older ones.

Primary key
-----------

Meilisearch will try to infer the primary key from the documents you upload. This inference will search for the first field containing the string `id` in its attribute.  
Sometimes, it may happen that no key can be found. In such a case, Meilisearch is not able to infer it.

Since Meilisearch needs a primary key to store the documents, if the latter cannot be inferred, we have set up two alternative ways to communicate the primary key to Meilisearch.

*   By giving it on index creation :

```json
{
  "uid": "movies",
  "primaryKey": "movieUniqueName"
}
```
    
*   By giving it on document addition

```bash
curl -X POST 'http://localhost:7700/indexes/movies/documents?primaryKey=movieUniqueName' --data @movies.json
```



New ranking rules names
-----------------------

In the previous versions, ranking rules names were too long and could contain unnecessary special characters. From now on, they have been simplified. Here is the list of the new built-in ranking rules:

*   `typo`
*   `words`
*   `proximity`
*   `attribute`
*   `wordsPosition`
*   `exactness`

[Follow this guide to know more about what each ranking rules does](https://docs.meilisearch.com/learn/core_concepts/relevancy.html).

Simplified authentication
-------------------------

When adding a master key to Meilisearch, a private key and a public key are generated on launch.  
The public key only grants permission to the routes that execute searches and get documents.  
The private key grants access to every other route in Meilisearch except for the `GET /keys` route. As it returns both the public and private keys, this route is accessible only with the master key.

[Read this to learn more about authentication in Meilisearch](https://docs.meilisearch.com/reference/features/authentication.html).

Production and development mode
-------------------------------

When launching your Meilisearch instance, setting the environment is now available as an option.  
By default, the environment is set to development mode.

While in development mode, you don't have to provide a master key. In that case, every route is accessible without requiring any API key. You are also able to **access the web interface**.

While in production mode, if no master key is given, the instance will be considered unsafe for production and will not start.

Bug fixes, syntax changes, and improvements
-------------------------------------------

*   Removed dead-lock in the update system
*   Settings can be added even when no primary key is known
*   `POST /documents/delete` changed to `POST /documents/delete-batch`
*   Speed up the reindexing system
*   When no highlight is prompted during search there will be no `_highlighted` field in the returned documents
*   Removed `searchableAttributes` from the search query parameters.
*   To know the stats of an index the route is now: `GET /indexes/:index_uid/stats` and not `GET /stats/:index_uid`
*   Documents ids' can only contain the following characters: `A-Z a-z 0-9`, `-`, and `_`

Some adjustments on routes’ design we made are temporary choices we took in order to release a working version. The `/key` route, for example, although functional, is too simple and not tailored to developers’ common needs. We are currently thinking about how to handle it better, and we are open to any advice!

This version took us about three months to finish, taking into account that the v0.8.5 has not been officially released but added to the v0.9 release. We did a lot of work on process organization to ensure that everything would be ready at the same time: the core Meilisearch, the documentation, and the SDK.

We are thrilled about how these latest changes will improve the users' experience with Meilisearch. This release is the result of a lot of discussions among our contributors and us. We are eager to hear about your experience with Meilisearch. Any suggestion or feedback is more than welcome since those are the premises of a long-term and ambitious project that will be built upon the decisions we make today.

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

Meilisearch v0.9: What’s new?

As a Rails and Ruby lover, I often search for the gem that will perfectly cover my use case. When I need to solve a problem I'm having, I want to choose the _right one_, the most suitable solution.

Ruby gems are extensive libraries created inside the Ruby community. The best place to find a ready solution for any task is the website [rubygems.org](https://rubygems.org/), a public repository of gems that can be searched using the search box on the home page. RubyGems’ website is an efficient tool that facilitates the sharing and the installation of packages. But although its search bar is very helpful, I decided to create an [alternative search bar](https://rubygems.meilisearch.com/) more suited to our needs.

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

The search-as-you-type experience
---------------------------------

First, I wanted to implement a search-as-you-type experience. Which means:

*   a response time lower than 50 milliseconds
*   presenting all matching results immediately under the search box while the user is typing and without them pressing enter

That is not yet the case in the RubyGems' website since a new page is loaded each time a request is made.

The relevancy
-------------

You can get relevant and accurate results by using the RubyGems' search bar, but most of the time only by performing an Advanced Search, which is not always convenient. You have to decide what to fill in the different sections. Are you going to search for a specific package by entering its name (e.g. "devise") or find a package whose summary would match a keyword (e.g. "deployment")?

However, despite this functionality, you may not find gems that meet your needs. For example, if you enter "pagination" you would expect to see the gem "kaminari", which is the most popular gem for pagination among the RoR community, showing up in the results. Here is [the return we get from RubyGem's search bar](https://rubygems.org/search?utf8=%E2%9C%93&query=pagination) when submitting the keyword "pagination". As you can see, "kaminari" doesn’t appear before the 9th result.

Even when [refining the search](https://rubygems.org/search?utf8=%E2%9C%93&query=summary%3A+pagination+description%3A+pagination), the first result to show is "kanimari-core" which is not exactly the more appropriate and famous "kaminari" package we would like to find, but it’s still better than nothing.

Then if we do a search [containing a typo in the request](https://rubygems.org/search?utf8=%E2%9C%93&query=pagintion), like "pagintion", the page is displayed without any result and suggests you a similar word for your next search.

After this experience as a user, I aimed to create **a single search bar able to understand what you want and to instantly find it**!

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

Meilisearch checks all these points, and more!
----------------------------------------------

I've never implemented a search engine; I've never even used one, except a basic Elasticsearch instance with no configuration for a proof of concept. For that reason, all I needed was an easy-to-setup tool, able to handle both speediness and relevancy at the same time. That's why Meilisearch was a perfect fit for this project.

**[Meilisearch](https://github.com/meilisearch/MeiliSearch) is an ultra-relevant and fast search engine**. In other words, it can return the most relevant results of your dataset under 50 ms, and therefore it gives a strong sense of immediacy.

Plus, without the need to configure anything, it handles search miss-spelling: i.e. Typos. Try to submit "devose" instead of "devise" and Meilisearch will return "devise" as the first result.

Finally, **Meilisearch is open-source and integrates a simple [RESTful API](https://www.meilisearch.com/docs/reference/api/overview)**. You can seamlessly communicate with the API using cURL or [one of Meilisearch's wrappers](https://www.meilisearch.com/docs/learn/what_is_meilisearch/sdks).

Creating the alternative search bar
-----------------------------------

All the [gems data](https://rubygems.org/pages/data) are available on the RubyGems' website as a PostgreSQL dump file and are updated daily. Thus, I wrote a Ruby script to download the latest dataset, parse the PostgreSQL dump file, and push all the data into my Meilisearch instance. Of course, it uses the [meilisearch-ruby wrapper](https://github.com/meilisearch/meilisearch-ruby) to communicate with the API. This script is hosted in Heroku and runs every day thanks to the Heroku Scheduler.

About the Meilisearch instance, at Meili we manage an internal Kubernetes cluster, which is a handy tool to host demos like this one. For curious readers who would like to find out more, Meilisearch is quite [easy to download and run](https://www.meilisearch.com/docs/learn/getting_started/installation) by yourself (Homebrew, APT, Docker...).

Regarding HTML and CSS, I kept much of the original structure of the RubyGems' website. My intention was to develop a "search-as-you-type experience" in the same spirit as the original website. The front is deployed using GitHub Pages.

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

Easily improving the relevancy
------------------------------

Without having to set anything up, Meilisearch returns pretty relevant results. Our search engine can quickly find the most suitable packages when inputting gem names like "devise" or "faraday". Unfortunately, for now it’s not always the case with keywords.

Let’s get back to my "pagination" example. If I run the search again without configuring anything, the first result to be displayed by Meilisearch will be the [Pagination](https://rubygems.org/gems/pagination) gem. I don't see [Kaminari](https://rubygems.org/gems/kaminari) at all in the results. That’s because by default, finding a document with a requested word in the title takes precedence over a document with a requested word in the description. Since there are many gems containing "pagination" in their title in the dataset, it explains why Kaminari does not appear at all.

I needed Meilisearch to include the libraries popularity as well. In my dataset, the popularity of the Ruby gems is indicated by the number of downloads. I classified my gems in eight groups of fame (downloaded more than 50M times, more than 30M, and so forth) from `0` to `7`. The latter being considered as the most famous group.

I added this information to every document (i.e. gems) as a field named `fame`. Then, I integrated this rule in Meilisearch settings as a custom ranking rule.

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

Take a look at this snippet above. To put it simply, Meilisearch will execute one by one all of these rules (`_sum_of_typos`, `_number_of_words` ...) and sort your documents following this sequence. When I add my custom rule, i.e. `fame` in `rankingOrder` and `fame: 'dsc'` in `rankingRules`, I'm in fact asking Meilisearch to sort by fame in descendant order.

You might have noticed I have a second custom rule in the example: `total_downloads`, so that my results will be sorted by the number of downloads. But since I chose to place this rule at the end of the list, meaning it was considered less important than the other ones, it will be the last one to be applied. The order of sequence definitely matters.

I'm not going to give further details about the [Meilisearch default ranking rules](https://docs.meilisearch.com/learn/core_concepts/relevancy.html#ranking-rules), even if it’s a particularly interesting topic. Describing how our search engine works deserves indeed a separate article of its own! 😉 _Spoiler alert: Meilisearch uses a bucket sort!_

Now, if you type a [global keyword like "pagination"](https://rubygems.meilisearch.com/?q=pagination) you will find Kaminari in the first place; and if you try again with a [less famous gem name like "pagy" for example](https://rubygems.meilisearch.com/?q=pagy) you will still get the gem you expected! 🎉

Meilisearch + you = 💛
----------------------

These minor settings were really easy to integrate, and your projects might require the same kind of behavior.

Here are some useful links if you want to get ready for your own Meilisearch experience:

*   the [documentation](https://docs.meilisearch.com/)
*   the [Meilisearch's repository](https://github.com/meilisearch/MeiliSearch) on GitHub: support Meili by starring it! ⭐️
*   the [repository of this project](https://github.com/meilisearch/finding-rubygems/)

If you are interested in our project, how it works, or if you have any feedback, do not hesitate to [contact the team](mailto:bonjour@meilisearch.com)! 😁

Meilisearch latest news and company updates