> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Routing with mongos

MongoDB [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instances route queries and write operations to [shards](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-shard) in a sharded cluster. `mongos` provides the only interface to a sharded cluster from the perspective of applications. Applications never connect or communicate directly with the shards.

The `mongos` tracks what data is on which shard by caching the metadata from the [config servers](https://www.mongodb.com/docs/manual/core/sharded-cluster-config-servers.md#std-label-sharded-cluster-config-server). The `mongos` uses the metadata to route operations from applications and clients to the [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instances. A `mongos` has no *persistent* state and consumes minimal system resources.

The most common practice is to run `mongos` instances on the same systems as your application servers, but you can maintain `mongos` instances on the shards or on other dedicated resources.  See also [Number of `mongos` and Distribution.](https://www.mongodb.com/docs/manual/core/sharded-cluster-components.md#std-label-sharded-cluster-components-distribution)

## Routing And Results Process

A [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance routes a query to a [cluster](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-sharded-cluster) by:

1. Determining the list of [shards](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-shard) that must receive the query.

2. Establishing a cursor on all targeted shards.

The `mongos` then merges the data from each of the targeted shards and returns the result document. Certain query modifiers, such as [sorting](https://www.mongodb.com/docs/manual/core/sharded-cluster-query-router.md#std-label-sharding-mongos-sort), are performed on each shard before `mongos` retrieves the results.

[Aggregation operations](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-aggregation-pipeline) running on multiple shards may route results back to the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) to merge results if they don't need to run on the database's [primary shard.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary-shard)

There are two cases in which a pipeline is ineligible to run on [`mongos`.](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos)

The first case occurs when the merge part of the split pipeline contains a stage which *must* run on a specific shard. For instance, if `$lookup` requires access to an unsharded collection in the same database as the sharded collection on which the aggregation is running, the merge runs on the shard that hosts the unsharded collection.

The second case occurs when the merge part of the split pipeline contains a stage which may write temporary data to disk, such as `$group`, and the client has specified `allowDiskUse:true`. In this case, assuming that there are no other stages in the merge pipeline which require the primary shard, the merge runs on a randomly-selected shard in the set of shards targeted by the aggregation.

For more information on how the work of aggregation is split among components of a sharded cluster query, use `explain:true` as a parameter to the [`aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) call. The return includes three JSON objects:

- `mergeType` shows where the stage of the merge happens ("anyShard", "specificShard", or "router"). When `mergeType` is `specificShard`, the aggregate output includes a `mergeShard` property that contains the shard ID of the merging shard.

- `splitPipeline` shows which operations in your pipeline have run on individual shards.

- `shards` shows the work each shard has done.

In some cases, when the [shard key](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-shard-key) or a prefix of the shard key is a part of the query, the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) performs a [targeted operation](https://www.mongodb.com/docs/manual/core/sharded-cluster-query-router.md#std-label-sharding-mongos-targeted), routing queries to a subset of shards in the cluster.

`mongos` performs a [broadcast operation](https://www.mongodb.com/docs/manual/core/sharded-cluster-query-router.md#std-label-sharding-mongos-broadcast) for queries that do *not* include the [shard key](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-shard-key), routing queries to *all* shards in the cluster. Some queries that do include the shard key may still result in a broadcast operation depending on the distribution of data in the cluster and the selectivity of the query.

See [Targeted Operations vs. Broadcast Operations](https://www.mongodb.com/docs/manual/core/sharded-cluster-query-router.md#std-label-sharding-query-isolation) for more on targeted and broadcast operations.

## How `mongos` Handles Query Modifiers

### Sorting

If the result of the query is not sorted, the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance opens a result cursor that "round robins" results from all cursors on the shards.

### Limits

If the query limits the size of the result set using the [`limit()`](https://www.mongodb.com/docs/manual/reference/method/cursor.limit.md#mongodb-method-cursor.limit) cursor method, the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance passes that limit to the shards and then re-applies the limit to the result before returning the result to the client.

### Skips

If the query specifies a number of records to *skip* using the [`skip()`](https://www.mongodb.com/docs/manual/reference/method/cursor.skip.md#mongodb-method-cursor.skip) cursor method, the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) *cannot* pass the skip to the shards, but rather retrieves unskipped results from the shards and skips the appropriate number of documents when assembling the complete result.

When used in conjunction with a [`limit()`](https://www.mongodb.com/docs/manual/reference/method/cursor.limit.md#mongodb-method-cursor.limit), the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) passes the *limit* plus the value of the [`skip()`](https://www.mongodb.com/docs/manual/reference/method/cursor.skip.md#mongodb-method-cursor.skip) to the shards to improve the efficiency of these operations.

## Read Preference and Shards

For sharded clusters, [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) applies the [read preference](https://www.mongodb.com/docs/manual/core/read-preference.md) when reading from the shards. The member selected is governed by both the [read preference](https://www.mongodb.com/docs/manual/core/read-preference.md) and [`replication.localPingThresholdMs`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-replication.localPingThresholdMs) settings, and is re-evaluated for each operation.

For details on read preference and sharded clusters, see [Read Preference and Shards.](https://www.mongodb.com/docs/manual/core/read-preference-mechanics.md#std-label-read-preference-mechanics-sharded-cluster)

## Confirm Connection to `mongos` Instances

To detect if the MongoDB instance that your client is connected to is [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos), use the [`hello`](https://www.mongodb.com/docs/manual/reference/command/hello.md#mongodb-dbcommand-dbcmd.hello) command. When a client connects to a [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos), [`hello`](https://www.mongodb.com/docs/manual/reference/command/hello.md#mongodb-dbcommand-dbcmd.hello) returns a document with a `msg` field that holds the string `isdbgrid`. For example:

```javascript
{
   "isWritablePrimary" : true,
   "msg" : "isdbgrid",
   "maxBsonObjectSize" : 16777216,
   "ok" : 1,
   ...
}
```

If the application is instead connected to a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod), the returned document does not include the `isdbgrid` string.

## Targeted Operations vs. Broadcast Operations

Generally, the fastest queries in a sharded environment are those that [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) route to a single shard, using the [shard key](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-shard-key) and the cluster meta data from the [config server](https://www.mongodb.com/docs/manual/core/sharded-cluster-config-servers.md#std-label-sharding-config-server). These [targeted operations](https://www.mongodb.com/docs/manual/core/sharded-cluster-query-router.md#std-label-sharding-mongos-targeted) use the shard key value to locate the shard or subset of shards that satisfy the query document.

For queries that don't include the shard key, [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) must query all shards, wait for their responses and then return the result to the application. These "scatter/gather" queries can be long running operations.

### Broadcast Operations

[`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instances broadcast queries to all shards for the collection **unless** the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) can determine which shard or subset of shards stores this data.

![Scatter-gather query: \`\`mongos\`\` broadcasts to all shards when no shard key is specified.](/images/sharded-cluster-scatter-gather-query.bakedsvg.svg)

After the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) receives responses from all shards, it merges the data and returns the result document. The performance of a broadcast operation depends on the overall load of the cluster, as well as variables like network latency, individual shard load, and number of documents returned per shard. Whenever possible, favor operations that result in [targeted operation](https://www.mongodb.com/docs/manual/core/sharded-cluster-query-router.md#std-label-sharding-mongos-targeted) over those that result in a broadcast operation.

Multi-update operations are always broadcast operations.

The [`updateMany()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.updatemany.md#mongodb-method-db.collection.updateMany) and [`deleteMany()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.deletemany.md#mongodb-method-db.collection.deleteMany) methods are broadcast operations, unless the query document specifies the shard key in full.

### Targeted Operations

[`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) can route queries that include the shard key or the prefix of a [compound](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-compound-index) shard key a specific shard or set of shards. [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) uses the shard key value to locate the [chunk](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-chunk) whose range includes the shard key value and directs the query at the [shard](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-shard) containing that chunk.

![Targeted query: \`\`mongos\`\` routes to specific shards when the shard key is included.](/images/sharded-cluster-targeted-query.bakedsvg.svg)

For example, if the shard key is:

```javascript
{ a: 1, b: 1, c: 1 }
```

The [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) program *can* route queries that include the full shard key or either of the following shard key prefixes at a specific shard or set of shards:

```javascript
{ a: 1 }
{ a: 1, b: 1 }
```

All [`insertOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertone.md#mongodb-method-db.collection.insertOne) operations target to one shard. Each document in the [`insertMany()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertmany.md#mongodb-method-db.collection.insertMany) array targets to a single shard, but there is no guarantee all documents in the array insert into a single shard.

All [`updateOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.updateone.md#mongodb-method-db.collection.updateOne), [`replaceOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.replaceone.md#mongodb-method-db.collection.replaceOne) and [`deleteOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteone.md#mongodb-method-db.collection.deleteOne) operations *must* include the [shard key](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-shard-key) or `_id` in the query document. MongoDB returns an error if these methods are used without the shard key or `_id`.

Depending on the distribution of data in the cluster and the selectivity of the query, [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) may still perform a [broadcast operation](https://www.mongodb.com/docs/manual/core/sharded-cluster-query-router.md#std-label-sharding-mongos-broadcast) to fulfill these queries.

### Index Use

When a shard receives a query, it uses the most efficient index available to fulfill that query. The index used may be either the [shard key index](https://www.mongodb.com/docs/manual/core/sharding-shard-key-indexes.md#std-label-sharding-shard-key-indexes) or another eligible index present on the shard.

## Sharded Cluster Security

Use [Self-Managed Internal/Membership Authentication](https://www.mongodb.com/docs/manual/core/security-internal-authentication.md) to enforce intra-cluster security and prevent unauthorized cluster components from accessing the cluster. You must start each [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) in the cluster with the appropriate security settings in order to enforce internal authentication.

Starting in MongoDB 5.3, [SCRAM-SHA-1](https://www.mongodb.com/docs/manual/core/security-scram.md#std-label-authentication-scram-sha-1) cannot be used for intra-cluster authentication. Only [SCRAM-SHA-256](https://www.mongodb.com/docs/manual/core/security-scram.md#std-label-authentication-scram-sha-256) is supported.

In previous MongoDB versions, SCRAM-SHA-1 and SCRAM-SHA-256 can both be used for intra-cluster authentication, even if SCRAM is not explicitly enabled.

See [Keyfile Authentication for Self-Managed Sharded Clusters](https://www.mongodb.com/docs/manual/tutorial/deploy-sharded-cluster-with-keyfile-access-control.md) for a tutorial on deploying a secured sharded cluster.

### Cluster Users

Sharded clusters support [Role-Based Access Control in Self-Managed Deployments](https://www.mongodb.com/docs/manual/core/authorization.md) *(RBAC)* for restricting unauthorized access to cluster data and operations. You must start each [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) in the cluster, including the [config servers](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-config-server), with the [`--auth`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--auth) option in order to enforce RBAC. Alternatively, enforcing [Self-Managed Internal/Membership Authentication](https://www.mongodb.com/docs/manual/core/security-internal-authentication.md) for inter-cluster security also enables user access controls via RBAC.

With RBAC enforced, clients must specify a [`--username`](https://www.mongodb.com/docs/mongodb-shell/reference/options.md#std-option-mongosh.--username), [`--password`](https://www.mongodb.com/docs/mongodb-shell/reference/options.md#std-option-mongosh.--password), and [`--authenticationDatabase`](https://www.mongodb.com/docs/mongodb-shell/reference/options.md#std-option-mongosh.--authenticationDatabase) when connecting to the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) in order to access cluster resources.

Each cluster has its own cluster users. These users cannot be used to access individual shards.

See [Enable Access Control on Self-Managed Deployments](https://www.mongodb.com/docs/manual/tutorial/enable-authentication.md) for a tutorial on enabling adding users to an RBAC-enabled MongoDB deployment.

## Metadata Operations

[`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) uses [`"majority"`](https://www.mongodb.com/docs/manual/reference/write-concern.md#mongodb-writeconcern-writeconcern.-majority-) write concern for the following operations that affect the sharded cluster metadata:

| Command | Method |
| --- | --- |
| [`addShard`](https://www.mongodb.com/docs/manual/reference/command/addshard.md#mongodb-dbcommand-dbcmd.addShard) | [`sh.addShard()`](https://www.mongodb.com/docs/manual/reference/method/sh.addshard.md#mongodb-method-sh.addShard) |
| [`create`](https://www.mongodb.com/docs/manual/reference/command/create.md#mongodb-dbcommand-dbcmd.create) | [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createcollection.md#mongodb-method-db.createCollection) |
| [`drop`](https://www.mongodb.com/docs/manual/reference/command/drop.md#mongodb-dbcommand-dbcmd.drop) | [`db.collection.drop()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.drop.md#mongodb-method-db.collection.drop) |
| [`dropDatabase`](https://www.mongodb.com/docs/manual/reference/command/dropdatabase.md#mongodb-dbcommand-dbcmd.dropDatabase) | [`db.dropDatabase()`](https://www.mongodb.com/docs/manual/reference/method/db.dropdatabase.md#mongodb-method-db.dropDatabase) |
| [`enableSharding`](https://www.mongodb.com/docs/manual/reference/command/enablesharding.md#mongodb-dbcommand-dbcmd.enableSharding) | [`sh.enableSharding()`](https://www.mongodb.com/docs/manual/reference/method/sh.enablesharding.md#mongodb-method-sh.enableSharding) |
| [`movePrimary`](https://www.mongodb.com/docs/manual/reference/command/moveprimary.md#mongodb-dbcommand-dbcmd.movePrimary) | |
| [`renameCollection`](https://www.mongodb.com/docs/manual/reference/command/renamecollection.md#mongodb-dbcommand-dbcmd.renameCollection) | [`db.collection.renameCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.renamecollection.md#mongodb-method-db.collection.renameCollection) |
| [`shardCollection`](https://www.mongodb.com/docs/manual/reference/command/shardcollection.md#mongodb-dbcommand-dbcmd.shardCollection) | [`sh.shardCollection()`](https://www.mongodb.com/docs/manual/reference/method/sh.shardcollection.md#mongodb-method-sh.shardCollection) |
| [`removeShard`](https://www.mongodb.com/docs/manual/reference/command/removeshard.md#mongodb-dbcommand-dbcmd.removeShard) | |
| [`setFeatureCompatibilityVersion`](https://www.mongodb.com/docs/manual/reference/command/setfeaturecompatibilityversion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion) | |

## Additional Information

### FCV Compatibility

The [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) binary cannot connect to [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instances whose [feature compatibility version (FCV)](https://www.mongodb.com/docs/manual/reference/command/setfeaturecompatibilityversion.md#std-label-view-fcv) is greater than that of the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos). For example, you cannot connect a MongoDB 4.0 version [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) to a 4.2 sharded cluster with [FCV](https://www.mongodb.com/docs/manual/reference/command/setfeaturecompatibilityversion.md#std-label-view-fcv) set to 4.2. You can, however, connect a MongoDB 4.0 version [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) to a 4.2 sharded cluster with [FCV](https://www.mongodb.com/docs/manual/reference/command/setfeaturecompatibilityversion.md#std-label-view-fcv) set to 4.0.

### Full Time Diagnostic Data Capture Requirements

[`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) includes a [Full Time Diagnostic Data Capture](https://www.mongodb.com/docs/manual/administration/full-time-diagnostic-data-capture.md#std-label-ftdc-stub) mechanism to assist MongoDB engineers with troubleshooting deployments. If this thread fails, it terminates the originating process. To avoid the most common failures, confirm that the user running the process has permissions to create the FTDC `diagnostic.data` directory. For `mongod` the directory is within [`storage.dbPath`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-storage.dbPath). For `mongos` it is parallel to [`systemLog.path`.](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-systemLog.path)

### Connection Pools

Starting in MongoDB 4.2, MongoDB adds the parameter [`ShardingTaskExecutorPoolReplicaSetMatching`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.ShardingTaskExecutorPoolReplicaSetMatching). This parameter determines the minimum size of the [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) / [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance's connection pool to each member of the sharded cluster. This value can vary during runtime.

[`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) and [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) maintain connection pools to each replica set secondary for every replica set in the sharded cluster. By default, these pools have a number of connections that is at least the number of connections to the primary.

To modify, see [`ShardingTaskExecutorPoolReplicaSetMatching`.](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.ShardingTaskExecutorPoolReplicaSetMatching)

### Using Aggregation Pipelines with Clusters

For more information on how sharding works with [aggregations](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-aggregation-pipeline), read the sharding chapter in the [Practical MongoDB Aggregations](https://www.practical-mongodb-aggregations.com/guides/sharding.html) e-book.