Query from any node in Azure DocumentDB

In a multishard Azure DocumentDB cluster, data is distributed across several physical shards (nodes). By default, every client connection lands on a single node that plans each request and routes it to the physical shards that own the data. That entry node handles connection management, query planning, and result aggregation for the whole cluster.

Query from any node removes that single entry point. When you enable it, every physical shard in the cluster accepts client connections directly and can route queries to any other shard. MongoDB drivers discover all the nodes automatically and spread operations across them, so connection and query-processing capacity grows with the number of physical shards in the cluster.

This article explains how query from any node works, when to use it, how to enable and verify it, and its current limitations.

When to use query from any node

Query from any node is most useful for workloads that issue a large number of small, targeted operations—for example, point reads and single-document writes by shard key—at a high rate. For these workloads, the entry node's CPU and connection capacity can become the limiting factor long before the physical shards that store the data are saturated.

Consider enabling query from any node when:

  • Your cluster has two or more physical shards and your workload is dominated by short, high-frequency reads and writes.
  • Metrics show CPU or connection pressure concentrated on one node while the other physical shards have headroom.
  • You need more concurrent client connections than a single node can accept.

Query from any node doesn't change how data is distributed. Data placement still follows your shard keys, and you still benefit most from a well-chosen shard key that spreads storage and requests evenly across physical shards.

How query from any node works

When you enable query from any node, Azure DocumentDB makes the following changes to the cluster:

  • Every physical shard accepts connections. Each node runs the component that handles MongoDB wire-protocol connections, so a client can connect to any node.
  • Each node gets its own port on the cluster endpoint. All nodes share the cluster host name. You can reach each physical shard on a different TCP port, starting at 10260 and incrementing by one for each additional node (10260, 10261, 10262, and so on).
  • The cluster's DNS SRV records list every node. The SRV record behind the mongodb+srv://<cluster-name>.mongocluster.cosmos.azure.com connection string returns one entry per physical shard instead of a single entry. If the cluster uses cross-region replication, the global read-write and global read-only SRV records also list every node of the cluster they point to.

Because the SRV record returns multiple host and port pairs, MongoDB drivers that use a mongodb+srv:// connection string treat each node as a separate server. The driver opens a connection pool to each node and distributes operations across them. Any node that receives a request plans it and routes it to the physical shards that own the data, so every node returns the same results.

Commands that change cluster metadata, such as creating or dropping a collection or an index, are coordinated across the cluster automatically. You can issue them through any node.

You don't need to change your connection string or application code to use query from any node. Applications that already connect with the cluster's mongodb+srv:// connection string start using all nodes after the driver refreshes its view of the SRV record.

The following table compares the two modes.

Behavior Query from any node disabled (default) Query from any node enabled
Nodes that accept client connections One entry node Every physical shard
SRV records for the cluster host name One One per physical shard
Ports on the cluster endpoint 10260 10260 through 10260 + (number of physical shards − 1)
Connection strings (cluster and global) mongodb+srv:// Unchanged
Data distribution and shard keys Unchanged Unchanged

Prerequisites

  • An Azure DocumentDB cluster with two or more physical shards. On a single-shard cluster, there's only one node, so enabling the feature has no effect. Clusters on burstable compute and free tier clusters support only one physical shard.
  • Clients that connect with a mongodb+srv:// connection string, either the cluster connection string or a global connection string.
  • Network rules on the client side that allow outbound TCP traffic to the cluster host name on every node port, from 10260 through 10260 + (number of physical shards − 1). For example, a cluster with three physical shards uses ports 10260, 10261, and 10262.

Enable or disable query from any node

Query from any node is an opt-in cluster setting. You can turn it on or off at any time after the cluster is created. The change is applied online and doesn't require a restart of your application.

In the Azure portal, the setting appears on the cluster's Features page. In Azure CLI and the REST API, you turn it on by adding the EnableMultiServerRouting value to the cluster's opt-in feature list. That list is exposed as the previewFeatures property in the REST API and as the --preview-features parameter in Azure CLI. The property name reflects the API surface, not the support level of the values it holds.

Important

The previewFeatures property holds the complete list of opt-in features for the cluster. When you update it through Azure CLI or the REST API, include every value that's already set on the cluster in addition to EnableMultiServerRouting. Any value that you omit from the list is treated as a request to remove it, and some values can't be removed after the cluster is created. The Azure portal preserves the existing values for you.

To check which opt-in features are currently set on a cluster, run:

az documentdb mongocluster show \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --query "properties.previewFeatures"

  1. In the Azure portal, open your Azure DocumentDB cluster.

  2. On the cluster sidebar, under Settings, select Features.

  3. Select Query from any node.

  4. In the Query from any node panel, select Enable to turn the feature on, or Disable to turn it off.

You can also include EnableMultiServerRouting in the previewFeatures list when you create a new multishard cluster with Azure CLI or the REST API.

Verify that query from any node is enabled

After the update operation finishes, query the SRV record for the cluster. When query from any node is enabled, the response contains one entry for each physical shard. Each entry uses the same target host name with a different port.

nslookup -q=SRV _mongodb._tcp.<cluster-name>.mongocluster.cosmos.azure.com

For a cluster with three physical shards, the output is similar to the following example:

_mongodb._tcp.<cluster-name>.mongocluster.cosmos.azure.com    service = 0 0 10260 <host-name>.mongocluster.cosmos.azure.com.
_mongodb._tcp.<cluster-name>.mongocluster.cosmos.azure.com    service = 0 0 10261 <host-name>.mongocluster.cosmos.azure.com.
_mongodb._tcp.<cluster-name>.mongocluster.cosmos.azure.com    service = 0 0 10262 <host-name>.mongocluster.cosmos.azure.com.

If the response contains a single entry on port 10260, query from any node is disabled or the update operation hasn't finished yet. DNS resolvers and drivers can cache SRV records, so allow a few minutes for clients to pick up the change.

Plan your client configuration

  • Use the SRV connection string. Drivers discover the per-node ports only through the SRV record. A mongodb:// connection string that lists a single host and port connects to only one node.
  • Size connection pools per node. MongoDB drivers keep a separate connection pool for each server they discover. With query from any node enabled, the maximum number of connections that a client opens is roughly maxPoolSize multiplied by the number of physical shards. Adjust maxPoolSize if you need to keep the total number of connections within a budget.
  • Open firewall ports for every node. If outbound traffic from your application environment is restricted, allow the full port range for the cluster. When you add a physical shard, the new node uses the next port in the sequence.
  • Expect even load distribution only with even data distribution. Query from any node spreads connection handling and query planning across nodes. The physical shard that owns the requested data still serves the read or write, so a skewed shard key can still create a hot shard.

Interaction with other features

Feature Behavior with query from any node
In-region high availability Supported. Client connections go to the primary physical shards. Standby shards don't serve client traffic.
Cross-region and same-region replicas A replica cluster inherits the setting from its source cluster when it's created. Global read-write and global read-only connection strings list every node of the cluster they point to, including after a replica promotion.
Point-in-time restore A restored cluster inherits the setting from the source cluster.

Limitations

The following limitations currently apply:

  • Query from any node requires a multishard cluster. It has no effect on a single-shard cluster.
  • Reads aren't served from high availability standby shards.

Related content

  • Last updated on