Docs Home → Launch & Manage MongoDB → MongoDB Atlas

Define Field Mappings

On this page

Static and Dynamic Mappings

Static Mappings
Dynamic Mappings
Data Types
Limitations
Index Field as Multiple Data Types
Examples
Static Mapping Example
Combined Mapping Example

When you create an Atlas Search index, you can:

Specify the fields to index using static mappings.
Configure Atlas Search to automatically index all supported field types using dynamic mappings.

To use static mappings, you must explicitly include the fields in the collection that you want to index. In the type field, specify the data type of the field in the field definition. Alternatively, you can specify an array of field definitions for a field, one for each data type.

Syntax

1 {
2   "mappings": {
3     "dynamic": <boolean>,
4     "fields": {
5       "<field-name>": [
6         {
7           "type": "<field-type>",
8           ...
9         },
10         ...
11       ],
12       ...
13     }
14   }
15 }

Note

Unlike compound indexes, the order of fields in the Atlas Search index definition is not important. Fields can be defined in any order.

Static and Dynamic Mappings

You can use static and dynamic mappings to specify whether Atlas Search must automatically index all the dynamically indexable fields in your collection.

Static Mappings

Use static mappings to configure index options for fields that you don't want indexed dynamically, or to configure a single field independently from others in an index.

For static mappings, set mappings.dynamic to false and specify the fields to index using mappings.fields. Atlas Search indexes only the specified fields with specific options. If an indexed field contains polymorphic data, Atlas Search indexes only documents that correspond to the mappings specified in the index definition for that field and ignores documents that contain values that aren't the data type specified in the index definition for that field.

You can't use the dot notation to statically index nested fields. When defining the index for a nested field, you must define the mappings for each parent field of that nested field. For an example, see the Examples on this page, which demonstrates the index syntax for a field named city that is nested inside a field named address.

Dynamic Mappings

Use dynamic mappings if your schema changes regularly or is unknown, or when experimenting with Atlas Search. You can configure an entire index to use dynamic mappings, or specify individual fields, such as fields of type document, to be dynamically mapped. Before using dynamic mappings, see the table for Data Types.

For dynamic mappings, set mappings.dynamic to true. Atlas Search automatically indexes the fields of supported types in each document. For fields of type string, Atlas Search stores the fields on mongot.

Note

Dynamically mapped indexes occupy more disk space than statically mapped indexes and may be less performant.

Data Types

Atlas Search doesn't support the following BSON data types:

Decimal128
JavaScript code with scope
Max key
Min key
Regular Expression
Timestamp

The following table enumerates the supported BSON data types and the Atlas Search field types that you can use to index the BSON data types. The table also indicates whether the Atlas Search field type is automatically included in an Atlas Search index when you enable dynamic mappings and lists the operators and collectors that you can use to query the field value.

Note

When you dynamically index a field that has polymorphic data, Atlas Search automatically indexes the field as all the dynamically indexable field types that correspond to the data. If the field contains data of a type that Atlas Search doesn't index automatically, Atlas Search won't index that data.

BSON Type	Atlas Search Field Type	Dynamically Indexed	Operators and Collectors
Array	boolean date number objectId string token	✓	Operators that support the data type in the array.
Boolean	boolean	✓	equals in
Date	date	✓	equals in near range
Date	dateFacet		facet
Double	number	✓	equals in near range
Double	numberFacet		facet
Double	knnVector (Deprecated)		knnBeta
GeoJSON Object	geo		geoShape geoWithin near
32-bit integer	number	✓	in near range
32-bit integer	numberFacet		facet
64-bit integer	number	✓	equals in near range
64-bit integer	numberFacet		facet
Null	N/A	✓	equals
Object	document	✓	All Operators
Object	embeddedDocument (for array of objects)		embeddedDocument
ObjectId	objectId	✓	equals in
String	string	✓	moreLikeThis phrase queryString regex span text wildcard
String	stringFacet		facet
String	autocomplete		autocomplete
String	token		equals in range
UUID/BSON Binary Subtype 4	uuid	✓	equals in

Some limitations apply. To learn more, see How to Index the Elements of an Array.

For string type, the moreLikeThis and queryString operators don't support an array of strings.

Atlas Search doesn't include a field type for indexing null values because Atlas Search automatically indexes null values for both statically and dynamically indexed fields.

Note

You can store fields of all supported data types on Atlas Search using the storedSource option.

Limitations

Atlas Search doesn't support indexing more than two billion index objects, where each indexed document counts as a single object. If you plan to index fields that might exceed this limit, you must shard your cluster. For example, if you use the embeddedDocuments field type, Atlas Search might index objects over this limit.

You can't index fields that contain the dollar ($) sign at the start of the field name.

Index Field as Multiple Data Types

To index a field as multiple types, define the types in the field definition array for the field.

Example

The following example shows the field definition for indexing a field as multiple types.

1 {
2   ...
3   "mappings": {
4     "dynamic": <boolean>,
5     "fields": {
6       "<field-name>": [
7         {
8           "type": "<field-type>",
9           ...
10         },
11         {
12           "type": "<field-type>",
13           ...
14         },
15         ...
16       ],
17       ...
18     },
19     ...
20   }
21 }

Examples

Static Mapping Example

The following index definition example uses static mappings.

The default index analyzer is lucene.standard.
The default search analyzer is lucene.standard. You can change the search analyzer if you want the query term to be parsed differently than how it is stored in your Atlas Search index.
The index specifies static field mappings (dynamic: false), which means fields that are not explicitly mentioned are not indexed. So, the index definition includes:
- The address field, which is of type document. It has two embedded sub-fields, city and state.
  The city sub-field uses the lucene.simple analyzer by default for queries. It uses the ignoreAbove option to ignore any string of more than 255 bytes in length.
  The state sub-field uses the lucene.english analyzer by default for queries.
- The company field, which is of type string. It uses the lucene.whitespace analyzer by default for queries. It has a multi analyzer named mySecondaryAnalyzer which uses the lucene.french analyzer by default for queries.
  To learn more about multi analyzers, see Path Construction.
- The employees field, which is an array of strings. It uses the lucene.standard analyzer by default for queries. For indexing arrays, Atlas Search only requires the data type of the array elements. You don't have to specify that the data is contained in an array in the index definition.

{
  "analyzer": "lucene.standard",
  "searchAnalyzer": "lucene.standard",
  "mappings": {
    "dynamic": false,
    "fields": {
      "address": {
        "type": "document",
        "fields": {
          "city": {
            "type": "string",
            "analyzer": "lucene.simple",
            "ignoreAbove": 255
          },
          "state": {
            "type": "string",
            "analyzer": "lucene.english"
          }
        }
      },
      "company": {
        "type": "string",
        "analyzer": "lucene.whitespace",
        "multi": {
          "mySecondaryAnalyzer": {
            "type": "string",
            "analyzer": "lucene.french"
          }
        }
      },
      "employees": {
        "type": "string",
        "analyzer": "lucene.standard"
      }
    }
  }
}

Combined Mapping Example

The following index definition example uses both static and dynamic mappings.

The default index analyzer is lucene.standard.
The default search analyzer is lucene.standard. You can change the search analyzer if you want the query term to be parsed differently than how it is stored in your Atlas Search index.
The index specifies static field mappings (dynamic: false), which means fields that aren't explicitly mentioned aren't indexed. So, the index definition includes:
- The company field, which is of type string. It uses the lucene.whitespace analyzer by default for queries. It has a multi analyzer named mySecondaryAnalyzer which uses the lucene.french analyzer by default for queries. To learn more about multi analyzers, see Path Construction.
- The employees field, which is an array of strings. It uses the lucene.standard analyzer by default for queries.
- The address field, which is of type document. It has two embedded sub-fields, city and state. Instead of explicitly mentioning each nested field in the document, the index definition enables dynamic mapping for all the sub-fields in the document. It uses the lucene.standard analyzer by default for queries.

{
  "analyzer": "lucene.standard",
  "searchAnalyzer": "lucene.standard",
  "mappings": {
    "dynamic": false,
    "fields": {
      "company": {
        "type": "string",
        "analyzer": "lucene.whitespace",
        "multi": {
          "mySecondaryAnalyzer": {
            "type": "string",
            "analyzer": "lucene.french"
          }
        }
      },
      "employees": {
        "type": "string",
        "analyzer": "lucene.standard"
      },
      "address": {
        "type": "document",
        "dynamic": true
      }
    }
  }
}

← Token Filters

How to Index the Elements of an Array →

1	{
2	"mappings": {
3	"dynamic": <boolean>,
4	"fields": {
5	"<field-name>": [
6	{
7	"type": "<field-type>",
8	...
9	},
10	...
11	],
12	...
13	}
14	}
15	}

Define Field Mappings.css-134mg1q{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.css-6vrlzm{border-radius:0!important;display:initial!important;margin:initial!important;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Note

Static and Dynamic Mappings

Static Mappings

Dynamic Mappings

Note

Data Types

Note

Note

Limitations

Index Field as Multiple Data Types

Example

Examples

Static Mapping Example

Combined Mapping Example

Define Field Mappings