# Chapter 2: 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://127.0.0.1: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 '../small_movies.json'

Use

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

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://127.0.0.1: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

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://127.0.0.1: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.17"
  # 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.13.2")
  ]

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

About this SDK

If you have already downloaded the dataset and created the movies index, you can skip to the next section.

# 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 POST '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"
  ]'

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 POST 'http://localhost:7700/indexes/movies/settings/displayed-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
      "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 displayed attributes 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 POST 'http://localhost:7700/indexes/movies/settings/searchable-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
      "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 POST 'http://localhost:7700/indexes/movies/settings/stop-words' \
  -H 'Content-Type: application/json' \
  --data-binary '["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 POST 'http://localhost:7700/indexes/movies/settings/synonyms' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "winnie": ["piglet"], "piglet": ["winnie"]
    }'

This will set winnie and piglet as synonyms; searching for either word will show the same results.

You can read more about it in our dedicated guide.

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

← Chapter 1: Filtering and sorting Chapter 3: Getting ready for production →

# Chapter 2: Fine-tuning search results

# Ranking rules

# Displayed attributes

# Distinct attribute

# Searchable attributes

# The order of searchableAttributes

# Stop words

# Synonyms

# The order of `searchableAttributes`