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

# Query Reference

## Pipeline Stages

MongoDB Search queries take the form of an [aggregation pipeline stage](https://www.mongodb.com/docs/manual/aggregation.md#std-label-aggregation). MongoDB Search provides [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) and [`$searchMeta`](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta) stages, both of which must be the first stage in any query pipeline, including the [`$lookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup.md#mongodb-pipeline-pipe.-lookup) and [`$unionWith`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unionWith.md#mongodb-pipeline-pipe.-unionWith) sub-pipelines. These stages can be used in conjunction with other [aggregation pipeline stages](https://www.mongodb.com/docs/manual/aggregation.md#std-label-aggregation) 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`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) | Return the search results of a full-text search. |
| [`$searchMeta`](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta) | Return metadata about your search results. |

## Operators and Collectors

MongoDB Search also provides query [operators](https://www.mongodb.com/docs/search/query/operators-collectors/overview.md#std-label-operators-ref) and [collectors](https://www.mongodb.com/docs/search/query/operators-collectors/overview.md#std-label-collectors-ref) that you can use inside the [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) and [`$searchMeta`](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta) aggregation pipeline stages. The MongoDB Search operators allow you to locate and retrieve relevant data from the collection on your cluster. The collector returns a document representing the search metadata results.

You can use MongoDB 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 MongoDB Search [compound](https://www.mongodb.com/docs/search/query/operators-collectors/compound.md#std-label-compound-ref) operator allows you to combine multiple operators inside your [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-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 MongoDB Search. You can use the [compound](https://www.mongodb.com/docs/search/query/operators-collectors/compound.md#std-label-compound-ref) operator to also match or filter documents in the [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) stage itself. Running [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) after [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) is less performant than running [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) with the [compound](https://www.mongodb.com/docs/search/query/operators-collectors/compound.md#std-label-compound-ref) operator.

To learn more about operators and collectors, see [Operators and Collectors.](https://www.mongodb.com/docs/search/query/operators-collectors/overview.md#std-label-operators-ref)

## Query Processing

`mongod` and `mongot` on the Same Node

When you run a query, MongoDB Search uses the [configured read preference](https://www.mongodb.com/docs/atlas/reference/replica-set-tags.md#std-label-replica-set-tags) 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 MongoDB Search queries that target a particular  shard. `mongos` directs the queries to all shards, making these *scatter gather* queries. If you use [zones](https://www.mongodb.com/docs/manual/core/zone-sharding.md#std-label-zone-sharding) to distribute a sharded collection over a subset of the shards in the cluster, MongoDB Search routes the query to the zone that contains the shards for the collection that you are querying and runs your [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) queries on just the shards where the collection is located.

MongoDB 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`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) [concurrent](https://www.mongodb.com/docs/search/query/concurrent-query.md#std-label-concurrent-ref) option in your query, MongoDB Search enables intra-query parallelism. To learn more, see [Parallelize Query Execution Across Segments.](https://www.mongodb.com/docs/search/query/concurrent-query.md#std-label-concurrent-ref)

`mongod` and `mongot` on Different Nodes

When you run a query, the query first goes to the `mongod` based on the [configured read preference](https://www.mongodb.com/docs/atlas/reference/replica-set-tags.md#std-label-replica-set-tags). By default, 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. Alternatively, if you set the `searchNodePreference` parameter for your [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) stage, MongoDB Search runs your query against the same search node each time.

The MongoDB 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`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) [concurrent](https://www.mongodb.com/docs/search/query/concurrent-query.md#std-label-concurrent-ref) option in your query, MongoDB Search enables intra-query parallelism. To learn more, see [Parallelize Query Execution Across Segments.](https://www.mongodb.com/docs/search/query/concurrent-query.md#std-label-concurrent-ref)

## Scoring

MongoDB Search associates a relevance-based score with every document in the result set. The relevance-based scoring allows MongoDB Search to return documents in the order from the highest score to the lowest. MongoDB 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. MongoDB 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.](https://www.mongodb.com/docs/search/query/score/overview.md#std-label-scoring-ref)

**See also: Learn by Watching**

Watch this video for an overview of searching and tracking your queries with MongoDB Search. In this video, you can learn more about MongoDB Search [operators](https://www.mongodb.com/docs/search/query/operators-collectors/overview.md#std-label-operators-ref) and how MongoDB Search [scores](https://www.mongodb.com/docs/search/query/score/overview.md#std-label-scoring-ref) documents in the results.

*Duration: 15 Minutes*

## Supported Clients

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

- [Search Tester](https://www.mongodb.com/docs/search/about/searching.md#std-label-atlas-search-queries)

- [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh)

- [Compass](https://www.mongodb.com/docs/compass/current/)

- [MongoDB drivers](https://www.mongodb.com/docs/drivers/)

## Troubleshoot Queries

### Empty Result Set

`mongot` doesn't return any errors, but returns an empty result set if your [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) query:

- References an index that doesn't exist. If you don't specify an index by name in the query, MongoDB 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, MongoDB 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, MongoDB 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](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-static-dynamic-mappings) in your index definition for the collection to ensure that all the [dynamically indexable fields](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-bson-data-chart) in the collection are automatically indexed. To learn more, see [dynamic mapping.](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-static-dynamic-mappings)

- Uses the `text` operator on a field path which is not indexed as a `string` type. If a field is indexed as a MongoDB Search field type other than `string`, such as `stringFacet` or `autocomplete`, MongoDB Search doesn't return an error and returns an empty result set. You *must* index the fields with `string` BSON (Binary Javascript Object Notation) data type values as [string](https://www.mongodb.com/docs/search/indexes/field-types/string-type.md#std-label-bson-data-types-string) type to query the fields using the [text](https://www.mongodb.com/docs/search/query/operators-collectors/text.md#std-label-text-ref) operator.

### `PlanExecutor` Error

`mongot` returns a `PlanExecutor` error if your [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) query:

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

  ```shell
  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` (MongoDB Search Operator)](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-ref) queries against `string`, `number`, or `date` fields, create an index for the fields using the corresponding MongoDB Search field type such as `stringFacet`, `number`, and `date` respectively. To learn more, see [Supported and Unsupported Data Types.](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-bson-data-chart)