Replication and sharding

Scale Meilisearch horizontally by distributing documents across multiple instances with sharding, and ensure high availability with replication.

Replication and sharding let you run Meilisearch across multiple instances as a coordinated network. Sharding splits your data across instances so each one handles a smaller portion. Replication duplicates shards across instances so your search stays available if one goes down.

Replication and sharding require the Meilisearch Enterprise Edition v1.37 or later. See Enterprise and Community editions for details.

What is sharding?

Sharding distributes documents from a single index across multiple Meilisearch instances, called “remotes.” Each remote holds one or more named shards containing a subset of your documents.

When a user searches, Meilisearch queries the necessary remotes in the network, collects results from each shard, and merges them into a single ranked response, as if the data lived on a single machine.

What is replication?

Replication assigns the same shard to more than one remote. This ensures your data is stored redundantly across instances. During a network search, Meilisearch ensures each shard is queried exactly once, either from a remote shard or from the local one (chosen randomly, favoring the local one). This guarantees each shard is queried exactly once, so results are never duplicated regardless of how many replicas exist.

How it works

1. Network: the user configures the topology via /network on the leader, and this instance propagates it to all remotes
2. Shards: Remotes distribute the subsets of documents across themselves based on shard assignments
3. Search: when useNetwork: true is set or not defined (defaults to true), the instance receiving the request fans out the search to all remotes, then merges and ranks the combined results

When to use sharding and replication

Scenario	Solution
Dataset too large for a single instance	Sharding: split documents across multiple remotes
Need high availability	Replication: assign each shard to 2+ remotes
Geographic distribution	Sharding + replication: place remotes closer to users
Read throughput bottleneck	Replication: distribute search load across replicas

The network

All instances in a Meilisearch network share a topology configuration that defines:

• self: the identity of the current instance
• leader: the instance coordinating writes and topology changes
• remotes: all instances in the network with their URLs, search API keys, and write API keys
• shards: how document subsets are distributed across remotes

The leader instance is responsible for write operations and topology changes. Non-leader instances reject write requests (document additions, settings changes, index creation) with a not_leader error. Search requests can be sent to any instance in the network.

Searching across the network

To search across all instances:

useNetwork defaults to true when a network topology is defined.

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "q": "batman"
  }'

The response includes _federation metadata showing which remote each result came from. You can also use the _shard filter to target specific shards:

{
  "q": "batman",
  "filter": "_shard = \"shard-a\""
}

Network search with multi-search

Network search works with multi-search and federated search. Add useNetwork: true to individual queries within a multi-search request:

curl \
  -X POST 'MEILISEARCH_URL/multi-search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "queries": [
      { "indexUid": "movies", "q": "batman" },
      { "indexUid": "comics", "q": "batman" }
    ]
  }'

Feature compatibility

Most Meilisearch features work transparently across a sharded network. The following table highlights important considerations:

Feature	Works with sharding?	Notes
Full-text search	Yes	Results merged and ranked across all remotes
Filtering and sorting	Yes	Filters applied on each remote before merging
Faceted search	Partial	Facet distribution in search results works across remotes, but the /facet-search endpoint does not support useNetwork
Hybrid/semantic search	Yes	Each remote runs its own vector search, results merged
Geo search	Yes	Geographic filters and sorting work across remotes
Multi-search	Yes	Works per query; useNetwork defaults to true when a network is configured
Federated search	Yes	Federation merges results from both indexes and remotes
Analytics	Partial	Events are tracked on the instance that receives the search request
Tenant tokens	Yes	Token filters apply on each remote
Document operations	Leader only	Writes must go through the leader instance
Settings changes	Leader only	Settings updates must go through the leader
Conversational search	No	Chat completions do not support useNetwork

Search requests may return errors during a network topology change if they reference shards that are being added or removed. Wait for all NetworkTopologyChange tasks to complete before searching.

Prerequisites

Before setting up sharding and replication, you need:

• Meilisearch Enterprise Edition v1.37 or later on all instances
• A master key configured on each instance
• Network connectivity between all instances
• If using private networks (10.x.x.x, 192.168.x.x), the --experimental-allowed-ip-networks flag must be set on each instance

Next steps

Set up a sharded cluster

Step-by-step guide to configuring sharding and replication.

Configure replication

Set up replicated shards for high availability and read scaling.

Manage the network

Add and remove remotes, update shard assignments.

Enterprise Edition

Learn about the differences between Community and Enterprise editions.