Apply Kerollmops review: remove useNetwork from examples, simplify replication description, full-sharding setup, no-fallback note, fix wording throughout

Author: qdequele

resources/self_hosting/sharding/configure_replication.mdx

@@ -12,7 +12,7 @@ Replication requires the Meilisearch Enterprise Edition v1.37 or later and a [co
 
 ## How replication works
 
-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.
+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.
 
 ## Assign shards to multiple remotes
 
@@ -83,15 +83,13 @@ Place replicas in different regions to reduce latency for geographically distrib
 }
 ```
 
-Route search requests to the closest cluster. Both regions hold all data, so either can serve a full result set.
+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.
 
 ## Remote availability
 
-When a network search runs, Meilisearch builds an internal partition: it assigns each shard to exactly one remote, then sends one query per remote with a shard filter. This guarantees no shard is queried twice and results are never duplicated.
+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.
 
-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 retry using another replica that holds the same shard.
-
-To handle remote failures, route search traffic away from unhealthy instances at the infrastructure level (for example, using a load balancer with health checks). When the failed remote comes back online, it can start serving searches again without manual intervention.
+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.
 
 ## Scaling read throughput
 
@@ -130,8 +128,8 @@ The leader is responsible for all write operations (document additions, settings
 
 If the leader goes down:
 
-- **Search may be affected**: if search requests are routed to the downed leader, they will fail. Route search traffic to healthy instances using a load balancer
-- **Writes are blocked**: no documents can be added or updated until a leader is available
+- **Search may be affected**: if search requests are routed to the downed leader, they will fail
+- **Writes are blocked**: no documents can be added or updated until a leader is available. Note that alive remote instances continue to process tasks
 - **Manual promotion**: you must designate a new leader by updating the network topology with `PATCH /network` and setting `"leader"` to another instance
 
 <Warning>

resources/self_hosting/sharding/manage_network.mdx

@@ -89,7 +89,7 @@ curl \
 
 When you modify shard assignments, Meilisearch triggers a `NetworkTopologyChange` task on all remotes. This task runs in three steps:
 
-1. **Compute new shards**: each instance uses rendezvous hashing to determine which documents now belong to which shard under the new topology.
+1. **Compute new shards**: each instance uses rendezvous hashing on document IDs to determine which documents belong to which shard under the new topology.
 2. **Export and import**: documents are sent to remotes that now own them.
 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.
 
@@ -121,7 +121,6 @@ curl \
   -H 'Authorization: Bearer MEILISEARCH_KEY' \
   --data-binary '{
     "q": "batman",
-    "useNetwork": true,
     "filter": "_shard = \"shard-a\""
   }'
 ```
@@ -132,9 +131,9 @@ Supported `_shard` filter operators:
 
 | Syntax | Behavior |
 |--------|----------|
-| `_shard = "shard-a"` | Results from `shard-a` only |
-| `_shard != "shard-a"` | Results from all shards except `shard-a` |
-| `_shard IN ["shard-a", "shard-b"]` | Results from both `shard-a` and `shard-b` |
+| `_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` |
 
 ## Private network security
 

resources/self_hosting/sharding/overview.mdx

@@ -34,9 +34,9 @@ graph TD
     Any -->|merged results| Client
 ```
 
-1. **Network**: the leader configures the topology via `/network` and propagates it to all remotes
-2. **Shards**: the leader distributes document subsets across remotes based on shard assignments
-3. **Search**: when `useNetwork: true` is set, the instance receiving the request fans out the search to all remotes, then merges and ranks the combined results
+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
 
@@ -60,7 +60,11 @@ The leader instance is responsible for write operations and topology changes. No
 
 ## Searching across the network
 
-To search across all instances, add `useNetwork: true` to your search request:
+To search across all instances:
+
+<Note>
+`useNetwork` defaults to `true` when a network topology is defined.
+</Note>
 
 <CodeGroup>
 
@@ -70,8 +74,7 @@ curl \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer MEILISEARCH_KEY' \
   --data-binary '{
-    "q": "batman",
-    "useNetwork": true
+    "q": "batman"
   }'
 ```
 
@@ -82,7 +85,6 @@ The response includes `_federation` metadata showing which remote each result ca
 ```json
 {
   "q": "batman",
-  "useNetwork": true,
   "filter": "_shard = \"shard-a\""
 }
 ```
@@ -100,8 +102,8 @@ curl \
   -H 'Authorization: Bearer MEILISEARCH_KEY' \
   --data-binary '{
     "queries": [
-      { "indexUid": "movies", "q": "batman", "useNetwork": true },
-      { "indexUid": "comics", "q": "batman", "useNetwork": true }
+      { "indexUid": "movies", "q": "batman" },
+      { "indexUid": "comics", "q": "batman" }
     ]
   }'
 ```
@@ -119,7 +121,7 @@ Most Meilisearch features work transparently across a sharded network. The follo
 | 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 | Use `useNetwork: true` per query |
+| 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 |

resources/self_hosting/sharding/setup_sharded_cluster.mdx

@@ -89,16 +89,20 @@ curl \
       }
     },
     "shards": {
-      "shard-a": { "remotes": ["ms-00", "ms-01"] },
-      "shard-b": { "remotes": ["ms-01", "ms-02"] },
-      "shard-c": { "remotes": ["ms-02", "ms-00"] }
+      "shard-a": { "remotes": ["ms-00"] },
+      "shard-b": { "remotes": ["ms-01"] },
+      "shard-c": { "remotes": ["ms-02"] }
     }
   }'
 ```
 
 </CodeGroup>
 
-In this configuration, each shard is replicated across two remotes. If any single instance goes down, all shard data still exists on another instance.
+In this configuration, each shard lives on exactly one remote. Documents are distributed across all three instances, and each instance handles searches for its own shards.
+
+<Note>
+This setup has no replication. If a remote becomes unavailable, its shards are missing from search results — Meilisearch does not yet automatically fall back to another instance. See [Configure replication](/resources/self_hosting/sharding/configure_replication) for a high-availability setup.
+</Note>
 
 ## Step 4: Index documents
 
@@ -126,7 +130,7 @@ All write operations (document additions, updates, deletions, settings changes)
 
 ## Step 5: Search across the cluster
 
-Search requests can be sent to any instance in the network, not just the leader. Add `useNetwork: true` to query all remotes:
+Search requests can be sent to any instance in the network, not just the leader. `useNetwork` defaults to `true` when a network topology is defined:
 
 <CodeGroup>
 
@@ -136,14 +140,13 @@ curl \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer SEARCH_KEY_00' \
   --data-binary '{
-    "q": "batman",
-    "useNetwork": true
+    "q": "batman"
   }'
 ```
 
 </CodeGroup>
 
-Meilisearch fans out the search to all remotes, collects results from each shard, and returns a single merged response.
+Meilisearch fans out the search to all shards, collects results from each shard, and returns a single merged response.
 
 ## Verify the topology