For the latest stable version, please use Spring Data Meilisearch 0.12.0!

Getting Started

Spring Data Meilisearch is a single-module Spring Data integration for applications that want to access Meilisearch through familiar Spring configuration, mapping, operations, and repository abstractions.

Applications configure the integration explicitly through Spring Java configuration or its XML namespace; the project does not provide Spring Boot auto-configuration. The quickest way to get started is to declare the dependency, extend MeilisearchConfiguration, annotate your domain type with @Document, and create a MeilisearchRepository for the aggregate root.

Requirements

  • JDK 17 or newer.

  • A reachable Meilisearch instance.

  • An API key with the permissions required for your application if the Meilisearch instance has authentication enabled.

The module does not claim one minimum Meilisearch version for every operation. ID-list document retrieval requires Meilisearch 1.14 or later, and sorted document listing requires 1.16 or later; use a server version that supports the APIs your application calls.

Maven Coordinates

<dependencies>
  <dependency>
    <groupId>io.vanslog</groupId>
    <artifactId>spring-data-meilisearch</artifactId>
    <version>${spring-data-meilisearch.version}</version>
  </dependency>
</dependencies>

Define spring-data-meilisearch.version in your POM as the exact version you intend to use. Choose a released version from the Maven Central artifact page.

For a development snapshot, set the same property to the exact -SNAPSHOT version published for the development branch, including the suffix, and add the Central snapshots repository to your POM:

<repositories>
  <repository>
    <id>central-snapshots</id>
    <name>Central Snapshots</name>
    <url>https://central.sonatype.com/repository/maven-snapshots/</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

Java Configuration

The usual starting point is a configuration class that extends MeilisearchConfiguration and enables repository scanning.

package com.example.movies;

import io.vanslog.spring.data.meilisearch.client.ClientConfiguration;
import io.vanslog.spring.data.meilisearch.config.MeilisearchConfiguration;
import io.vanslog.spring.data.meilisearch.repository.config.EnableMeilisearchRepositories;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

@Configuration
@ComponentScan("com.example.movies")
@EnableMeilisearchRepositories(basePackages = "com.example.movies")
class MeilisearchConfig extends MeilisearchConfiguration {

    @Override
    public ClientConfiguration clientConfiguration() {
        return ClientConfiguration.builder()
                .connectedTo("http://localhost:7700")
                .withApiKey(System.getenv("MEILISEARCH_API_KEY"))
                .build();
    }
}

MeilisearchConfiguration registers the standard Spring Data Meilisearch beans, including the client, mapping context, converter, and the meilisearchTemplate / meilisearchOperations bean. MeilisearchRepository is the recommended repository base interface for this module’s current repository feature set. For local development with authentication, prefer a scoped API key exposed through MEILISEARCH_API_KEY instead of using the Meilisearch master key in application code. For a development instance without authentication, pass withApiKey("") explicitly (see ClientConfiguration Builder).

Domain Type

Annotate persistent types with @Document and choose the target index uid explicitly.

@Document maps the type to the movies index but does not itself create it. Repository bootstrap applies settings by default, and Meilisearch can create a missing index during that settings update. If the index is still absent, the first save submits documents through an API that creates it with id as the primary key. To control index creation and its primary key explicitly, see index operations and settings.

package com.example.movies;

import io.vanslog.spring.data.meilisearch.annotations.Document;

import org.springframework.data.annotation.Id;

@Document(indexUid = "movies")
public record Movie(@Id String id, String title, String description) {
}

Repository Usage

package com.example.movies;

import io.vanslog.spring.data.meilisearch.repository.MeilisearchRepository;

public interface MovieRepository extends MeilisearchRepository<Movie, String> {
}
package com.example.movies;

import org.springframework.stereotype.Service;

@Service
class MovieService {

    private final MovieRepository repository;

    MovieService(MovieRepository repository) {
        this.repository = repository;
    }

    public Movie save(String id, String title, String description) {
        return repository.save(new Movie(id, title, description));
    }
}

Next Steps

  • Continue with client configuration to customize JSON handling, timeouts, and XML namespace usage.

  • Continue with object mapping to understand @Document, @Setting, and conversion support.

  • Continue with operations and repositories to choose between template-style access and repository abstractions.