You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Set up replicated shards across multiple Meilisearch instances to ensure high availability and distribute search load.
5
5
---
6
6
7
-
Replication assigns the same shard to multiple remotes in your Meilisearch network. If one remote goes down, another remote holding the same shard continues serving results. This guide covers how to configure replication, common patterns, and what to expect during failover.
7
+
Replication assigns the same shard to multiple remotes in your Meilisearch network. This guide covers how to configure replication, common patterns, and scaling read throughput.
8
8
9
9
<Note>
10
10
Replication requires the Meilisearch Enterprise Edition v1.37 or later and a [configured network](/resources/self_hosting/sharding/setup_sharded_cluster).
11
11
</Note>
12
12
13
13
## How replication works
14
14
15
-
When you configure shards, each shard can be assigned to one or more remotes. If a shard is assigned to multiple remotes, Meilisearch replicates the data to each of them. During a search with `useNetwork: true`, Meilisearch queries each shard exactly once, picking one of the available remotes for each shard. This avoids duplicate results and provides automatic failover.
15
+
When you configure shards, each shard can be assigned to one or more remotes. If a shard is assigned to multiple remotes, Meilisearch replicates the data to each of them. During a search, Meilisearch queries each shard exactly once, picking one of the available remotes for each shard (prioritizing the `self`/local remote). This avoids duplicate results.
16
16
17
17
## Assign shards to multiple remotes
18
18
@@ -36,7 +36,7 @@ curl \
36
36
37
37
</CodeGroup>
38
38
39
-
In this configuration, every shard exists on two remotes. If any single instance goes down, all shards remain available.
39
+
In this configuration, every shard exists on two remotes. If any single instance goes down, all shard data still exists on another instance.
40
40
41
41
## Common replication patterns
42
42
@@ -83,26 +83,19 @@ Place replicas in different regions to reduce latency for geographically distrib
83
83
}
84
84
```
85
85
86
-
Route search requests to the closest cluster. Both regions hold all data, so either can serve a full result set.
86
+
Route search requests to the closest cluster. Both regions hold all data, so either can serve a full result set. By default, Meilisearch prioritizes local search requests and will not transfer the request to a remote server. Make sure your search requests are made on the closest remote instance to ensure this setup is efficient.
87
87
88
-
## Failover behavior
88
+
## Remote availability
89
89
90
-
When a remote becomes unavailable during a network search:
90
+
When a network search runs, Meilisearch builds an internal set of remotes to query: it assigns each shard to a remote, then sends one query per remote with a shard filter. This guarantees that no shard is queried twice and that results are never duplicated.
91
91
92
-
1. Meilisearch detects the remote is unreachable
93
-
2. If another remote holds the same shard, Meilisearch queries that remote instead
94
-
3. The search completes with results from all shards, using the available replicas
95
-
4. If no remote for a given shard is reachable, results from that shard are missing from the response
96
-
97
-
Meilisearch does not require manual intervention for failover. When the failed remote comes back online, it automatically rejoins the network and starts serving searches again.
92
+
The downside is that there is no automatic fallback. If the remote assigned to a shard is unreachable, that shard's results are missing from the response — Meilisearch does not yet retry using another replica that holds the same shard.
98
93
99
94
## Scaling read throughput
100
95
101
96
Replication is the primary way to scale search throughput in Meilisearch. Each replica can independently handle search requests, so adding more replicas increases the total number of concurrent searches your cluster can handle.
102
97
103
-
To add a new replica for an existing shard:
104
-
105
-
1. Add the new remote to the network:
98
+
To add a new replica for an existing shard, add the new remote and use `addRemotes` to append it to the shard without rewriting the full assignment:
106
99
107
100
<CodeGroup>
108
101
@@ -112,45 +105,31 @@ curl \
112
105
-H 'Content-Type: application/json' \
113
106
-H 'Authorization: Bearer MEILISEARCH_KEY' \
114
107
--data-binary '{
115
-
"addRemotes": {
108
+
"remotes": {
116
109
"ms-03": {
117
110
"url": "http://ms-03.example.com:7703",
118
-
"searchApiKey": "SEARCH_KEY_03"
111
+
"searchApiKey": "SEARCH_KEY_03",
112
+
"writeApiKey": "WRITE_KEY_03"
119
113
}
120
-
}
121
-
}'
122
-
```
123
-
124
-
</CodeGroup>
125
-
126
-
2. Update the shard assignment to include the new remote:
This triggers a `NetworkTopologyChange` task that replicates the shard's documents to `ms-03`.
124
+
146
125
## The leader instance
147
126
148
-
The leader is responsible for all write operations (document additions, settings changes, index management). Non-leader instances reject writes with a `not_a_leader` error.
127
+
The leader is responsible for all write operations (document additions, settings changes, index management). Non-leader instances reject writes with a `not_leader` error.
149
128
150
129
If the leader goes down:
151
130
152
-
-**Search continues**: replicas still serve search results for all replicated shards
153
-
-**Writes are blocked**: no documents can be added or updated until a leader is available
131
+
-**Search may be affected**: if search requests are routed to the downed leader, they will fail
132
+
-**Writes are blocked**: no documents can be added or updated until a leader is available. Note that alive remote instances continue to process tasks
154
133
-**Manual promotion**: you must designate a new leader by updating the network topology with `PATCH /network` and setting `"leader"` to another instance
Copy file name to clipboardExpand all lines: resources/self_hosting/sharding/manage_network.mdx
+51-19Lines changed: 51 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,14 @@
1
1
---
2
2
title: Manage the network
3
3
sidebarTitle: Manage the network
4
-
description: Add and remove remotes, update shard assignments, and manage your Meilisearch network topology dynamically.
4
+
description: Add remotes, update shard assignments, and manage your Meilisearch network topology dynamically. Includes rebalancing behavior and validation rules.
5
5
---
6
6
7
7
Once your [sharded cluster is set up](/resources/self_hosting/sharding/setup_sharded_cluster), you can modify the topology without restarting instances. All topology changes go through `PATCH /network` on the leader instance.
8
8
9
9
## Add a remote
10
10
11
-
Use `addRemotes` to add a new instance to the network without rewriting the entire`remotes`configuration:
11
+
Include the new remote in the `remotes` object. To assign it to an existing shard, either send the full`remotes`list for that shard, or use `addRemotes` as a convenience to append without rewriting the full list:
12
12
13
13
<CodeGroup>
14
14
@@ -18,22 +18,36 @@ curl \
18
18
-H 'Content-Type: application/json' \
19
19
-H 'Authorization: Bearer MEILISEARCH_KEY' \
20
20
--data-binary '{
21
-
"addRemotes": {
21
+
"remotes": {
22
22
"ms-03": {
23
23
"url": "http://ms-03.example.com:7703",
24
-
"searchApiKey": "SEARCH_KEY_03"
24
+
"searchApiKey": "SEARCH_KEY_03",
25
+
"writeApiKey": "WRITE_KEY_03"
25
26
}
27
+
},
28
+
"shards": {
29
+
"shard-a": { "addRemotes": ["ms-03"] }
26
30
}
27
31
}'
28
32
```
29
33
30
34
</CodeGroup>
31
35
32
-
After adding the remote, update your shard configuration to assign shards to it.
36
+
<Note>
37
+
`addRemotes` and `removeRemotes` are write-only convenience fields. They are applied on top of the existing shard configuration and are never returned by `GET /network`, which always returns the full `remotes` list for each shard.
38
+
</Note>
39
+
40
+
## Update shard assignments
41
+
42
+
Each shard object in a `PATCH /network` request accepts three fields:
33
43
34
-
## Remove a remote
44
+
| Field | Type | Behavior |
45
+
|-------|------|----------|
46
+
|`remotes`| array | Full replacement of the shard's remote list |
47
+
|`addRemotes`| array | Adds remotes to the existing list |
48
+
|`removeRemotes`| array | Removes remotes from the existing list, applied after `addRemotes`|
35
49
36
-
Use `removeRemotes` to take an instance out of the network:
50
+
Shards not included in the request are left unchanged. To remove a remote from a specific shard:
37
51
38
52
<CodeGroup>
39
53
@@ -43,19 +57,15 @@ curl \
43
57
-H 'Content-Type: application/json' \
44
58
-H 'Authorization: Bearer MEILISEARCH_KEY' \
45
59
--data-binary '{
46
-
"removeRemotes": ["ms-03"]
60
+
"shards": {
61
+
"shard-a": { "removeRemotes": ["ms-03"] }
62
+
}
47
63
}'
48
64
```
49
65
50
66
</CodeGroup>
51
67
52
-
<Warning>
53
-
Before removing a remote, make sure its shards are replicated on other remotes. Removing the only remote holding a shard makes that data unavailable for network searches.
54
-
</Warning>
55
-
56
-
## Update shard assignments
57
-
58
-
Reassign shards to different remotes by sending a new `shards` configuration:
68
+
To fully replace a shard's assignment, use `remotes`:
59
69
60
70
<CodeGroup>
61
71
@@ -75,6 +85,29 @@ curl \
75
85
76
86
</CodeGroup>
77
87
88
+
## Topology changes and rebalancing
89
+
90
+
When you modify shard assignments, Meilisearch triggers a `NetworkTopologyChange` task on all remotes. This task runs in three steps:
91
+
92
+
1.**Compute new shards**: each instance uses rendezvous hashing on document IDs to determine which documents belong to which shard under the new topology.
93
+
2.**Export and import**: documents are sent to remotes that now own them.
94
+
3.**Delete stale data**: once all remotes confirm their imports are complete, each instance deletes the documents it no longer owns. Search switches to the new shard definitions at this point.
95
+
96
+
Cancelling a topology change at step 3 only results in stale documents being retained temporarily. It does not cause data loss.
97
+
98
+
<Warning>
99
+
Search requests may return incomplete results during a topology change. Wait for all `NetworkTopologyChange` tasks to complete before resuming normal search traffic.
100
+
</Warning>
101
+
102
+
## Validation
103
+
104
+
`PATCH /network` rejects requests with a `400 invalid_network_shards` error in the following cases:
105
+
106
+
- The shard list would become empty after applying the patch
107
+
- A shard's `remotes` list would become empty after applying `removeRemotes`
108
+
- A shard references a remote that is not in the `remotes` object
109
+
- A remote is removed from `remotes` and this leaves a shard with no remotes
110
+
78
111
## Filter searches by shard
79
112
80
113
Target specific shards using the `_shard` filter in search requests:
Copy file name to clipboardExpand all lines: resources/self_hosting/sharding/overview.mdx
+31-26Lines changed: 31 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,30 +14,29 @@ Replication and sharding require the Meilisearch Enterprise Edition v1.37 or lat
14
14
15
15
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.
16
16
17
-
When a user searches, Meilisearch queries all remotes in the network, collects results from each shard, and merges them into a single ranked response, as if the data lived on one machine.
17
+
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.
18
18
19
19
## What is replication?
20
20
21
-
Replication assigns the same shard to more than one remote. If one remote becomes unavailable, another remote holding the same shard continues serving results. Meilisearch automatically queries each shard exactly once, avoiding duplicate results even when shards are replicated.
21
+
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.
22
22
23
23
## How it works
24
24
25
25
```mermaid
26
26
graph TD
27
-
Client[Client application] -->|search with useNetwork: true| Leader[Leader instance]
Client[Client application] -->|search with useNetwork: true| Any[Any instance]
28
+
Any -->|fan out| R1[Remote ms-00<br/>shard-a, shard-c]
29
+
Any -->|fan out| R2[Remote ms-01<br/>shard-a, shard-b]
30
+
Any -->|fan out| R3[Remote ms-02<br/>shard-b, shard-c]
31
+
R1 -->|partial results| Any
32
+
R2 -->|partial results| Any
33
+
R3 -->|partial results| Any
34
+
Any -->|merged results| Client
35
35
```
36
36
37
-
1.**Network**: all instances register with each other through the `/network` endpoint, forming a topology with a designated leader
38
-
2.**Shards**: the leader distributes document subsets across remotes based on shard assignments
39
-
3.**Search**: when `useNetwork: true` is set, the leader fans out the search to all remotes, then merges and ranks the combined results
40
-
4.**Failover**: if a remote is down, another remote holding the same shard serves those results
37
+
1.**Network**: the user configures the topology via `/network` on the leader, and this instance propagates it to all remotes
38
+
2.**Shards**: Remotes distribute the subsets of documents across themselves based on shard assignments
39
+
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
41
40
42
41
## When to use sharding and replication
43
42
@@ -54,14 +53,18 @@ All instances in a Meilisearch network share a topology configuration that defin
54
53
55
54
-**`self`**: the identity of the current instance
56
55
-**`leader`**: the instance coordinating writes and topology changes
57
-
-**`remotes`**: all instances in the network with their URLsand search API keys
56
+
-**`remotes`**: all instances in the network with their URLs, search API keys, and write API keys
58
57
-**`shards`**: how document subsets are distributed across remotes
59
58
60
-
The leader instance is responsible for write operations. Non-leader instances reject write requests (document additions, settings changes, index creation) with a `not_a_leader` error.
59
+
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.
61
60
62
61
## Searching across the network
63
62
64
-
To search across all instances, add `useNetwork: true` to your search request:
63
+
To search across all instances:
64
+
65
+
<Note>
66
+
`useNetwork` defaults to `true` when a network topology is defined.
67
+
</Note>
65
68
66
69
<CodeGroup>
67
70
@@ -71,8 +74,7 @@ curl \
71
74
-H 'Content-Type: application/json' \
72
75
-H 'Authorization: Bearer MEILISEARCH_KEY' \
73
76
--data-binary '{
74
-
"q": "batman",
75
-
"useNetwork": true
77
+
"q": "batman"
76
78
}'
77
79
```
78
80
@@ -83,7 +85,6 @@ The response includes `_federation` metadata showing which remote each result ca
| Multi-search | Yes |Works per query; `useNetwork` defaults to `true`when a network is configured|
124
125
| Federated search | Yes | Federation merges results from both indexes and remotes |
125
126
| Analytics | Partial | Events are tracked on the instance that receives the search request |
126
127
| Tenant tokens | Yes | Token filters apply on each remote |
127
128
| Document operations | Leader only | Writes must go through the leader instance |
128
129
| Settings changes | Leader only | Settings updates must go through the leader |
129
-
| Conversational search | Yes | Chat queries can use network search |
130
+
| Conversational search | No | Chat completions do not support `useNetwork`|
131
+
132
+
<Warning>
133
+
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.
134
+
</Warning>
130
135
131
136
## Prerequisites
132
137
@@ -147,7 +152,7 @@ Before setting up sharding and replication, you need:
147
152
Set up replicated shards for high availability and read scaling.
148
153
</Card>
149
154
<Cardtitle="Manage the network"href="/resources/self_hosting/sharding/manage_network">
150
-
Add and remove remotes, update topology, and handle failover.
0 commit comments