Settings

Spring Data Meilisearch supports two complementary ways to configure index settings:

  • annotation metadata on a mapped entity type,

  • runtime inspection and updates through MeilisearchIndexOperations.

Use annotations for settings that belong with an entity definition. Use runtime operations when settings must be read, changed, cleared, or reset independently. See Index and Instance Operations for index lifecycle methods.

Annotation-driven Settings

Use @Setting for the main settings and companion annotations for pagination, typo tolerance, and faceting:

@Document(indexUid = "products")
@Setting(
        searchableAttributes = { "description", "brand", "color" },
        displayedAttributes = { "description", "brand", "color", "productId" },
        sortableAttributes = { "productId" },
        rankingRules = { "typo", "words", "proximity", "attribute", "sort", "exactness" },
        distinctAttribute = "productId",
        filterableAttributes = { "brand", "color", "price" },
        synonyms = {
                @Synonym(word = "phone", synonyms = { "mobile", "cellphone" })
        },
        dictionary = { "netflix", "spotify" },
        stopWords = { "a", "an", "the" },
        separatorTokens = { "-", "_", "@" },
        nonSeparatorTokens = { ".", "#" },
        proximityPrecision = "byWord",
        searchCutoffMs = 50)
@TypoTolerance(enabled = true,
        minWordSizeForTypos = @MinWordSizeForTypos(oneTypo = 5, twoTypos = 9),
        disableOnWords = { "skype", "zoom" },
        disableOnAttributes = { "serial_number" })
@Faceting(maxValuesPerFacet = 100)
@Pagination(maxTotalHits = 2000)
class Product {
}

@Document.applySettings defaults to true. Repository bootstrap applies the declared settings when it creates a repository for the entity; set applySettings = false to disable that automatic update. Meilisearch’s settings-update API creates a missing index, so bootstrap can create the index before the first document is saved. You can also apply annotation settings explicitly with MeilisearchOperations.applySettings(Entity.class).

Direct document saves do not apply annotation settings, but Meilisearch’s add-documents API can also create a missing index. If you need to declare a primary key or other lifecycle options before bootstrap applies settings, create the index explicitly; see Index and Instance Operations.

Annotation defaults that are empty or unset are omitted from the update. They do not clear or reset settings already present on the index; use runtime updates with empty collections to clear supported settings or resetSettings() to restore Meilisearch defaults.

Settings Categories

The annotations cover the settings groups exposed by this module:

  • search and display behavior: searchableAttributes, displayedAttributes, filterableAttributes, sortableAttributes, rankingRules, and distinctAttribute,

  • text processing: synonyms, dictionary, stop words, tokenization, proximity precision, search cutoff, and typo tolerance,

  • result and performance controls: pagination and faceting,

  • explicit language handling through localized attributes,

  • embedder definitions for AI-powered and similar-document search.

Localized Attributes

localizedAttributes declares the locale rules for matching groups of fields. Use it when automatic language detection is not sufficient for the index.

@Document(indexUid = "products")
@Setting(localizedAttributes = {
        @LocalizedAttribute(attributePatterns = { "*En" }, locales = { "eng" })
})
class Product {

    private String nameEn;
}

Embedders

Declare non-secret embedder settings with @Embedder inside @Setting:

@Document(indexUid = "movies")
@Setting(embedders = {
        @Embedder(
                name = "default",
                source = Embedder.Source.OPEN_AI,
                model = "text-embedding-3-small")
})
class Movie {
}

Each embedder needs a unique name. Similar-document queries refer to that name through SimilarQuery.withEmbedder(…​); the embedder must also be configured on the target index.

@Embedder.apiKey is copied as a literal annotation value; a Spring-style placeholder such as ${OPENAI_API_KEY} is not resolved by settings conversion. Set the variable in the process environment and build runtime EmbedderSettings when a credential must be supplied from application configuration:

import io.vanslog.spring.data.meilisearch.core.MeilisearchIndexOperations;
import io.vanslog.spring.data.meilisearch.core.MeilisearchIndexSettings;
import java.util.Map;

MeilisearchIndexOperations index = meilisearchOperations.indexOps("movies");

MeilisearchIndexSettings.EmbedderSettings embedder =
        MeilisearchIndexSettings.EmbedderSettings.builder()
                .withSource(MeilisearchIndexSettings.EmbedderSource.OPEN_AI)
                .withApiKey(System.getenv("OPENAI_API_KEY"))
                .withModel("text-embedding-3-small")
                .build();

index.updateSettings(MeilisearchIndexSettings.builder()
        .withEmbedders(Map.of("default", embedder))
        .build());

Runtime Settings Updates

Use MeilisearchIndexOperations to inspect or change current settings:

MeilisearchIndexOperations index = meilisearchOperations.indexOps(Product.class);

MeilisearchIndexSettings current = index.getSettings();

MeilisearchIndexSettings updated = index.updateSettings(
        MeilisearchIndexSettings.builder()
                .withSearchableAttributes(List.of("description", "brand", "color"))
                .withDisplayedAttributes(List.of("description", "brand", "color", "productId"))
                .withFilterableAttributes(List.of("brand", "color", "price"))
                .withPagination(new MeilisearchIndexSettings.PaginationSettings(2000))
                .build());

MeilisearchIndexSettings defaults = index.resetSettings();

An update sends the non-null fields present in MeilisearchIndexSettings; unspecified fields are left unchanged. Use empty collections to clear supported list or map settings. resetSettings() resets all settings to Meilisearch defaults and returns the settings read back after the reset task succeeds.

Pagination Limits

@Pagination(maxTotalHits = …​) and the runtime PaginationSettings configure the maximum number of search hits that can be retrieved through pagination. If a request asks for more hits than this limit, the returned hit list can be shorter than its requested page size. When @Pagination is present without an explicit value, its maxTotalHits default is 1,000.

The limit does not necessarily cap the total-hit metadata reported by Meilisearch. When the response reports a total, Spring Data Meilisearch carries that value into SearchHits#getTotalHits() and repository Page#getTotalElements(); the reported total may therefore exceed maxTotalHits. For example, with maxTotalHits = 10, a search over 11 matching documents can return 10 hits while reporting 11 total matches. See Search Result Types for total-hit relation semantics.