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

Object Mapping

Spring Data Meilisearch maps domain objects to Meilisearch documents through mapping metadata, a mapping context, and a converter. The same mapping is used by repositories and MeilisearchOperations; metadata supplies the index uid, document id, and optional settings.

@Document

A mapped type used by repository or template operations must declare its target index uid:

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

import org.springframework.data.annotation.Id;

@Document(indexUid = "movies")
class Movie {

    @Id
    private String id;
    private String title;
    private String description;
}

indexUid is required. Spring Data Meilisearch resolves the index for entity-based operations from this metadata. @Document.applySettings defaults to true; repository bootstrap applies the entity’s declared settings unless it is set to false. Meilisearch creates a missing index when its settings-update API runs, so repository bootstrap can create the index. See Settings for annotation and runtime settings behavior.

Document Id

The document id is resolved from a Spring Data @Id property. A property named id is also recognized by convention, even without @Id. The default mapping uses the property’s Java field name as the document key; the same property name is used as the Meilisearch primary key when saving the entity.

When repository methods or entity-based delete operations need a string id, MeilisearchConverter.convertId uses a registered conversion to String when available; otherwise it uses the value’s toString() representation. This conversion is separate from serializing the entity’s primary-key field. A Converter<MyId, String> alone does not make the default document writer serialize a custom MyId property as a scalar JSON value; ensure the persisted primary-key field is a scalar supported by Meilisearch.

Annotation-driven Settings Metadata

Use @Setting and companion annotations such as @TypoTolerance, @Faceting, and @Pagination to declare entity-owned index settings. These annotations are metadata; repository bootstrap applies them by default when @Document.applySettings is enabled. Direct template use does not automatically apply them; call MeilisearchOperations.applySettings(Entity.class) or use MeilisearchIndexOperations.updateSettings(…​) when needed. For setting groups and clearing/resetting behavior, see Settings.

Mapping Context and Converter

MeilisearchConfigurationSupport registers the mapping infrastructure beans:

  • meilisearchMappingContext

  • meilisearchCustomConversions

  • meilisearchConverter

The default converter is MappingMeilisearchConverter. It uses the mapping context for entity metadata and applies custom conversions registered through MeilisearchCustomConversions.

For properties traversed by the default writer, non-null values are mapped using their Java field names. Collections and arrays become JSON arrays, maps become JSON objects, and nested objects are mapped recursively. The mapping context does not implement entity-reference/association loading; related data must be represented in the document model rather than relying on automatic reference resolution.

Document Mapping and JSON Payloads

MappingMeilisearchConverter reads and writes map-shaped Document values before they reach the Meilisearch Java SDK. The Spring-managed ObjectMapper bean named meilisearchObjectMapper then serializes those document payloads. The SDK JsonHandler remains responsible for SDK transport concerns; it is not the entity mapping layer.

Example 1. Customizing the document ObjectMapper
import com.fasterxml.jackson.databind.ObjectMapper;
import io.vanslog.spring.data.meilisearch.client.ClientConfiguration;
import io.vanslog.spring.data.meilisearch.config.MeilisearchConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
class MyClientConfig extends MeilisearchConfiguration {

    @Bean
    @Override
    public ClientConfiguration clientConfiguration() {
        return ClientConfiguration.builder()
                .connectedToLocalhost()
                .withApiKey(System.getenv("MEILISEARCH_API_KEY"))
                .build();
    }

    @Bean(name = "meilisearchObjectMapper")
    @Override
    public ObjectMapper meilisearchObjectMapper() {
        return new ObjectMapper();
    }
}

MeilisearchConfiguration is abstract, so a configuration subclass must also provide clientConfiguration(). Provide a scoped API key through MEILISEARCH_API_KEY rather than committing credentials.

Custom Conversions

Override the meilisearchCustomConversions() bean when document values need a custom representation. The default writer consults custom write conversions that target Document; the reader consults conversions from a document value to the target property type. Register a writing and reading converter for a round trip:

import io.vanslog.spring.data.meilisearch.core.document.Document;
import java.math.BigDecimal;
import java.util.List;
import org.springframework.core.convert.converter.Converter;
import org.springframework.data.convert.ReadingConverter;
import org.springframework.data.convert.WritingConverter;

record Price(BigDecimal amount, String currency) {}

@WritingConverter
class PriceToDocumentConverter implements Converter<Price, Document> {

    @Override
    public Document convert(Price price) {
        return Document.create()
                .append("amount", price.amount().toPlainString())
                .append("currency", price.currency());
    }
}

@ReadingConverter
class DocumentToPriceConverter implements Converter<Document, Price> {

    @Override
    public Price convert(Document document) {
        return new Price(new BigDecimal((String) document.get("amount")),
                (String) document.get("currency"));
    }
}

Register the converters through MeilisearchCustomConversions:

import io.vanslog.spring.data.meilisearch.core.convert.MeilisearchCustomConversions;
import java.util.List;

@Bean
@Override
public MeilisearchCustomConversions meilisearchCustomConversions() {
    return new MeilisearchCustomConversions(
            List.of(new PriceToDocumentConverter(), new DocumentToPriceConverter()));
}

Use this pattern when a document property needs a structure different from its Java type. ID conversion to String is handled separately by MeilisearchConverter.convertId; see Document Id for the primary-key serialization limitation.