Index and Instance Operations

MeilisearchOperations exposes two Meilisearch-specific entry points:

  • instanceOps() for instance-level information.

  • indexOps(…​) for APIs bound to an index uid.

These synchronous APIs cover instance inspection and index lifecycle/settings operations without requiring direct use of the Meilisearch Java SDK. See Settings for settings annotation and update details.

Instance Operations

MeilisearchInstanceOperations provides these read operations:

  • MeilisearchHealth health()

  • boolean isHealthy()

  • MeilisearchVersion version()

  • MeilisearchStats stats()

MeilisearchInstanceOperations instance = meilisearchOperations.instanceOps();

MeilisearchHealth health = instance.health();
boolean healthy = instance.isHealthy();
MeilisearchVersion version = instance.version();
MeilisearchStats stats = instance.stats();

instanceOps().stats() reports instance-level statistics. For statistics for one index, use indexOps(…​).stats().

Index-bound Operations

Resolve index operations either from entity mapping metadata or from an explicit uid:

MeilisearchIndexOperations byEntity = meilisearchOperations.indexOps(Movie.class);
MeilisearchIndexOperations byIndexUid = meilisearchOperations.indexOps("movies");

indexOps(Class<?>) requires an entity annotated with @Document and uses its indexUid. indexOps(String) is useful for index administration when no mapped entity type is involved. Document and search operations still require a mapped entity class.

Index Lifecycle

MeilisearchIndexOperations exposes:

  • MeilisearchIndex create() and MeilisearchIndex create(MeilisearchIndexCreateRequest)

  • MeilisearchIndex get()

  • MeilisearchIndexList list() and MeilisearchIndexList list(MeilisearchIndexQuery)

  • MeilisearchIndex update(MeilisearchIndexUpdateRequest)

  • boolean delete()

  • MeilisearchIndexStats stats()

  • MeilisearchIndexSettings getSettings()

  • MeilisearchIndexSettings updateSettings(MeilisearchIndexSettings)

  • MeilisearchIndexSettings resetSettings()

create() creates the bound index without an explicit primary key. Pass a create request to specify one:

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

MeilisearchIndex created = index.create(new MeilisearchIndexCreateRequest("productId"));
MeilisearchIndex current = index.get();

MeilisearchIndexList firstHundred = index.list(new MeilisearchIndexQuery(0, 100));
MeilisearchIndex updated = index.update(new MeilisearchIndexUpdateRequest("productId"));
boolean deleted = index.delete();

The index list methods return a page of indexes for the Meilisearch instance; they are not restricted to the uid bound to the MeilisearchIndexOperations object. MeilisearchIndexQuery supplies a non-negative offset and positive limit. update(request) sets the bound index’s primary key from the request. delete() returns whether its delete task succeeded.

Runtime Settings

Inspect, update, or reset settings on the bound index:

MeilisearchIndexSettings current = index.getSettings();

MeilisearchIndexSettings updatedSettings = index.updateSettings(
        MeilisearchIndexSettings.builder()
                .withSearchableAttributes(List.of("title", "description"))
                .withFilterableAttributes(List.of("genres"))
                .withPagination(new MeilisearchIndexSettings.PaginationSettings(1500))
                .build());

MeilisearchIndexSettings defaults = index.resetSettings();

updateSettings applies only the non-null fields supplied in the settings value; an empty collection clears a supported list or map setting. resetSettings() restores all Meilisearch index settings to defaults. Both methods return settings read after their task succeeds. See Runtime Settings Updates.

The public API uses Spring Data Meilisearch value types such as MeilisearchIndexSettings, MeilisearchIndexCreateRequest, MeilisearchIndexUpdateRequest, and MeilisearchIndexList rather than exposing Meilisearch Java SDK request/response models directly.

Asynchronous Task Behavior

Meilisearch enqueues document writes/deletes, settings changes, and index lifecycle mutations as tasks. The public operations wait for those tasks using the configured request timeout and polling interval before returning; they do not expose task ids or return immediately after enqueueing. This applies to document methods such as save(…​), delete(…​), and applySettings(…​) as well as index methods such as create(), update(…​), delete(), and settings mutations.

ClientConfigurationBuilder.withRequestTimeout(…​) and withRequestInterval(…​) configure these values in milliseconds. A failed or canceled completed task raises TaskStatusException from save(…​), applySettings(…​), deleteByFilter(…​), index create() and update(…​), and settings mutations. Boolean deletion operations return false when their task does not succeed.

TaskStatusException reports the completed task’s UID through getTaskUid(), its server-reported status through getStatus(), and the server error code through getErrorCode() when one is available. The error code is null when Meilisearch provides no task error details. The exception message retains the operation and server failure reason when available. A wait timeout is an unconfirmed outcome and remains a distinct UncategorizedMeilisearchException; it is not reported as a failed task. Document, settings, and index operations also reject a missing completed-task response as an unconfirmed outcome, using UncategorizedMeilisearchException rather than inventing a failed task status.

Handle a completed task failure with the SDK-independent diagnostics:

import io.vanslog.spring.data.meilisearch.TaskStatusException;

try {
    operations.save(movie);
} catch (TaskStatusException ex) {
    System.err.printf("Task %d ended with status %s (error %s): %s%n",
            ex.getTaskUid(), ex.getStatus(), ex.getErrorCode(), ex.getMessage());
}

The exception contract no longer exposes com.meilisearch.sdk.model.TaskStatus. Its SDK-typed public constructors and getTaskStatus() accessor have been removed, which is a source and binary compatibility change. Recompile applications that used the old constructors and replace getTaskStatus() with getStatus(); use getTaskUid() and getErrorCode() for the other diagnostics. Code constructing the exception directly must use its UID, string status, nullable error code, message, and optional cause constructor arguments.

This change is limited to task failure diagnostics. The supported SDK-coupled callback and native client access boundaries remain unchanged; see Operations and Client Configuration.