Skip to main content
This guide walks you through setting up Meilisearch with Java.

Prerequisites

  • Java 17 or higher
  • Maven or Gradle
  • A Meilisearch instance (Cloud or self-hosted)

1. Install the SDK

<dependency>
  <groupId>com.meilisearch.sdk</groupId>
  <artifactId>meilisearch-java</artifactId>
  <version>0.17.1</version>
</dependency>

2. Connect to Meilisearch

import com.meilisearch.sdk.Client;
import com.meilisearch.sdk.Config;

public class Main {
    public static void main(String[] args) {
        Client client = new Client(new Config(
            System.getenv("MEILISEARCH_URL"),
            System.getenv("MEILISEARCH_API_KEY")
        ));
    }
}
Set your environment variables:
export MEILISEARCH_URL="https://your-instance.meilisearch.io"  # or http://localhost:7700
export MEILISEARCH_API_KEY="your_api_key"
Get a free Cloud instance →

3. Add documents

import com.meilisearch.sdk.Index;
import com.meilisearch.sdk.model.TaskInfo;

// Define your document class
class Movie {
    public int id;
    public String title;
    public String[] genres;
    public int year;

    public Movie(int id, String title, String[] genres, int year) {
        this.id = id;
        this.title = title;
        this.genres = genres;
        this.year = year;
    }
}

// Add documents
Movie[] movies = {
    new Movie(1, "The Matrix", new String[]{"Action", "Sci-Fi"}, 1999),
    new Movie(2, "Inception", new String[]{"Action", "Thriller"}, 2010),
    new Movie(3, "Interstellar", new String[]{"Drama", "Sci-Fi"}, 2014)
};

Index index = client.index("movies");
TaskInfo task = index.addDocuments(new Gson().toJson(movies));

// Wait for indexing to complete
client.waitForTask(task.getTaskUid());
import com.meilisearch.sdk.SearchRequest;
import com.meilisearch.sdk.model.SearchResult;

SearchResult results = index.search("matrix");

System.out.println(results.getHits());
// [{id=1, title=The Matrix, genres=[Action, Sci-Fi], year=1999}]

5. Search with filters

First, configure filterable attributes:
index.updateFilterableAttributesSettings(new String[]{"genres", "year"});
Then search with filters:
SearchRequest searchRequest = new SearchRequest("matrix")
    .setFilter(new String[]{"genres = \"Sci-Fi\"", "year > 2000"});

SearchResult results = index.search(searchRequest);

Full example

import com.meilisearch.sdk.*;
import com.meilisearch.sdk.model.*;
import com.google.gson.Gson;

public class Main {
    public static void main(String[] args) throws Exception {
        // Connect
        Client client = new Client(new Config(
            System.getenv("MEILISEARCH_URL"),
            System.getenv("MEILISEARCH_API_KEY")
        ));

        // Add documents
        String documents = "[" +
            "{\"id\": 1, \"title\": \"The Matrix\", \"year\": 1999}," +
            "{\"id\": 2, \"title\": \"Inception\", \"year\": 2010}," +
            "{\"id\": 3, \"title\": \"Interstellar\", \"year\": 2014}" +
        "]";

        Index index = client.index("movies");
        TaskInfo task = index.addDocuments(documents);
        client.waitForTask(task.getTaskUid());

        // Search
        SearchResult results = index.search("inter");
        System.out.println(results.getHits());
    }
}

Next steps

Full-text search

Configure ranking and relevancy

Filtering

Add filters and facets

AI-powered search

Add semantic search

API reference

Explore all search parameters

Resources