Manage the network

Once your sharded cluster is set up, you can modify the topology without restarting instances. All topology changes go through PATCH /network on the leader instance.

Add a remote

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:

curl \
  -X PATCH 'MEILISEARCH_URL/network' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "remotes": {
      "ms-03": {
        "url": "http://ms-03.example.com:7703",
        "searchApiKey": "SEARCH_KEY_03",
        "writeApiKey": "WRITE_KEY_03"
      }
    },
    "shards": {
      "shard-a": { "addRemotes": ["ms-03"] }
    }
  }'

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.

Update shard assignments

Each shard object in a PATCH /network request accepts three fields:

Field	Type	Behavior
`remotes`	array	Full replacement of the shard’s remote list
`addRemotes`	array	Adds remotes to the existing list
`removeRemotes`	array	Removes remotes from the existing list, applied after `addRemotes`

Shards not included in the request are left unchanged. To remove a remote from a specific shard:

curl \
  -X PATCH 'MEILISEARCH_URL/network' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "shards": {
      "shard-a": { "removeRemotes": ["ms-03"] }
    }
  }'

To fully replace a shard’s assignment, use remotes:

curl \
  -X PATCH 'MEILISEARCH_URL/network' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "shards": {
      "shard-a": { "remotes": ["ms-00", "ms-01", "ms-03"] },
      "shard-b": { "remotes": ["ms-01", "ms-02"] },
      "shard-c": { "remotes": ["ms-02", "ms-03"] }
    }
  }'

Topology changes and rebalancing

When you modify shard assignments, Meilisearch triggers a NetworkTopologyChange task on all remotes. This task runs in three steps:

Compute new shards: each instance uses rendezvous hashing on document IDs to determine which documents belong to which shard under the new topology.
Export and import: documents are sent to remotes that now own them.
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.

Cancelling a topology change at step 3 only results in stale documents being retained temporarily. It does not cause data loss.

Search requests may return incomplete results during a topology change. Wait for all NetworkTopologyChange tasks to complete before resuming normal search traffic.

Run the same Meilisearch version on all instances before rebalancing. Network rebalancing is not guaranteed to work across instances on different versions.

Validation

PATCH /network rejects requests with a 400 invalid_network_shards error in the following cases:

The shard list would become empty after applying the patch
A shard’s remotes list would become empty after applying removeRemotes
A shard references a remote that is not in the remotes object
A remote is removed from remotes and this leaves a shard with no remotes

Filter searches by shard

Target specific shards using the _shard filter in search requests:

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

Supported _shard filter operators:

Syntax	Behavior
`_shard = "shard-a"`	Documents associated to `shard-a`
`_shard != "shard-a"`	Documents associated to all shards except `shard-a`
`_shard IN ["shard-a", "shard-b"]`	Documents associated to both `shard-a` and `shard-b`

Attribute visibility via `/network`

If an attribute is not on the displayedAttributes list but is present on sortableAttributes, its value can become publicly accessible through the /network endpoint. Do not enable the network feature if you rely on the value of attributes not present in displayedAttributes to remain hidden at all times. Either add such attributes to displayedAttributes so their exposure is explicit, or remove them from sortableAttributes before opting into network search.

Private network security

By default, Meilisearch blocks requests to non-global IP addresses. If your instances communicate over a private network, configure the --experimental-allowed-ip-networks flag on each instance:

meilisearch --experimental-allowed-ip-networks 10.0.0.0/8,192.168.0.0/16

Only allow the CIDR ranges your instances actually use.

Next steps

Replication and sharding overview

Understand the concepts behind sharding, replication, and network search.

Deployment overview

Deploy Meilisearch to production on various cloud providers.

Comparisons

Migration

Self-hosting

Demos

Under the hood

Other resources

Add a remote

Update shard assignments

Topology changes and rebalancing

Validation

Filter searches by shard

Attribute visibility via `/network`

Private network security

Next steps

Replication and sharding overview

Deployment overview

​Add a remote

​Update shard assignments

​Topology changes and rebalancing

​Validation

​Filter searches by shard

​Attribute visibility via /network

​Private network security

​Next steps

Replication and sharding overview

Deployment overview

Add a remote

Update shard assignments

Topology changes and rebalancing

Validation

Filter searches by shard

Attribute visibility via `/network`

Private network security

Next steps