Share the article
Meilisearch uses sharding to distribute a single index across multiple instances, going beyond the limits of a single machine. Paired with replication, it lets you handle large datasets and high query volume while staying available when an instance goes down.
This guide covers what sharding and replication do, and how to set up a cluster.
This post was originally written when sharding landed in v1.19. The feature has changed substantially since: shards are now named and assigned explicitly, replication is supported, writes are coordinated by a leader instance, and searching a sharded index no longer requires building a federated request by hand. It has been updated for Meilisearch Enterprise Edition v1.37 and later.
How sharding and replication work
Sharding splits the documents of an index across several instances, called remotes, so each one holds and indexes a subset. Replication assigns the same shard to more than one remote, so the data survives losing an instance.
When a user searches, the instance receiving the request fans the query out across the network, collects results from each shard, and merges them into a single ranked response. Each shard is queried exactly once even when several remotes hold a copy, so replicas never produce duplicate results.
| Scenario | Solution |
|---|---|
| Dataset too large for a single instance | Sharding: split documents across remotes |
| Need high availability | Replication: assign each shard to two or more remotes |
| Geographic distribution | Sharding and replication: place remotes closer to users |
| Read throughput bottleneck | Replication: spread search load across replicas |
The network topology
Every instance shares one topology configuration, which defines:
self: the identity of the current instanceleader: the instance that coordinates writes and topology changesremotes: every instance in the network, with its URL and API keysshards: how document subsets are distributed across remotes
Writes go through the leader. Non-leader instances reject document additions, settings changes, and index creation with a not_leader error. Search requests can go to any instance.
Enterprise Edition and licensing
Sharding and replication are available in Meilisearch Enterprise Edition (EE). All Meilisearch Cloud projects have access to Enterprise Edition features, and Cloud users can ask support to enable sharding on a project.
A note on self-hosting: EE features are governed by the Business Source License 1.1, which lets you use, test, and develop with sharding for free in non-production environments. Running it in production requires a commercial license agreement.
To get started with Meilisearch Enterprise Edition, talk to our team.
How to set up a sharded cluster
Prerequisites
- Meilisearch Enterprise Edition v1.37 or later on every instance.
- Identical setup: all instances must run the same version.
- Network access between instances. If they talk over a private network, start them with
--experimental-allowed-ip-networks.
Step 1: Start your instances
Step 2: Enable the network feature
The network feature is experimental, so enable it on each instance:
Repeat for ms-01 and ms-02 with their own URLs and master keys.
Step 3: Configure the network topology
Send a single PATCH /network request to the leader. The leader propagates the configuration to every other remote, so you no longer configure each node separately.
writeApiKeymust carry thedocuments.addpermission and authorizes document forwarding between instances.searchApiKeymust have permission to search the relevant indexes.
To add replication, list more than one remote per shard, for example "shard-a": { "remotes": ["ms-00", "ms-01"] }.
Step 4: Add documents
Send documents to the leader, as you would to any single instance. Meilisearch distributes them across the shards for you.
The task object includes a root-level network field so you can follow the operation across the cluster:
Step 5: Search the distributed index
Search normally, against any instance. Once a topology is configured, useNetwork defaults to true, so Meilisearch fans the query out and merges the results itself.
The response carries _federation metadata identifying which remote each result came from. To restrict a search to one shard, filter on _shard:
Network search also works with multi-search and federated search; useNetwork applies per query.
What works across a sharded network
Full-text search, filtering and sorting, faceted search, hybrid and semantic search, geo search, federated search, and tenant tokens all work transparently across shards. Two things to keep in mind:
- Writes and settings changes go through the leader only.
- Conversational search does not support network search.
Search requests can also error during a topology change if they reference shards being added or removed, so wait for NetworkTopologyChange tasks to finish before searching.
Moving forward
Sharding and replication let you scale a single index past one machine and stay available when an instance fails.
Meilisearch Cloud users can get started by asking support to enable sharding for their project. For companies interested in self-hosting Meilisearch Enterprise Edition, book a call to get a quote.
Frequently asked questions (FAQs)
What is the difference between sharding and replication?
Sharding splits an index's documents across several instances so each holds a subset, which is what lets a dataset outgrow a single machine. Replication assigns the same shard to more than one instance so a copy survives if one goes down. They compose: a production cluster typically shards for capacity and replicates for availability.
Do I need Meilisearch Enterprise Edition for sharding?
Yes. Sharding and replication are Enterprise Edition features, available from v1.37. Meilisearch Cloud projects already include Enterprise Edition features. Self-hosted use is governed by the Business Source License 1.1, which permits non-production use for free and requires a commercial agreement in production.
Can I send writes to any instance in the cluster?
No. Writes, settings changes, and index creation must go through the leader instance; other instances reject them with a not_leader error. Search requests can go to any instance.
Do I have to build a federated search request to query a sharded index?
No. Once a network topology is configured, useNetwork defaults to true, so an ordinary search against any instance is fanned out across the network and merged automatically. Earlier versions required assembling a multi-search request targeting each node by hand.
Will replicas return duplicate results?
No. Meilisearch queries each shard exactly once per search, choosing one remote among those holding it, so the number of replicas does not affect the result set.
