Fine-tuning search results

Meilisearch is designed to offer a great search experience out of the box, but sometimes you need to customize it to better fit your needs. You can alter the search behavior for each index using the settings object.

For this chapter, we will be using a collection of movies as our dataset.

To follow along, first click this link to download the file: movies.json. Then, move it into your working directory and run the following command:

curl \
  -X POST 'http://localhost:7700/indexes/movies/documents' \
  -H 'Content-Type: application/json' \
  --data-binary @movies.json

npm install meilisearch

Or, if you are using yarn

yarn add meilisearch

Import

require syntax:

const { MeiliSearch } = require('meilisearch')
const movies = require('./movies.json')

import syntax:

import { MeiliSearch } from 'meilisearch'
import movies from './movies.json'

Use

const client = new MeiliSearch({ host: 'http://localhost:7700' })
client.index('movies').addDocuments(movies)
  .then((res) => console.log(res))

About this SDK

pip3 install meilisearch

import meilisearch
import json

client = meilisearch.Client('http://localhost:7700')

json_file = open('movies.json')
movies = json.load(json_file)
client.index('movies').add_documents(movies)

About this SDK

Using meilisearch-php with the Guzzle HTTP client:

composer require meilisearch/meilisearch-php \
    guzzlehttp/guzzle \
    http-interop/http-factory-guzzle:^1.0

<?php

require_once __DIR__ . '/vendor/autoload.php';

use MeiliSearch\Client;

$client = new Client('http://localhost:7700');

$movies_json = file_get_contents('movies.json');
$movies = json_decode($movies_json);

$client->index('movies')->addDocuments($movies);

About this SDK

Maven Add the following code to the <dependencies> section of your project:

<dependency>
  <groupId>com.meilisearch.sdk</groupId>
  <artifactId>meilisearch-java</artifactId>
  <version>0.7.2</version>
  <type>pom</type>
</dependency>

Gradle Add the following line to the dependencies section of your build.gradle:

implementation 'com.meilisearch.sdk:meilisearch-java:0.7.2'

import com.meilisearch.sdk;
import java.nio.file.Files;
import java.nio.file.Path;

Path fileName = Path.of("movies.json");
String moviesJson = Files.readString(fileName);
Client client = new Client(new Config("http://127.0.0.1:7700", "masterKey"));
Index index = client.index("movies");
index.addDocuments(moviesJson);

About this SDK

$ bundle add meilisearch

require 'json'
require 'meilisearch'

client = MeiliSearch::Client.new('http://localhost:7700')

movies_json = File.read('movies.json')
movies = JSON.parse(movies_json)

client.index('movies').add_documents(movies)

About this SDK

go get -u github.com/meilisearch/meilisearch-go

package main

import (
  "os"
  "encoding/json"
  "io/ioutil"

  "github.com/meilisearch/meilisearch-go"
)

func main() {
  client := meilisearch.NewClient(meilisearch.ClientConfig{
    Host: "http://localhost:7700",
  })

  jsonFile, _ := os.Open("movies.json")
  defer jsonFile.Close()

  byteValue, _ := ioutil.ReadAll(jsonFile)
  var movies []map[string]interface{}
  json.Unmarshal(byteValue, &movies)

  _, err := client.Index("movies").AddDocuments(movies)
  if err != nil {
      panic(err)
  }
}

About this SDK

dotnet add package MeiliSearch

using System.IO;
using System.Text.Json;
using Meilisearch;
using System.Threading.Tasks;
using System.Collections.Generic;

namespace Meilisearch_demo
{
    public class Movie
    {
        public string Id { get; set; }
        public string Title { get; set; }
        public string Poster { get; set; }
        public string Overview { get; set; }
        public IEnumerable<string> Genres { get; set; }
    }

    internal class Program
    {
        static async Task Main(string[] args)
        {
            MeilisearchClient client = new MeilisearchClient("http://localhost:7700", "masterKey");
            var options = new JsonSerializerOptions
            {
                PropertyNameCaseInsensitive = true
            };

            string jsonString = await File.ReadAllTextAsync("movies.json");
            var movies = JsonSerializer.Deserialize<IEnumerable<Movie>>(jsonString, options);

            var index = client.Index("movies");
            await index.AddDocumentsAsync<Movie>(movies);
        }
    }
}

About this SDK

  [dependencies]
  meilisearch-sdk = "0.20"
  # futures: because we want to block on futures
  futures = "0.3"
  # serde: required if you are going to use documents
  serde = { version="1.0",   features = ["derive"] }
  # serde_json: required in some parts of this guide
  serde_json = "1.0"

Documents in the Rust library are strongly typed.

#[derive(Serialize, Deserialize)]
struct Movie {
  id: String,
  title: String,
  poster: String,
  overview: String,
  release_date: i64,
  genres: Vec<String>
}

You will often need this Movie struct in other parts of this documentation. (you will have to change it a bit sometimes) You can also use schemaless values, by putting a serde_json::Value inside your own struct like this:

#[derive(Serialize, Deserialize)]
struct Movie {
  id: String,
  #[serde(flatten)]
  value: serde_json::Value,
}

Then, add documents into the index:

use meilisearch_sdk::{
  indexes::*,
  client::*,
  search::*,
  settings::*
};
use serde::{Serialize, Deserialize};
use std::{io::prelude::*, fs::File};
use futures::executor::block_on;

fn main() { block_on(async move {
  let client = Client::new("http://localhost:7700", "masterKey");

  // reading and parsing the file
  let mut file = File::open("movies.json")
    .unwrap();
  let mut content = String::new();
  file
    .read_to_string(&mut content)
    .unwrap();
  let movies_docs: Vec<Movie> = serde_json::from_str(&content)
    .unwrap();

  // adding documents
  client
    .index("movies")
    .add_documents(&movies_docs, None)
    .await
    .unwrap();
})}

About this SDK

Add this to your Package.swift:

  dependencies: [
    .package(url: "https://github.com/meilisearch/meilisearch-swift.git", from: "0.14.1")
  ]

  let path = Bundle.main.url(forResource: "movies", withExtension: "json")
  let documents: Data = Data(contentsOf: path)
  client.index("movies").addDocuments(documents: documents) { (result) in
      switch result {
      case .success(let task):
          print(task)
      case .failure(let error):
          print(error)
      }
  }

About this SDK

dependencies:
  meilisearch: ^0.3.1

import 'package:meilisearch/meilisearch.dart';
import 'dart:io';
import 'dart:convert';

var client = MeiliSearchClient('http://localhost:7700', 'masterKey');

final jsonFile = await File('movies.json').readAsString();
final movies = json.decode(jsonFile);
await client.index('movies').addDocuments(movies);

About this SDK

Ranking rules

Meilisearch sorts search responses based on an array of rules called rankingRules, which is part of the settings object.

The order of the rankingRules array matters: the first rule has the most impact and the last rule has the least. This is the default order:

"rankingRules": [
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "exactness"
]

You can read more about each ranking rule and what it does in our dedicated guide.

In this example, we change the order of the ranking rules for the movies index by moving exactness to the top:

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/ranking-rules' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "exactness",
    "words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "release_date:asc",
    "rank:desc"
  ]'

client.index('movies').updateRankingRules([
  'exactness',
  'words',
  'typo',
  'proximity',
  'attribute',
  'sort',
  'release_date:asc',
  'rank:desc'
])

client.index('movies').update_ranking_rules([
    'exactness',
    'words',
    'typo',
    'proximity',
    'attribute',
    'sort',
    'release_date:asc',
    'rank:desc'
])

$client->index('movies')->updateRankingRules([
  'exactness',
  'words',
  'typo',
  'proximity',
  'attribute',
  'sort',
  'release_date:asc',
  'rank:desc'
]);

Settings settings = new Settings();
settings.setRankingRules(new String[]
{
  "exactness",
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "release_date:asc",
  "rank:desc"
});
client.index("movies").updateSettings(settings);

client.index('movies').update_ranking_rules([
  'exactness',
  'words',
  'typo',
  'proximity',
  'attribute',
  'sort',
  'release_date:asc',
  'rank:desc'
])

rankingRules := []string{
  "exactness",
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "release_date:asc",
  "rank:desc",
}
client.Index("movies").UpdateRankingRules(&rankingRules)

await client.Index("movies").UpdateRankingRulesAsync(new string[] {
  "exactness",
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "release_date:asc",
  "rank:desc"
});

let ranking_rules = [
  "exactness",
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "release_date:asc",
  "rank:desc"
];

client
  .index("movies")
  .set_ranking_rules(&ranking_rules)
  .await
  .unwrap();

let rankingRules: [String] = [
  "exactness",
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "release_date:asc",
  "rank:desc"
]
client.index("movies").updateRankingRules(rankingRules) { (result) in
  switch result {
  case .success(let task):
    print(task)
  case .failure(let error):
    print(error)
  }
}

await client.index('movies').updateRankingRules([
  'exactness',
  'words',
  'typo',
  'proximity',
  'attribute',
  'sort',
  'release_date:asc',
  'rank:desc'
]);

You can read more about ranking rules in our dedicated guide.

Displayed attributes

By default, all attributes are displayed in search results but the displayedAttributes array in the settings object allows you to change that.

If you only want to display the title, poster, and overview for the movies index:

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/displayed-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "title",
    "overview",
    "poster"
  ]'

client.index('movies').updateDisplayedAttributes([
  'title',
  'overview',
  'poster'
])

client.index('movies').update_displayed_attributes([
    'title',
    'overview',
    'poster'
])

$client->index('movies')->updateDisplayedAttributes([
  'title',
  'overview',
  'poster'
]);

Settings settings = new Settings();
settings.setDisplayedAttributes(new String[]
{
      "title",
      "overview",
      "poster"
});
client.index("movies").updateSettings(settings);

client.index('movies').update_displayed_attributes([
  'title',
  'overview',
  'poster'
])

displayedAttributes := []string{
  "title",
  "overview",
  "poster",
}
client.Index("movies").UpdateDisplayedAttributes(&displayedAttributes)

await client.Index("movies").UpdateDisplayedAttributesAsync(new string[] {
  "title",
  "overview",
  "poster"
});

let displayed_attributes = [
  "title",
  "overview",
  "poster",
];

client
  .index("movies")
  .set_displayed_attributes(&displayed_attributes)
  .await
  .unwrap();

let displayedAttributes: [String] = ["title", "overview", "poster"]
client.index("movies").updateDisplayedAttributes(displayedAttributes) { (result) in
     switch result {
     case .success(let task):
         print(task)
     case .failure(let error):
         print(error)
     }
 }

await client.index('movies').updateDisplayedAttributes([
  'title',
  'overview',
  'poster'
]);

You can read more about displayed attributes in our dedicated guide.

Distinct attribute

If you have groups of almost identical documents, you may wish to only return one of them per search. distinctAttribute is a tool in the settings object that allows you to do just that.

When you set one of your attributes as the distinctAttribute, Meilisearch will not return more than one document with the same value associated to that attribute.

Suppose you have an e-commerce dataset with an index on jackets. There are several identical items with minor variations in color.

[
  {
    "id": 1,
    "description": "Leather jacket",
    "brand": "Lee jeans",
    "color": "brown",
    "product_id": "123456"
  },
  {
    "id": 2,
    "description": "Leather jacket",
    "brand": "Lee jeans",
    "color": "black",
    "product_id": "123456"
  },
  {
    "id": 3,
    "description": "Leather jacket",
    "brand": "Lee jeans",
    "color": "blue",
    "product_id": "123456"
  }
]

If you searched for lee leather jacket with the default settings, you would get all three documents. But if you set product_id as the distinctAttribute, Meilisearch will only return one of those jackets.

You can read more about the distinct attribute in our dedicated guide.

Searchable attributes

Documents in Meilisearch are composed of multiple fields. By default, Meilisearch looks for matches in every field, but the searchableAttributes array in the settings object allows you to change that.

For example, if you search the movies index for 2012, Meilisearch searches for 2012 in every field: the title, overview, release_year, and so on. If you just want to search in the title field:

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/searchable-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '["title"]'

client.index('movies').updateSearchableAttributes([
  'title'
])

client.index('movies').update_searchable_attributes([
    'title'
])

$client->index('movies')->updateSearchableAttributes(['title']);

Settings settings = new Settings();
settings.setSearchableAttributes(new String[]
{
  "title"
});

client.index('movies').update_searchable_attributes([
  'title'
])

searchableAttributes := []string{
  "title",
}
client.Index("movies").UpdateSearchableAttributes(&searchableAttributes)

await client.Index("movies").UpdateSearchableAttributesAsync(new string[] {
  "title"
});

let searchable_attributes = [
  "title"
];

client
  .index("movies")
  .set_searchable_attributes(&searchable_attributes)
  .await
  .unwrap();

let searchableAttributes: [String] = ["title"]
client.index("movies").updateSearchableAttributes(searchableAttributes) { (result) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client.index('movies').updateSearchableAttributes([
  'title'
]);

Meilisearch will now only consider title during search, and you will see fewer results.

NOTE

Meilisearch will still highlight matches in other fields, but they won’t be used to compute results.

The order of searchableAttributes

The order of the searchableAttributes array corresponds to the order of importance of the attributes.

  [
    "overview",
    "title",
  ]

With the above order, matching words found in the overview field will have a higher impact on relevancy than the same words found in title. You can read more about this in our relevancy guide.

Stop words

Meilisearch allows you to ignore certain words in your search queries by adding them to the stopWords array. A good example is the word the in English.

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/stop-words' \
  -H 'Content-Type: application/json' \
  --data-binary '["the"]'

client.index('movies').updateStopWords(['the'])

client.index('movies').update_stop_words(['the'])

$client->index('movies')->updateStopWords(['the']);

Settings settings = new Settings();
settings.setStopWords(new String[]
{
  "the"
});
client.index("movies").updateSettings(settings);

client.index('movies').update_stop_words(['the'])

stopWords := []string{"the"}
client.Index("movies").UpdateStopWords(&stopWords)

await client.Index("movies").UpdateStopWordsAsync(new string[] {
  "the"
});

let stop_words = ["the"];
client
  .index("movies")
  .set_stop_words(&stop_words)
  .await
  .unwrap();

let stopWords: [String] = ["the"]
client.index("movies").updateStopWords(stopWords) { (result) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client.index('movies').updateStopWords(['the']);

If you search for the cat after running the above command, Meilisearch will consider your search query to be cat, improving the speed and relevancy of your search.

You can read more about stop words in the API reference.

Synonyms

The synonyms array lets you associate certain words in your dataset, telling Meilisearch that they are equivalent and interchangeable.

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/synonyms' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "winnie": ["piglet"], 
    "piglet": ["winnie"]
  }'

client.index('movies').updateSynonyms({
  winnie: ['piglet'],
  piglet: ['winnie']
})

client.index('movies').update_synonyms({
  'winnie': ['piglet'],
  'piglet': ['winnie']
})

$client->index('movies')->updateSynonyms([
  'winnie' => ['piglet'],
  'piglet' => ['winnie']
]);

Settings settings = new Settings();
HashMap<String, String[]> synonyms = new HashMap<String, String[]>();
synonyms.put("winnie", new String[] {"piglet"});
synonyms.put("piglet", new String[] {"winnie"});
settings.setSynonyms(synonyms);
client.index("movies").updateSettings(settings);

client.index('movies').update_synonyms({
  winnie: ['piglet'],
  piglet: ['winnie']
})

synonyms := map[string][]string{
  "winnie":  []string{"piglet"},
  "piglet":  []string{"winnie"},
}
client.Index("movies").UpdateSynonyms(&synonyms)

var newSynonyms = new Dictionary<string, IEnumerable<string>>
{
    { "winnie", new string[] { "piglet" } },
    { "piglet", new string[] { "winnie" } },
};
await client.Index("movies").UpdateSynonymsAsync(newSynonyms);

let mut synonyms = std::collections::HashMap::new();
synonyms.insert(String::from("winnie"), vec![String::from("piglet")]);
synonyms.insert(String::from("piglet"), vec![String::from("winnie")]);

client
  .index("movies")
  .set_synonyms(&synonyms)
  .await
  .unwrap();

let synonyms: [String: [String]] = [
   "winnie": ["piglet"],
   "piglet": ["winnie"]
]
 client.index("movies").updateSynonyms(synonyms) { (result) in
     switch result {
     case .success(let task):
         print(task)
     case .failure(let error):
         print(error)
     }
 }

await client.index('movies').updateSynonyms({
  winnie: ['piglet'],
  piglet: ['winnie']
});

This will set winnie and piglet as synonyms. Searching for either won't always return the same results due to factors like typos and splitting the query.

You can read more about it in our dedicated guide.

Typo tolerance

Meilisearch is typo tolerant by default. It will help you find relevant search results even if you make spelling mistakes or typos, e.g., searching for swaj instead of swan.

The typoTolerance object allows you to:

• Enable or disable the typo tolerance feature
• Configure the minimum word size for typos
• Disable typos on specific words
• Disable typos on specific attributes

Meilisearch accepts one typo for query terms containing 5 or more characters by default. If you search the movies index for swaj, you will not get any results.

curl \
  -X PATCH 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "minWordSizeForTypos": { "oneTypo": 4 }
}'

client.index('movies').update_typo_tolerance({
  'minWordSizeForTypos': {
    'oneTypo': 4
  }
})

$client->index('books')->updateTypoTolerance([
  'minWordSizeForTypos' => [ 
    'oneTypo' => 4 
  ]
]);

client.index('movies').update_typo_tolerance({ min_word_size_for_typos: { one_typo: 4 } })

client.index("movies").UpdateTypoTolerance({
  MinWordSizeForTypos: meilisearch.MinWordSizeForTypos{
    OneTypo: 4,
  },
})

var typoTolerance = new TypoTolerance {
  MinWordSizeTypos = new TypoTolerance.TypoSize {
    OneTypo = 4
  }
};

await client.Index("movies").UpdateTypoToleranceAsync(typoTolerance);

The above code sample sets the minimum word size for one typo to 4 characters. If you search for swaj now, you should get some results.

You can read more about typo tolerance in our dedicated guide.

Faceting

Meilisearch allows you to create faceted search interfaces, refining search results based on broad categories called facets. Like filters, you need to add the attributes you want to use as facets to filterableAttributes.

When creating a faceted search interface, it is helpful to display how results are distributed between the different categories. For example, a user might want to know how many of their results have a genre of comedy and how many have a genre of horror. Meilisearch supports this with the facets search parameter.

Using the faceting settings, you can configure the maximum number of facet values returned for each facet.

Suppose your results contain the following values for the genres facet: Action, Adventure, Science Fiction, and Comedy. After running the below code sample, you would only see how results are distributed between the Action and Adventure genres.

curl \
  -X PATCH 'http://localhost:7700/indexes/movies/settings/faceting' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "maxValuesPerFacet": 2
  }'

You can read more about faceting in our dedicated guide.

Pagination

By default, Meilisearch returns 1000 results per search. This limit protects your database from malicious scraping.

The code sample below sets this limit to 500:

curl \
  -X PATCH 'http://localhost:7700/indexes/movies/settings/pagination' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "maxTotalHits": 500
  }'

Now, users won't be able to access search results beyond 500.

You can read more about pagination in our dedicated guide.

The next chapter tackles more advanced topics, including security and data backup.