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.

Native Client Boundary

MeilisearchClient intentionally extends the Meilisearch Java SDK Client. This inheritance is retained as a supported low-level boundary, including for 1.0; it is not a reason to make ordinary application access a thin SDK wrapper. Prefer MeilisearchOperations, indexOps(…​), instanceOps(), and repositories for regular application work. See Native SDK Access for callback and direct-client guarantees.

Inherited SDK methods, SDK model types, and native JSON-handler configuration remain coupled to the supported SDK API and version. They do not make the entire public API SDK-independent. A future composition change would require a concrete driver and an explicit migration for inherited calls, SDK Client assignment/injection, and subclass/override assumptions; it is not a prerequisite for synchronous client support or a consequence of evaluating Reactive support.

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();
    }
}

Native Client Boundary

MeilisearchClient intentionally extends com.meilisearch.sdk.Client; this low-level inheritance is retained for 1.0. JavaConfig and the XML namespace both expose MeilisearchClient as the concrete product type, which remains assignable to the SDK Client. For ordinary application data access, prefer MeilisearchOperations (see Operations), indexOps(…​) and instanceOps(…​) (see Index operations), or repositories.

Direct use of MeilisearchClient is coupled to the supported meilisearch-java SDK API and models (currently version 0.21.0). The raw MeilisearchCallback receives the SDK Client, and SDK JsonHandler types remain part of client configuration; retaining inheritance does not make the whole public API independent of the SDK. MeilisearchClient also keeps its internal HTTP transport-backed document retrieval for operations not supplied by the SDK.

Replacing inheritance with composition would break direct calls to inherited SDK methods, assignment or dependency injection as Client, and user subclasses that override inherited methods. Any composition change would need an explicit compatibility and migration plan rather than a forwarding facade. Reopen that decision only for a concrete driver, such as a required alternative transport or an observed SDK inheritance compatibility problem.

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.