Meilisearch Settings

This chapter covers how to modify search settings in Meilisearch.

Overview

Meilisearch settings are used to define the behavior of the search engine. Using the @Setting annotation, you can define the basic settings for the index, while complex settings are defined using separate annotations like @TypoTolerance, @Faceting, and @Pagination.

@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" }),
        @Synonym(word = "laptop", synonyms = { "notebook" })
  },
  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 {
    @Id private String id;
    private String description;
    private String brand;
    private String color;
    private String productId;
    private double price;
}

Search Settings

These settings control how documents are searched and ranked in Meilisearch.

Searchable and Displayed Attributes

@Document(indexUid = "products")
@Setting(
  searchableAttributes = { "description", "brand", "color" },        (1)
  displayedAttributes = { "description", "brand", "color", "productId" } (2)
)
class Product {
    @Id private String id;
    private String description;
    private String brand;
    private String color;
    private String productId;
}

1	The `searchableAttributes` attribute is used to define the fields that must be used for searching the results.
2	The `displayedAttributes` attribute is used to define the fields that must be displayed in the results.

Ranking and Sorting

@Document(indexUid = "products")
@Setting(
  sortableAttributes = { "productId" },                                              (1)
  rankingRules = { "typo", "words", "proximity", "attribute", "sort", "exactness" }, (2)
  distinctAttribute = "productId"                                                    (3)
)
class Product {
    @Id private String id;
    private String productId;
    // other fields...
}

1	The `sortableAttributes` attribute is used to define the fields that can be used for sorting the results.
2	The `rankingRules` attribute is used to define the ranking rules that must be used for sorting the results.
3	The `distinctAttribute` attribute is used to define the field that must be used to remove duplicates from the results.

Filtering and Faceting

@Document(indexUid = "products")
@Setting(
  filterableAttributes = { "brand", "color", "price" }                               (1)
)
@Faceting(maxValuesPerFacet = 100)                                                   (2)
class Product {
    @Id private String id;
    private String brand;
    private String color;
    private double price;
    // other fields...
}

1	The `filterableAttributes` attribute defines which fields can be used for filtering and faceted search.
2	The `@Faceting` annotation configures faceted search behavior.

Text Processing Settings

These settings control how Meilisearch processes text during indexing and searching.

Synonyms and Dictionary

@Document(indexUid = "products")
@Setting(
  synonyms = {                                                                       (1)
        @Synonym(
            word = "phone",
            synonyms = { "mobile", "cellphone" }
        ),
        @Synonym(
            word = "laptop",
            synonyms = { "notebook" }
        )
  },
  dictionary = { "netflix", "spotify" },                                             (2)
  stopWords = { "a", "an", "the" }                                                   (3)
)
class Product {
    @Id private String id;
    // fields...
}

1	The `synonyms` attribute defines groups of words that should be considered equivalent in search.
2	The `dictionary` attribute adds custom words to the internal dictionary.
3	The `stopWords` attribute defines stop words to ignore while searching.

Typo Tolerance

@Document(indexUid = "products")
@TypoTolerance(                                                                      (1)
  enabled = true,
  minWordSizeForTypos = @MinWordSizeForTypos(
    oneTypo = 5,
    twoTypos = 9
  ),
  disableOnWords = {"skype", "zoom"},
  disableOnAttributes = {"serial_number"}
)
class Product {
    @Id private String id;
    // fields...
}

1	The `@TypoTolerance` annotation configures the typo tolerance behavior of the search engine.

Tokenization

@Document(indexUid = "products")
@Setting(
  separatorTokens = { "-", "_", "@" },                                               (1)
  nonSeparatorTokens = { ".", "#" }                                                  (2)
)
class Product {
    @Id private String id;
    // fields...
}

1	The `separatorTokens` attribute defines which characters should be considered as word separators.
2	The `nonSeparatorTokens` attribute defines which characters should not be considered as word separators.

Localization

By default, Meilisearch automatically detects the languages used in your documents. However, you can explicitly define which languages are present in your dataset and in which fields using localized attributes configuration. You can configure localized attributes using the @LocalizedAttribute annotation within the @Setting annotation. Note that configuring multiple languages for a single index may impact search performance.

@Document(indexUid = "products")
@Setting(
  localizedAttributes = {
    @LocalizedAttribute(
      attributePatterns = { "*En" },                                                (1)
      locales = { "eng" }                                                           (2)
    )
  }
)
class Product {
    @Id private String id;
    private String nameEn;
    // fields...
}

The attributePatterns specify which fields contain content in the specified languages using patterns. These patterns support wildcards (*) to match multiple fields with similar naming conventions:

*En matches fields ending with En, such as nameEn and titleEn. These fields are processed according to the language rules of the specified locales. The patterns affect searchableAttributes, filterableAttributes, and sortableAttributes.

2 The locales attribute defines the list of supported languages for the specified attributes. Each locale follows the ISO-639-3 three-letter, or alternatively use ISO-639-1 two-letter equivalents. For a complete list of supported languages, refer to the Meilisearch documentation.

Language Detection Control

Meilisearch provides two mechanisms for controlling language detection:

Query-level Language Control: If Meilisearch is detecting incorrect languages because of the query text, you can explicitly set the search language using the locales parameter in your search request.
Document-level Language Control: If Meilisearch is detecting incorrect languages in your documents, use localizedAttributes to explicitly set the document languages at the index level.

For complete control over language detection during both indexing and search time, you can use both locales and localizedAttributes together.

AI-powered Search Settings

Meilisearch uses embedders to generate vector embeddings for AI-powered search features such as semantic search and similar document search. You can configure embedders with the @Embedder annotation inside @Setting.

@Document(indexUid = "movies")
@Setting(
  searchableAttributes = { "title", "description" },
  embedders = {
    @Embedder(
      name = "default",
      source = Embedder.Source.OPEN_AI,
      apiKey = "sk-...",
      model = "text-embedding-3-small",
      documentTemplate = "A movie titled {{doc.title}} whose description starts with {{doc.description|truncatewords: 20}}"
    )
  }
)
class Movie {
    @Id private String id;
    private String title;
    private String description;
}

Each @Embedder requires a unique name, which becomes the key in Meilisearch’s embedders setting. Optional attributes map to the SDK embedder settings, including source, apiKey, model, documentTemplate, dimensions, distributionMean, distributionSigma, documentTemplateMaxBytes, revision, binaryQuantized, REST request and response parameters, headers, url, inputField, inputType, and query. distributionMean and distributionSigma must be configured together. request, response, and headers use @EmbedderParameter and currently support flat string key-value parameters.

Performance Settings

These settings control the performance aspects of Meilisearch.

@Document(indexUid = "products")
@Setting(
  proximityPrecision = "byWord",                                                     (1)
  searchCutoffMs = 50                                                                (2)
)
class Product {
    @Id private String id;
    // fields...
}

1	The `proximityPrecision` attribute defines how word proximity is calculated (`byWord`, `byAttribute`).
2	The `searchCutoffMs` attribute sets the maximum processing time for a search query in milliseconds.

Pagination

Meilisearch’s search function is limited to return a maximum of 1,000 results. Therefore, search(SearchRequest searchRequest, Class<?> clazz) in MeilisearchOperation can’t return more than 1,000 results.

If you have more than 1,000 results, you must use @Pagination annotation to extract the remaining results.

@Document(indexUid = "products")
@Pagination(maxTotalHits = 2000)                                                     (1)
class Product {
    @Id private String id;
    // fields...
}

1	The `maxTotalHits` is used to define the maximum number of results that can be reached through search.

See the Meilisearch pagination documentation for details on maxTotalHits, estimatedTotalHits, and totalHits. This setting can cap the totalHits reported by Meilisearch paginated search responses. As a result, exact total hit metadata such as SearchHits#getTotalHits() with relation EQUAL_TO and repository Page totals can reflect the capped search total, while the page content size still reflects only the hits returned for the current request.