Queries and Indexes

On this page

Plan Your Search Experience
What are your users searching for?
Which fields in your documents contain likely search terms?
How closely should users' search terms match your data?
Do you need advanced text analysis?
How do you want to present search results?
How can you optimize search performance?
Define Your Index
Choose which fields to index.
(Optional) Apply text analysis rules.
(Optional) Add options to optimize query performance.
Define Your Query
Choose your initial Atlas Search pipeline stage.
Apply operators to define your search criteria.
(Optional) Apply options or collectors to return metadata.
(Optional) Add search options to your $search stage to retrieve additional information about your Atlas Search query.
(Optional) Add $search options to define result ranking.
(Optional) Add $search options to optimize query performance.
Learn More

The relationship between search queries and search indexes dictates how efficiently and effectively you can find data within your MongoDB collections using Atlas Search.

Atlas Search queries specify the criteria for finding documents within a database. Atlas Search queries take the form of an aggregation pipeline that begins with the $search or $searchMeta pipeline stage. You can use operators, collectors, and search options inside the pipeline stages to implement complex search functionality like full-text search, relevance-based ranking, faceted search, filtering, and sorting.

Before you can run an Atlas Search query, you must create an Atlas Search index on the fields that you want to search. Search indexes are data structures that are optimized to quickly retrieve documents that meet the search criteria of your query. When you define a search index, you specify which fields to index and how these fields should be tokenized.

Effective search queries depend on properly defined search indexes. The fields you intend to search must be indexed, and your index configuration determines whether your search supports sorting, faceting, autocomplete, and other search functionality. You can iterate on both query and index design to balance search accuracy with performance.

This page describes how to plan your Atlas Search search experience and define an Atlas Search index and query to fit your search requirements.

Plan Your Search Experience

When planning your Atlas Search implementation, start by defining the search experience you want to deliver:

Clearly identify what types of searches your application needs to perform. Are you building a search feature for a blog website that needs full-text search and autocomplete for article titles, or an e-commerce site that requires faceted search and filtering by product categories?
Determine how users will interact with your application. Prioritize features that will enhance the user experience, such as quick response times or accurate autocomplete suggestions.

Then, consider the following questions to help determine the structure of your Atlas Search indexes and queries based on those user needs:

What are your users searching for?

Choose between returning document content or search metadata.

Consider whether your application users want to return the content of documents or metadata about your documents:

If users want document content, use the $search aggregation stage to return documents that match their search criteria.
If users want metadata about their search results, use the $searchMeta stage to return customizable counts of matching documents and facets.

Which fields in your documents contain likely search terms?

Determine which fields to index based on which fields contain the data your users want to find.

Identify the specific fields within your collections that users are likely to search so that you know which fields to index. Each Atlas Search query searches a single Atlas Search index, which contains terms that are extracted from one or more specified fields within a collection. When planning your Atlas Search queries, decide whether to index only key fields or every field in your specified collection by enabling static or dynamic mapping. You can query across multiple fields by specifying the query path as an array of fields, or by using the queryString operator.

How closely should users' search terms match your data?

Choose search operators based on whether your users' common search terms are exact, similar, or partial matches for your data.

Your users' common search terms may be exact, similar , or partial matches for the data in your Atlas cluster. For example, users of a movie review application may want to filter for movies from an exact year, or see movie recommendations that are similar to their favorite film.

Determine the type of matches your users are searching for to inform which operators to use in your Atlas Search queries:

For exact matches, use operators like equals or in to match documents that contain terms that are identical to the specified query value. You can also use the text operator to match documents that contain any or all of the strings in the query value.
For similar matches, use operators like near, moreLikeThis, or phrase to match documents that contain numeric values, documents, or string orderings that are similar to the specified search terms. You can also use the range operator to match documents that contain a value within a specified range of values.
For partial matches, such as search-as-you-type queries, use operators like autocomplete, regex, or wildcard to implement search-as-you-type functionality or match terms using regular expressions.
Use the compound operator to blend multiple matching behaviors in a single query.

Do you need advanced text analysis?

Use text analysis tools if your application requires text normalization, multi-language support, or more.

For applications that require text normalization, multi-language support, stemming, or more, leverage Atlas Search text analysis tools:

Choose a built-in analyzer in your index definition to match the language and nature of your text data. Analyzers break text into terms or tokens and can adjust text to remove punctuation and capitalization, convert words to their root form, and more.
Configure custom analyzers if your application has specific requirements like handling domain-specific jargon or parsing formatted text like email addresses or dash-separated IDs. Custom analyzers enable you to filter text by character, define the number of characters to include in each token chunk, or enable stemming or redaction.
Define synonyms to improve search accuracy for terms with the same or similar meanings.

How do you want to present search results?

Use search options to implement filtering, sorting, or relevancy demands for your search results.

You can adjust the presentation of search results based on your users' filtering, sorting, or relevancy demands:

Use the score query option to modify the relevance score of documents and affect the order in which users view results. Atlas Search queries associate a relevance-based score with every document in the result set, and returns documents in order from the highest to the lowest score.
Set the sort query option for indexed fields that users are likely to sort in ascending or descending order, such as dates or numeric fields.
Use the searchBefore or searchAfter query options to display results as a set of pages that users can navigate sequentially or skip through.
Use the facet collector to allow users to filter results by categories or other dimensions. This can significantly improve the relevance of search results, offering users a more guided search experience.

How can you optimize search performance?

Adjust your index and query configuration to optimize your search performance.

Atlas Search query performance is affected by your index configuration and the complexity of your queries. Focus on indexing fields that are critical to your application's search functionality and aim for a logical balance between query complexity and speed.

To further optimize performance, consider the following query options:

Use the concurrent query option to set the number of concurrent search requests that are executed when evaluating a query. This option is useful for complex queries or large datasets.
Use the returnStoredSource query option in combination with the storedSource index option to determine whether to return original source documents, stored as part of the index, alongside the search results. This option is useful for applications where you display summaries or highlights based on search criteria.
Use the numPartitions index option to partition your index, distributing index objects between sub-indexes in an optimal way.

For more recommendations on how to optimize your query performance, see Atlas Search Query Performance.

Define Your Index

Before you can search your data using Atlas Search, you must create one or more Atlas Search indexes to be used during your Atlas Search query. This section demonstrates how to apply your query preferences to the JSON configuration syntax of an Atlas Search index.

To use the JSON syntax in this section in your index definition, replace the placeholders with valid values and ensure that your full index definition contains the necessary options.

To learn how to add your Atlas Search index to your Atlas cluster, see the Atlas Search Quick Start.

Choose which fields to index.

If you know which fields you want to query in your collection, enable static mappings and specify the fields in your Atlas Search index definition. Otherwise, you can enable dynamic mappings to automatically index all the fields of supported types.

To learn more, see Static and Dynamic Mappings.

Note

If your collection contains documents that are 16MB or larger, Atlas Search fails to index your data. This issue can also occur when update operations on large documents cause the change stream event to exceed the 16MB BSON limit. To avoid this, consider the following best practices:

Structure your documents to minimize the size of sub-documents or arrays.
Avoid operations that update or replace large fields, sub-documents, or arrays.

To learn more, see Change Streams Production Recommendations and Reduce the Size of Large Documents.

1 {
2   "mappings": {
3     "dynamic": true,
4     "fields": {  // Optional, use this to configure individual fields
5       "<field-name>": {
6         "type": "<field-type>",
7         ...
8       },
9       ...
10     }
11   }
12 }

1 {
2   "mappings": { 
3     "dynamic": false, // Optional, if omitted defaults to "false"
4     "fields": { 
5       "<field-name>": {
6         "type": "<field-type>",
7         ...
8       },
9       ...  
10     }
11   }
12 }

(Optional) Apply text analysis rules.

If you have special language or parsing requirements, you can apply the following options to your index definition:

Specify which built-in analyzers to apply to the string fields you are indexing in the analyzer, searchAnalyzer, or fields.<field-name>.analyzer fields.

1 {
2   "analyzer": "<index-analyzer-name>", // top-level index analyzer, used if no analyzer is set in the field mappings
3   "searchAnalyzer": "<search-analyzer-name>", // query text analyzer, typically the same as the index analyzer
4   "mappings": {
5     "dynamic": <boolean>,
6     "fields":{
7       "<field-name>": [
8         {
9           "type": "string",
10           "analyzer": "<field-analyzer-name>" // field-specific index analyzer
11         }
12       ]
13     }
14   }
15 }

Define custom analyzers for your Atlas Search index in the analyzers field.

1 {
2   "analyzers": [
3     {
4       "name": "<custom-analyzer-name>",
5       "tokenizer": {
6         "type": "<tokenizer-type>"
7       }
8     },
9     ...
10   ]
11 }

Define synonyms for terms that have the same or similar meanings in the synonyms field.

1 { 
2   "synonyms": [
3     {
4       "name": "<synonym-mapping-name>",
5       "source": {
6         "collection": "<source-collection-name>"
7       },
8       "analyzer": "<synonym-mapping-analyzer>"
9     }
10   ] 
11 }

(Optional) Add options to optimize query performance.

If you want to optimize your query performance on a large dataset, you can add the following options to your index definition to limit the amount of data that your Atlas Search query must traverse:

Use the numPartitions option to configure partitions for your index. When you partition your index, Atlas Search automatically distributes the index objects between sub-indexes in an optimal way.

1 {
2   "numPartitions": <integer>,
3 }

Use the storedSource option to specify fields in the source document that Atlas Search must store.

1 {
2   "storedSource": true | false | {
3     "include" | "exclude": [
4       "<field-name>",
5       ...
6     ]
7   }
8 }

Define Your Query

After you create an Atlas Search index for all the fields that you want to search in your collection, you can run an Atlas Search query. This section demonstrates how to apply your goals for your application's search experience to the JSON syntax of an Atlas Search query.

To use the JSON syntax in this section in your Atlas Search query aggregation pipeline, replace the placeholders with valid values and ensure that your full query pipeline contains the required $search fields or $searchMeta fields.

To learn how to run a Search query, see the Atlas Search Quick Start.

Choose your initial Atlas Search pipeline stage.

The first stage of your Atlas Search query aggregation pipeline must be either the $search or $searchMeta stage, depending on whether you're searching for documents or metadata:

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

Apply operators to define your search criteria.

To define your search criteria, you must apply one or more operators or collectors to your $search or $searchMeta pipeline stage.

Atlas Search operators allow you to locate and retrieve relevant data from your Atlas cluster according to content, format, or data tyoe. To learn which operators support searches for each field type, see the table in the operators reference section. You must specify one or more indexed search fields in the operator's query path parameter:

1 {
2   $search: {
3     "<operator-name>"|"<collector-name>": {
4       <operator-specification>|<collector-specification>
5     }
6   }
7 }

[
  {
    _id: <result-document-id>,
    ...
  },
  {
    _id: <result-document-id>,
    ...
  },
  ...
]

1 {
2   $searchMeta: {
3     "<operator-name>"|"<collector-name>": {
4       <operator-specification>|<collector-specification>
5     }
6   }
7 }

[
  {
    count: {
      total: <results-count>
    }
  }
]

Tip

You can combine multiple operators into one operation using the compound operator. You can also use the compound operator's filter clause to filter for query output that matches a given clause.

(Optional) Apply options or collectors to return metadata.

If you want to retrieve metadata from your Atlas Search query, you can apply one of the following configurations to choose between the count or facet type of metadata results document:

To return the total or lower-bounded count of your search results, set the count option in your aggregation stage.

The $searchMeta stage returns the count metadata results, while the $search stage stores the metadata results in the $$SEARCH_META aggregation variable and returns only the search results. For an example of how to retrieve the count metadata results from the $$SEARCH_META variable, see Count Results.

1 {
2   "$search" | "$searchMeta": {
3     "<operator-name>": {
4       <operator-specifications>
5     },
6     "count": {
7       "type": "lowerBound" | "total",
8       "threshold": <number-of-documents> // Optional
9     }
10   }
11 }

To run a facet query, which groups results by values or ranges and returns the count for each of these groups, use the facet collector in your aggregation stage.

The $searchMeta stage returns facet metadata results, while the $search stage stores the metadata results in the $$SEARCH_META aggregation variable and returns only the search results. For an example of how to retrieve the facet metadata results from the $$SEARCH_META variable, see Facet Results.

1 {
2   "$search" | "$searchMeta": {
3     "facet": {
4       "facets": {
5         <facet-definitions>
6       }
7     }
8   }
9 }

(Optional) Add search options to your $search stage to retrieve additional information about your Atlas Search query.

You can retrieve additional information about your $search stage results using the following options:

Option	Use Case
highlight	Display your search terms in their original context as fields in your query result.
scoreDetail	Retrieve a detailed breakdown of the score for each document Atlas Search returns.
tracking	Track and provide analytics information for your query search terms.
explain	Retrieve analytics about which Lucene queries Atlas Search executed to satify your query, and how much time your query spends in the various stages of execution.

(Optional) Add $search options to define result ranking.

You can implement special ordering functionality for your $search results with the following options:

Option	Use Case
score	Modify the relevance score of the documents in the results to ensure Atlas Search returns relevant results.
sort	Sort your results by number, string, and date fields, or by score.
searchBefore/searchAfter	Set a reference point to stop or start your ordered results

(Optional) Add $search options to optimize query performance.

Optimize query performance using the following $search options:

Option	Use Case
returnStoredSource	Run your Atlas Search query more efficiently by only retrieving fields stored on `mongot` as specified in your Atlas Search index definition for a collection.
concurrent	Parallelize search across segments on dedicated search nodes.

Learn More

To learn how to build and run an Atlas Search index and Atlas Search query, see the Atlas Search Quick Start.

To learn more about the Atlas Search query configuration options mentioned in this tutorial, see the following reference pages:

To learn more about the Atlas Search index configuration options mentioned in this tutorial, see the following reference pages:

Back

How to Use Facets with Atlas Search

Manage Indexes

1	{
2	"mappings": {
3	"dynamic": true,
4	"fields": { // Optional, use this to configure individual fields
5	"<field-name>": {
6	"type": "<field-type>",
7	...
8	},
9	...
10	}
11	}
12	}

1	{
2	"mappings": {
3	"dynamic": false, // Optional, if omitted defaults to "false"
4	"fields": {
5	"<field-name>": {
6	"type": "<field-type>",
7	...
8	},
9	...
10	}
11	}
12	}

1	{
2	"analyzer": "<index-analyzer-name>", // top-level index analyzer, used if no analyzer is set in the field mappings
3	"searchAnalyzer": "<search-analyzer-name>", // query text analyzer, typically the same as the index analyzer
4	"mappings": {
5	"dynamic": <boolean>,
6	"fields":{
7	"<field-name>": [
8	{
9	"type": "string",
10	"analyzer": "<field-analyzer-name>" // field-specific index analyzer
11	}
12	]
13	}
14	}
15	}

1	{
2	"analyzers": [
3	{
4	"name": "<custom-analyzer-name>",
5	"tokenizer": {
6	"type": "<tokenizer-type>"
7	}
8	},
9	...
10	]
11	}

1	{
2	"synonyms": [
3	{
4	"name": "<synonym-mapping-name>",
5	"source": {
6	"collection": "<source-collection-name>"
7	},
8	"analyzer": "<synonym-mapping-analyzer>"
9	}
10	]
11	}

1	{
2	"storedSource": true \| false \| {
3	"include" \| "exclude": [
4	"<field-name>",
5	...
6	]
7	}
8	}

1	{
2	$search: {
3	"<operator-name>"\|"<collector-name>": {
4	<operator-specification>\|<collector-specification>
5	}
6	}
7	}

1	{
2	$searchMeta: {
3	"<operator-name>"\|"<collector-name>": {
4	<operator-specification>\|<collector-specification>
5	}
6	}
7	}

1	{
2	"$search" \| "$searchMeta": {
3	"<operator-name>": {
4	<operator-specifications>
5	},
6	"count": {
7	"type": "lowerBound" \| "total",
8	"threshold": <number-of-documents> // Optional
9	}
10	}
11	}

1	{
2	"$search" \| "$searchMeta": {
3	"facet": {
4	"facets": {
5	<facet-definitions>
6	}
7	}
8	}
9	}