Skip to main content
Sharding is the process of splitting an index containing many documents into multiple smaller indexes, often called shards. This horizontal scaling technique is useful when handling large databases. Replicated sharding adds the constraint that a shard is stored in several Meilisearch instances, guaranteeing document availability even when an individual instance is not available. This guide walks you through activating the /network route, configuring the network object, and performing search across all shards. Sharding is an Enterprise Edition feature. You are free to use it for evaluation purposes. Please reach out to us before using it in production.

​
Prerequisites

  • Multiple Meilisearch projects (instances) running Meilisearch >=v1.35

​
Activate the /network endpoint

​
Meilisearch Cloud

If you are using Meilisearch Cloud, contact support to enable this feature in your projects.

​
Self-hosting

Use the /experimental-features route to enable network: 
curl \
  -X PATCH 'MEILISEARCH_URL/experimental-features/' \
  -H 'Content-Type: application/json'  \
  --data-binary '{
    "network": true
  }'
Meilisearch should respond immediately, confirming the route is now accessible. Repeat this process for all instances.

​
Configuring the network object

If you are using Meilisearch Cloud, then you can skip this section. Self-hosted users must configure the network object. It consists of the following fields:
  • remotes: defines a list with the required information to access each remote instance
  • self: specifies which of the configured remotes corresponds to the current instance
  • leader: specifies which of the configured remotes is the leader of the network. Setting this field will enable sharding.
  • shards: defines a list of shards representing the various pieces of the index data to split between the remotes.

​
Setting up the list of remotes

Use the /network route to configure the remotes field of the network object. remotes should be an object containing one or more objects. Each one of the nested objects should consist of the name of each instance, associated with its URL, an API key with search permission, and an API key with write permission: 
curl \
  -X PATCH 'MEILISEARCH_URL/network' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "remotes": {
      "REMOTE_NAME_1": {
        "url": "INSTANCE_URL_1",
        "searchApiKey": "SEARCH_API_KEY_1",
        "writeApiKey": "WRITE_API_KEY_1"
      },
      "REMOTE_NAME_2": {
        "url": "INSTANCE_URL_2",
        "searchApiKey": "SEARCH_API_KEY_2",
        "writeApiKey": "WRITE_API_KEY_2"
      },
      "REMOTE_NAME_3": {
        "url": "INSTANCE_URL_3",
        "searchApiKey": "SEARCH_API_KEY_3",
        "writeApiKey": "WRITE_API_KEY_3"
      },
      …
    }
  }'

​
Pick a leader instance

In a Meilisearch network, the leader will be responsible for:
  • Receiving any task that modifies the state of the Meilisearch instance: document additions, settings change, etc.
    • Any task will be replicated to the remote instances of the network.
    • If you send a task to a non-leader remote instance, the task will not be registered and a 400 BAD REQUEST HTTP error code will be emitted.
  • Receiving network change requests.
    • They will be propagated to the rest of the network.
curl \
  -X PATCH 'MEILISEARCH_URL/network' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "leader": "REMOTE_NAME_1",
    "remotes": {
      "REMOTE_NAME_1": {
        "url": "INSTANCE_URL_1",
        "searchApiKey": "SEARCH_API_KEY_1",
        "writeApiKey": "WRITE_API_KEY_1"
      },
      "REMOTE_NAME_2": {
        "url": "INSTANCE_URL_2",
        "searchApiKey": "SEARCH_API_KEY_2",
        "writeApiKey": "WRITE_API_KEY_2"
      },
      "REMOTE_NAME_3": {
        "url": "INSTANCE_URL_3",
        "searchApiKey": "SEARCH_API_KEY_3",
        "writeApiKey": "WRITE_API_KEY_3"
      },
      …
    }
  }'

​
Specify the name of the current instance

Since the network change payload must be sent to the leader, this is always the same as the leader: 
curl \
  -X PATCH 'MEILISEARCH_URL/network' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "self": "REMOTE_NAME_1",
    "leader": "REMOTE_NAME_1",
    "remotes": {
      "REMOTE_NAME_1": {
        "url": "INSTANCE_URL_1",
        "searchApiKey": "SEARCH_API_KEY_1",
        "writeApiKey": "WRITE_API_KEY_1"
      },
      "REMOTE_NAME_2": {
        "url": "INSTANCE_URL_2",
        "searchApiKey": "SEARCH_API_KEY_2",
        "writeApiKey": "WRITE_API_KEY_2"
      },
      "REMOTE_NAME_3": {
        "url": "INSTANCE_URL_3",
        "searchApiKey": "SEARCH_API_KEY_3",
        "writeApiKey": "WRITE_API_KEY_3"
      },
      …
    }
  }'
Meilisearch processes searches on the remote that corresponds to self locally instead of making a remote request.

​
Setting up the list of shards

Shards are a list of named entries, each specifying a list of remotes that should own that shard. The same shard can be owned by multiple remotes, and remotes can own multiple shards, allowing to fine-tune how data is sharded and replicated in the network. 
curl \
  -X PATCH 'MEILISEARCH_URL/network' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "shards": {
      "SHARD_NAME_1": {
        "remotes": ["REMOTE_NAME_1", "REMOTE_NAME_2"]
      },
      "SHARD_NAME_2": {
        "remotes": ["REMOTE_NAME_2", "REMOTE_NAME_3"]
      },
      "SHARD_NAME_3": {
        "remotes": ["REMOTE_NAME_3", "REMOTE_NAME_1"]
      }
    },
    "self": "REMOTE_NAME_1",
    "leader": "REMOTE_NAME_1",
    "remotes": {
      "REMOTE_NAME_1": {
        "url": "INSTANCE_URL_1",
        "searchApiKey": "SEARCH_API_KEY_1",
        "writeApiKey": "WRITE_API_KEY_1"
      },
      "REMOTE_NAME_2": {
        "url": "INSTANCE_URL_2",
        "searchApiKey": "SEARCH_API_KEY_2",
        "writeApiKey": "WRITE_API_KEY_2"
      },
      "REMOTE_NAME_3": {
        "url": "INSTANCE_URL_3",
        "searchApiKey": "SEARCH_API_KEY_3",
        "writeApiKey": "WRITE_API_KEY_3"
      },
      …
    }
  }'
This example demonstrates a mixed sharding and replication setup: each remote owns 60% of the documents (2 out of 3 shards), and losing 1 out of 3 remotes never causes a loss of documents, achieving replication.

​
Adding or removing an instance or shard

Changing the topology of the network involves moving some documents from an instance to another. Meilisearch will rebalance documents automatically depending on the change in network topology, via a NetworkTopologyChange task on all remotes of the network.

​
Add documents

Send your documents to the designated leader. Documents will be replicated to the other instances. Each instance will index the documents they are responsible for and ignore the others.

​
Updating index settings

Changing settings in a sharded database is not fundamentally different from changing settings on a single Meilisearch instance. If the update enables a feature, such as setting filterable attributes, wait until all changes have been processed before using the filter search parameter in a query. Likewise, if an update disables a feature, first remove it from your search requests, then update your settings. When sharding is enabled, your search requests will happen over all instances of the network automatically. To disable this behavior and force the request to be executed solely locally, add useNetwork: false to your search requests. 
curl \
  -X POST 'MEILISEARCH_URL/indexes/INDEX_A/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "batman",
    "useNetwork": false
  }'