Meilisearch Java SDK

Add meilisearch-java as a dependency in your project. Note that this SDK requires okhttp as a peer dependency.

Maven

Add the following to your <dependencies> section:

Gradle

Add the following to your dependencies block in build.gradle:

<!-- Maven -->
<dependency>
  <groupId>com.meilisearch.sdk</groupId>
  <artifactId>meilisearch-java</artifactId>
  <version>0.21.0</version>
  <type>pom</type>
</dependency>

<!-- Gradle -->
implementation 'com.meilisearch.sdk:meilisearch-java:0.21.0'

The SDK uses Gson by default. You can switch to Jackson or provide a custom implementation of the JsonHandler interface.

Using Jackson

Initialize your Config with a JacksonJsonHandler before creating the Client.

Implementing a Custom JsonHandler

Implement the following methods:

• String encode(Object o) throws Exception
• <T> T decode(Object o, Class<?> targetClass, Class<?>... parameters) throws Exception

// Using Jackson
import com.meilisearch.sdk.json.JacksonJsonHandler;

Config config = new Config("http://localhost:7700", "masterKey", new JacksonJsonHandler());
Client client = new Client(config);

// Using Custom Handler
Config config = new Config("http://localhost:7700", "masterKey", new myJsonHandler());
Client client = new Client(config);

The Index class provides a comprehensive suite of methods to manage various index settings. Most settings follow a pattern of get...Settings(), update...Settings(...), and reset...Settings().

Note that many update operations return a TaskInfo object, indicating that the operation is asynchronous and will be processed as a task by the Meilisearch engine.

To connect to a Meilisearch instance, instantiate the Client class by passing a Config object. The Config object contains the necessary connection details such as the host and API key.

// Assuming Config is already instantiated with host and apiKey
Client client = new Client(config);

For advanced search requirements, create a SearchRequest object and use its setter methods to configure parameters such as highlighting or match positions.

import com.meilisearch.sdk.SearchRequest;

// ...

SearchResult results = (SearchResult) index.search(
    new SearchRequest("of")
        .setShowMatchesPosition(true)
        .setAttributesToHighlight(new String[]{"title"})
);
System.out.println(results.getHits());

To implement pagination, use SearchRequest with setPage() and setHitsPerPage(). The result will be an instance of SearchResultPaginated.

import com.meilisearch.sdk.SearchResultPaginated;

// ...

SearchResultPaginated results = (SearchResultPaginated) index.search(
    new SearchRequest("wonder")
        .setPage(1)
        .setHitsPerPage(20)
);

A basic search can be performed by calling the index.search() method with a simple string query. The search is typo-tolerant by default.

import com.meilisearch.sdk.model.SearchResult;

// Meilisearch is typo-tolerant:
SearchResult results = index.search("carlo");
System.out.println(results);

To use filters in a search, you must first register the attributes you wish to filter by using updateFilterableAttributesSettings. This is a one-time operation that triggers an index rebuild. Once configured, you can pass a filter string to a SearchRequest.

// 1. Configure filterable attributes (perform once)
index.updateFilterableAttributesSettings(new String[] {
  "id",
  "genres"
});

// 2. Perform the search with a filter
index.search(
  new SearchRequest("wonder")
      .setFilter(new String[] {"id > 1 AND genres = Action"})
);

To add documents, initialize a Client with a Config object containing your Meilisearch host and master key. Access an Index using the client, and call addDocuments() with a JSON string representing your documents.

Note: If the index does not exist, Meilisearch will create it automatically upon the first document addition. The operation returns a taskUid which can be used to track the status (enqueued, canceled, processing, succeeded, or failed) via the Meilisearch task endpoint.

Client client = new Client(new Config("http://localhost:7700", "masterKey"));

// An index is where the documents are stored.
Index index = client.index("movies");

// If the index 'movies' does not exist, Meilisearch creates it when you first add the documents.
index.addDocuments(documents); // => { "taskUid": 0 }

The SDK is compatible with Meilisearch version v1.x.

JDK Requirements:

• SDK v1.x requires JDK 17 or above.