Review Atlas Search Index Syntax

On this page

Limitation

Syntax
Options

Atlas Search can index data in different ways. When you define an Atlas Search index, you can specify a particular analyzer or multiple analyzers to index certain fields. To learn more, see Process Data with Analyzers. You can also index certain fields and omit others, or you can dynamically index all the fields in a collection. To learn more, see Define Field Mappings. You can define Atlas Search indexes through the Atlas User Interface, Atlas Search API, and Atlas CLI.

This page describes the JSON syntax and fields for an Atlas Search index.

Important

If you use the $out aggregation stage to modify a collection with an Atlas Search index, you must delete and re-create the search index. If possible, consider using $merge instead of $out.

Limitation

Atlas Search doesn't index numeric, date, or boolean values if they are part of an array or if they are inside of a document in an array.
Atlas Search doesn't support indexing array of string values for autocompletion.

Syntax

1 { 
2   "name": "<index-name>", 
3   "analyzer": "<analyzer-for-index>", 
4   "searchAnalyzer": "<analyzer-for-query>", 
5   "mappings": { 
6     "dynamic": <boolean>, 
7     "fields": { <field-definition> } 
8   }, 
9   "analyzers": [ <custom-analyzer> ],
10   "storedSource": <boolean> | {
11     <stored-source-definition>
12   },
13   "synonyms": [
14     {
15       "name": "<synonym-mapping-name>",
16       "source": {
17         "collection": "<source-collection-name>"
18       },
19       "analyzer": "<synonym-mapping-analyzer>"
20     }
21   ] 
22 }
23

Options

Field	Type	Necessity	Description
`analyzer`	string	Optional	Specifies the analyzer to apply to string fields when indexing. If you set this only at the top and do not specify an analyzer for the fields in the index definition, Atlas Search applies this analyzer to all the fields. To use a different analyzer for each field, you must specify a different analyzer for the field. If omitted, defaults to Standard Analyzer.
`analyzers`	array of Custom Analyzers	Optional	Specifies the Custom Analyzers to use in this index.
`mappings`	Document Field Definition	Required	Specifies how to index fields at different paths for this index.
`mappings.dynamic`	boolean	Optional	Enables or disables dynamic mapping of fields for this index. If set to `true`, Atlas Search recursively indexes all fields and embedded documents in the `document` except: Fields of certain data types. To learn more, see BSON Data Types. Any fields explicitly excluded by the `mappings.fields` parameter. If set to `false`, you must specify individual fields to index using `mappings.fields`. If omitted, defaults to `false`. Important Atlas indexes all fields in a `dynamic` `document` using the default settings for the detected data type. All nested documents under the dynamic `document` are treated as `dynamic`, unless explicitly overridden. To learn more, see index configuration example.
`mappings.fields`	document	Conditional	Required only if dynamic mapping is disabled. Specifies the fields that you would like to index. To learn more, see Define Field Mappings.
`name`	string	Optional	Specifies a name for the index. In each namespace, names of all indexes in the namespace must be unique. If omitted, defaults to `default`. Note If you name your index `default`, you don't need to specify an `index` parameter when using the $search pipeline stage. Otherwise, you must specify the index name using the `index` parameter.
`searchAnalyzer`	string	Optional	Specifies the analyzer to apply to query text before searching with it. If omitted, defaults to Standard Analyzer.
`storedSource`	boolean or Stored Source Definition	Optional	Note The Atlas Search index storedSource option and `$search` returnStoredSource option are in preview, but can be used in production applications. If there are any syntax or behavior changes between the preview stage and general availability (GA), we will proactively communicate before introducing any breaking changes. The MongoDB Cloud Support team will help troubleshoot any issues related to using this feature as part of your contract. Specifies fields in the documents to store for query-time look-ups using the returnedStoredSource option. You can store fields of all BSON Data Types on Atlas Search. Value can be one of the following: `true`, to store all fields `false`, to not store any fields Object that specifies the fields to `include` or `exclude` from storage If omitted, defaults to `false`. To learn more about the syntax and fields, see Define Stored Source Fields in Your Atlas Search Index. Note `storedSource` is only available on Atlas clusters running one of the following versions: MongoDB 4.4.12+ MongoDB 5.0.6+
`synonyms`	array of Synonym Mapping Definition	Optional	Synonym mappings to use in your index. To learn more, see Define Synonym Mappings in Your Atlas Search Index.

← Define Synonym Mappings in Your Atlas Search Index View an Atlas Search Index →

1	{
2	"name": "<index-name>",
3	"analyzer": "<analyzer-for-index>",
4	"searchAnalyzer": "<analyzer-for-query>",
5	"mappings": {
6	"dynamic": <boolean>,
7	"fields": { <field-definition> }
8	},
9	"analyzers": [ <custom-analyzer> ],
10	"storedSource": <boolean> \| {
11	<stored-source-definition>
12	},
13	"synonyms": [
14	{
15	"name": "<synonym-mapping-name>",
16	"source": {
17	"collection": "<source-collection-name>"
18	},
19	"analyzer": "<synonym-mapping-analyzer>"
20	}
21	]
22	}
23