# Quick start

In this quick start we will walk you through setting up Meilisearch, adding documents, performing your first search, using the search preview, and adding a search bar.

All that is required is a command line (opens new window) for installation, and some way to interact with Meilisearch afterwards (e.g. cURL (opens new window) or one of our SDKs).

Let's get started!

# Step 1: Setup and installation

We'll start with downloading and installing Meilisearch. You have the option to install Meilisearch locally or deploy it over a cloud service.

# Local installation

# Cloud deploy

To deploy Meilisearch on a cloud service, follow one of our dedicated guides:

# Running Meilisearch

On successfully running Meilisearch, you should see the following response:

888b     d888          d8b 888 d8b                                            888
8888b   d8888          Y8P 888 Y8P                                            888
88888b.d88888              888                                                888
888Y88888P888  .d88b.  888 888 888 .d8888b   .d88b.   8888b.  888d888 .d8888b 88888b.
888 Y888P 888 d8P  Y8b 888 888 888 88K      d8P  Y8b     "88b 888P"  d88P"    888 "88b
888  Y8P  888 88888888 888 888 888 "Y8888b. 88888888 .d888888 888    888      888  888
888   "   888 Y8b.     888 888 888      X88 Y8b.     888  888 888    Y88b.    888  888
888       888  "Y8888  888 888 888  88888P'  "Y8888  "Y888888 888     "Y8888P 888  888

Database path:       "./data.ms"
Server listening on: "127.0.0.1:7700"

Congratulations! You're ready to move on to the next step!

# Step 2: Add documents

For this quick start, 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 the downloaded file into your working directory.

Open a new terminal window 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.0</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.0'

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.15"
  # 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. You have to implement the Document trait on a struct to be able to use it with Meilisearch.

#[derive(Serialize, Deserialize, Debug)]
struct Movie {
  id: String,
  title: String,
  poster: String,
  overview: String,
  release_date: i64,
  genres: Vec<String>
}
impl Document for Movie {
  type UIDType = String;
  fn get_uid(&self) -> &Self::UIDType { &self.id }
}

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, Debug)]
struct Movie {
  id: String,
  #[serde(flatten)]
  value: serde_json::Value,
}

impl Document for Movie {
  type UIDType = String;
  fn get_uid(&self) -> &Self::UIDType { &self.id }
}

Then, add documents into the index:

use meilisearch_sdk::{
  indexes::*,
  document::*,
  client::*,
  search::*,
  progress::*,
  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.0")
  ]

  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

Meilisearch stores data in the form of discrete records, called documents. Documents are grouped into collections, called indexes.

The previous command added documents from movies.json to a new index called movies. After adding documents, you should receive a response like this:

{
    "uid": 0,
    "indexUid": "movies",
    "status": "enqueued",
    "type": "documentAddition",
    "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

Most database operations in Meilisearch are asynchronous. This means that rather than being processed instantly, API requests are added to a queue and processed one at a time.

Use the returned uid to check the status of your documents:

curl \
  -X GET 'http://localhost:7700/indexes/movies/tasks/0'

If the document addition is successful, the response should look like this:

{
   "uid":0,
   "indexUid":"movies",
   "status":"succeeded",
   "type":"documentAddition",
   "details":{
      "receivedDocuments":19547,
      "indexedDocuments":19547
   },
   "duration":"PT0.030750S",
   "enqueuedAt":"2021-12-20T12:39:18.349288Z",
   "startedAt":"2021-12-20T12:39:18.352490Z",
   "finishedAt":"2021-12-20T12:39:18.380038Z"
}

If the status field has the value enqueued or processing, all you have to do is wait a short time and check again. Proceed to the next step once the task status has changed to succeeded.

# Step 3: Search

Now that you have Meilisearch setup, you can start searching!

curl \
  -X POST 'http://127.0.0.1:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "botman" }'

You can build a Query and execute it later:

let query: Query = Query::new(&movies)
  .with_query("botman")
  .build();

let results: SearchResults<Movie> = client.index("movies").execute_query(&query).await.unwrap();

You can build a Query and execute it directly:

let results: SearchResults<Movie> = Query::new(&movies)
  .with_query("botman")
  .execute()
  .await
  .unwrap();

You can search in an index directly:

let results: SearchResults<Movie> = client.index("movies").search()
  .with_query("botman")
  .execute()
  .await
  .unwrap();

About this SDK

In the above code sample, the parameter q represents the search query. The documents you added in step two will be searched for text that matches botman.

Meilisearch response:

{
  "hits": [
    {
      "id": "29751",
      "title": "Batman Unmasked: The Psychology of the Dark Knight",
      "poster": "https://image.tmdb.org/t/p/w1280/jjHu128XLARc2k4cJrblAvZe0HE.jpg",
      "overview": "Delve into the world of Batman and the vigilante justice tha",
      "release_date": "2008-07-15"
    },
    {
      "id": "471474",
      "title": "Batman: Gotham by Gaslight",
      "poster": "https://image.tmdb.org/t/p/w1280/7souLi5zqQCnpZVghaXv0Wowi0y.jpg",
      "overview": "ve Victorian Age Gotham City, Batman begins his war on crime",
      "release_date": "2018-01-12"
    },
    …
  ],
  "nbHits":66,
  "exhaustiveNbHits":false,
  "query":"botman",
  "limit":20,
  "offset":0,
  "processingTimeMs":12
}

By default, Meilisearch only returns the first 20 results for a search query. This can be changed using the limit parameter.

# Step 4: Search preview

Meilisearch offers a web interface where you can preview search results. It comes with a search bar that allows you to search a selected index. You can access it in your browser at http://127.0.0.1:7700 any time Meilisearch is running.

Screenshot of Meilisearch's search preview indicating the indexes dropdown on the upper right corner

If you have multiple indexes, you can switch between them using the indexes dropdown.

# Step 5: Front-end integration

The only step missing now is adding a search bar to your project. The easiest way of achieving this is to use instant-meilisearch (opens new window): a developer tool that generates all the components needed to start searching.

To learn more about instant-meilisearch, refer to its documentation (opens new window) located in the project repository.

# What's next?

You now know all the basics: how to install Meilisearch, create an index, add documents, check the status of an asynchronous task, and perform a search.

To keep going, continue to the Meilisearch 101 for a guided overview of the main features, or check out the API references to dive right in!

← Contact us Chapter 1: Filtering and sorting →