Client Configuration

Spring Data Meilisearch operates on top of the Meilisearch Java client and exposes a Spring-friendly configuration model for creating and wiring the client.

In most applications, the entry point is a Java configuration class that extends MeilisearchConfiguration. XML namespace support is available for applications that still use XML-based container configuration.

JavaConfig

In Java configuration, extend MeilisearchConfiguration to provide the ClientConfiguration bean. The base class registers the default GsonJsonHandler, MeilisearchClient, mapping context, converter, object mapper, and meilisearchTemplate / meilisearchOperations bean names.

import io.vanslog.spring.data.meilisearch.client.ClientConfiguration;
import io.vanslog.spring.data.meilisearch.config.MeilisearchConfiguration;

import org.springframework.context.annotation.Configuration;

@Configuration
class MyClientConfig extends MeilisearchConfiguration {

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

ClientConfiguration Builder

ClientConfiguration exposes the following core options through its builder:

connectedTo(…) or connectedToLocalhost() to choose the server URL. The Java builder has no default URL.
withApiKey(…) to supply a key when authentication is enabled; the Java builder has no default key.
withClientAgents(String[]) to supply client-agent values sent in the User-Agent header.
withRequestTimeout(…) to set the task-completion wait timeout in milliseconds. The Java builder default is 5,000 ms.
withRequestInterval(…) to set the polling interval in milliseconds. The Java builder default is 50 ms.

The Java builder requires a non-null argument to withApiKey(…). Pass withApiKey("") for a development instance without authentication.

These timeout and interval values are passed to the SDK’s task-wait operations for asynchronous writes, index lifecycle changes, and settings updates. They are not HTTP connection or socket timeouts.

JSON Handler

MeilisearchConfiguration registers GsonJsonHandler by default. The JsonHandler configures the underlying Meilisearch Java SDK transport. Entity document mapping and document JSON payloads are handled by Spring Data Meilisearch through MeilisearchConverter and the meilisearchObjectMapper bean. Override jsonHandler() when you need a different implementation.

import com.meilisearch.sdk.json.JacksonJsonHandler;
import com.meilisearch.sdk.json.JsonHandler;
import io.vanslog.spring.data.meilisearch.client.ClientConfiguration;
import io.vanslog.spring.data.meilisearch.config.MeilisearchConfiguration;

import org.springframework.context.annotation.Configuration;

@Configuration
class JsonHandlerConfig extends MeilisearchConfiguration {

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

    @Override
    public JsonHandler jsonHandler() {
        return new JacksonJsonHandler();
    }
}

The supported integration styles are:

com.meilisearch.sdk.json.GsonJsonHandler
com.meilisearch.sdk.json.JacksonJsonHandler
Any custom implementation of com.meilisearch.sdk.json.JsonHandler

XML Namespace

Spring Data Meilisearch also provides an XML namespace. Unlike Java configuration, the namespace does not create a JSON handler bean. Declare a JsonHandler bean named jsonHandler (the schema’s default reference), or set json-handler-ref to the id of another handler bean. The XML api-key attribute is optional. Omit it or set api-key="" for an instance without authentication; neither form sends an Authorization header. A placeholder resolving to an empty value behaves the same way, while an unresolved placeholder fails Spring’s property resolution by default. For protected instances, prefer a scoped API key rather than the Meilisearch master key.

<beans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:meilisearch="http://www.vanslog.io/spring/data/meilisearch"
       xmlns="http://www.springframework.org/schema/beans"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.springframework.org/schema/context
       http://www.springframework.org/schema/context/spring-context.xsd
       http://www.vanslog.io/spring/data/meilisearch
       http://www.vanslog.io/spring/data/meilisearch/spring-meilisearch-1.0.xsd">

    <context:property-placeholder/>

    <bean id="jsonHandler" class="com.meilisearch.sdk.json.GsonJsonHandler"/>

    <meilisearch:meilisearch-client
            id="meilisearchClient"
            host-url="http://localhost:7700"
            api-key="${MEILISEARCH_API_KEY}"
            request-timeout="2000"
            request-interval="20"
            json-handler-ref="jsonHandler"/>
</beans>

For a local instance without authentication, omit the key:

<meilisearch:meilisearch-client id="meilisearchClient" json-handler-ref="jsonHandler"/>

When omitted, the XML factory leaves request-timeout and request-interval at 0, unlike the Java builder defaults. See the XML namespace reference for attribute defaults.