The MongoDB Search process (mongot) runs queries in a fixed execution pool. When queries arrive faster than the process can run them, Atlas holds the excess queries in an admission control queue rather than running them all at once. Search Load Shedding governs this queue. It protects the search process from memory exhaustion and from the latency collapse that occurs when a process accepts more concurrent work than it can complete.
Search Load Shedding applies to both $search and $vectorSearch queries. It's available on clusters running MongoDB 8.0, 8.3, and 9.0 or later, and Atlas enables it by default on clusters running MongoDB 9.0 or later.
When the search process reaches its execution capacity, Atlas queues incoming queries. Queued queries run when capacity frees up, so they complete successfully but with higher latency than usual. Latency remains elevated until the arrival rate drops below the rate at which the process can admit work.
At any time, a query is running in the execution pool, waiting in the admission control queue, or rejected. Only a full queue causes rejection.
Search Load Shedding doesn't change how many queries the search process runs concurrently. It changes only whether the admission control queue has a capacity limit:
With an unbounded queue, Atlas queues every excess query. Queries always run, but sustained overload produces increasing latency.
With a bounded queue, Atlas still queues excess queries, but only up to a capacity limit. When the queue is full, Atlas rejects further queries immediately rather than adding latency for every client.
Atlas sets the size of the execution pool and the capacity of the bounded queue internally, and can change these limits at any time.
By the time Atlas begins rejecting queries, the overload has already raised latency for the queries that Atlas admits. Rejection sheds the excess load, which prevents that latency from degrading further. It also keeps the search process responsive instead of allowing it to fail entirely.
Rejected Query Errors
When Atlas rejects a query because the admission control queue is full, the query fails with the following error:
字段 | 值 |
|---|---|
错误代码 |
|
Code name |
|
Error label |
|
Every version that supports Search Load Shedding returns this same error, so your application can rely on a single error contract.
重要
Rejected Queries Aren't Retryable
The 489 error doesn't carry the RetryableError label. Neither the MongoDB drivers nor mongod retry a rejected query automatically. Your application must decide how to respond.
A rejection means that the search process is already saturated. Retrying immediately adds load to a process that can't absorb it, which extends the overload and increases the number of rejections. To respond to a 489 error, apply the following practices:
Catch the
SystemOverloadedErrorlabel rather than matching on the error message text.Wait before you send the query again. Use exponential backoff with jitter so that concurrent clients don't retry in step with each other.
Cap the number of attempts. Surface a degraded result or an error to the end user rather than retrying indefinitely.
Reduce the rate at which your application sends search queries while rejections persist. Lowering client concurrency shortens the overload.
Treat sustained rejections as a capacity signal rather than a transient fault, and scale or optimize your search workload.
Monitor and Reduce Search Overload
Atlas reports queuing before it results in rejections, which gives you time to act. Use the following signals:
The Search Process Throttling metric reports the rate at which the search process signaled that it exceeded its queue threshold. A sustained non-zero value means that work arrives faster than the process can admit it. To view this metric, see Review MongoDB Search Metrics.
The MongoDB Search: Search Process is Overloaded alert fires when the condition persists for 5 minutes. To resolve this alert, see Fix MongoDB Search Issues.
To reduce the load that reaches the search process, take the following actions:
Deploy Search Nodes to isolate the search workload, or upgrade to a Search Node tier with more vCPUs.
Spread queries out over time instead of sending them in bursts.
Optimize your queries. Add filters, reduce leading wildcards and deeply nested clauses, and return only the fields that you need.
To learn more about optimizing queries, see MongoDB Search Query Performance.
Configure Search Load Shedding
Configure Search Load Shedding per cluster. The setting accepts the following states:
州 | API Value | 说明 |
|---|---|---|
Atlas 托管 | No override | Atlas selects the state based on the MongoDB version that your cluster runs. Atlas resolves this state to Off on MongoDB 8.0 and 8.3, and to On on MongoDB 9.0 or later. |
On（开启） |
| The admission control queue is bounded. Atlas queues excess queries up to a capacity limit, then rejects further queries with a |
关闭 |
| The admission control queue is unbounded. Atlas queues every excess query and never rejects a query. |
Use the Atlas UI or the Atlas Administration API to change the state.