Query Reference

Pipeline Stages

Atlas Search queries take the form of an aggregation pipeline stage. Atlas Search provides $search and $searchMeta stages, both of which must be the first stage in any query pipeline, including the $lookup and $unionWith sub-pipelines. These stages can be used in conjunction with other aggregation pipeline stages in your query pipeline.

Based on the pipeline stage that you choose, your query returns either the search results of a full-text search or metadata about your search results:

Aggregation Pipeline Stage	Purpose
`$search`	Return the search results of a full-text search.
`$searchMeta`	Return metadata about your search results.

Operators and Collectors

Atlas Search also provides query operators and collectors that you can use inside the $search and $searchMeta aggregation pipeline stages. The Atlas Search operators allow you to locate and retrieve relevant data from the collection on your Atlas cluster. The collector returns a document representing the search metadata results.

You can use Atlas Search operators to query terms, phrases, geographic shapes and points, numeric values, similar documents, synonymous terms, and more.

You can also search using regex and wildcard expressions. The Atlas Search compound operator allows you to combine multiple operators inside your $search stage to perform a complex search and filter of data based on what must, must not, or should be present in the documents returned by Atlas Search. You can use the compound operator to also match or filter documents in the $search stage itself. Running $match after $search is less performant than running $search with the compound operator.

To learn more about operators and collectors, see Operators and Collectors.

Query Processing

mongod and mongot on the Same Node

When you run a query, Atlas Search uses the configured read preference to identify the node on which to run the query. The query first goes to the MongoDB process, which is mongod for a replica set cluster or mongos for a sharded cluster.

For a replica set cluster, the MongoDB process routes the query to the mongot on the same node. For sharded clusters, your cluster data is partitioned across mongod instances and each mongot knows about the data on the mongod on the same node only. Therefore, you can't run Atlas Search queries that target a particular shard. mongos directs the queries to all shards, making these scatter gather queries. If you use zones to distribute a sharded collection over a subset of the shards in the cluster, Atlas Search routes the query to the zone that contains the shards for the collection that you are querying and runs your $search queries on just the shards where the collection is located.

Atlas Search performs the search and scoring and returns the document IDs and other search metadata for the matching results to mongod. The mongod then performs a full document lookup implicitly for the matching results and returns the results to the client. If you use the $search concurrent option in your query, Atlas Search enables intra-query parallelism. To learn more, see Parallelize Query Execution Across Segments.

mongod and mongot on Different Nodes

When you run a query, the query first goes to the mongod based on the configured read preference. The mongod process routes the search query through a load balancer on the same node, which distributes the requests across all of the mongot processes.

The Atlas Search mongot process performs the search and scoring and returns the document IDs and metadata for the matching results to mongod. The mongod then performs a full document lookup for the matching results and returns the results to the client. If you use the $search concurrent option in your query, Atlas Search enables intra-query parallelism. To learn more, see Parallelize Query Execution Across Segments.

Scoring

Atlas Search associates a relevance-based score with every document in the result set. The relevance-based scoring allows Atlas Search to return documents in the order from the highest score to the lowest. Atlas Search scores documents higher if the query term appears frequently in a document and lower if the query term appears across many documents in the collection. Atlas Search also supports customizing the relevance-based default score by boosting, decaying, or other modifying options. To learn more about customizing the resulting scores, see Score the Documents in the Results.

Supported Clients

You can create and run Atlas Search queries using the following clients:

Troubleshoot Queries

Empty Result Set

mongot doesn't return any errors, but returns an empty result set if your $search query:

References an index that doesn't exist. If you don't specify an index by name in the query, Atlas Search defaults to an index named default. If you don't have an index named default or if the index that you specified doesn't exist, Atlas Search doesn't return an error and returns an empty result set. You can specify a valid index by its name using the index option.
Specifies a non-indexed field. If you run a query against a field that isn't indexed, Atlas Search doesn't return an error and returns an empty result set. You must specify only indexed fields as values for the path parameter. You can enable dynamic mapping in your index definition for the collection to ensure that all the dynamically indexable fields in the collection are automatically indexed. To learn more, see dynamic mapping.
Uses the text operator on a field path which is not indexed as a string type. If a field is indexed as an Atlas Search field type other than string, such as stringFacet or autocomplete, Atlas Search doesn't return an error and returns an empty result set. You must index the fields with string BSON data type values as string type to query the fields using the text operator.

`PlanExecutor` Error

mongot returns a PlanExecutor error if your $search query:

Specifies a field that is indexed as an incorrect data type. In this case, if you run a query, Atlas Search returns an error message identifying the field that was indexed incorrectly and its correct data type. For example:

PlanExecutor error during aggregation :: caused by :: Cannot facet on field "genres" because
it was not indexed as a "stringFacet" field.

For example, to run facet queries against string, number, or date fields, create an index for the fields using the corresponding Atlas Search field type such as stringFacet, number, and date respectively. To learn more, see Supported and Unsupported Data Types.

Back

Index Partitions

Choose the Aggregation Pipeline Stage