Define Field Mappings

When you create a MongoDB Search index, you can specify which fields to index using the following methods:

Dynamic mappings: Enable MongoDB Search to automatically index all fields based on a default or configured set of field types (typeSet).
Static mappings: Enable you to specify which fields to index.

Data Type Limitations

By default, MongoDB Search stops replicating changes for indexes larger than 2.1 billion index objects on a replica set or single shard, where each indexed document or nested embeddedDocument counts as a single object. This means that your index remains queryable, but you might get stale results.

If you plan to index fields that might exceed 2.1 billion objects, where an index object is a top-level document or an embedded document, use the numPartitions index option to partition your index (supported only on Search Nodes deployment) or shard your cluster.

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

Syntax

The following syntax demonstrates how to enable MongoDB Search to index fields using dynamic and static mappings. To learn more about dynamic and static mappings, see Dynamic and Static Mappings.

1 {
2   "mappings": {
3     "dynamic": true|false | {
4         "typeSet": "<typeset-name>"
5     },
6     "fields": {
7       "<field-name>": {
8         "type": "<field-type>",
9         ...
10       },
11       ...
12     }
13   },
14   "typeSets": [
15     {
16       "name": "<typeset-name>",
17       "types": [
18         {
19           "type": "<field-type>",
20           ...
21         },
22         ...
23       ]
24     },
25     ...
26   ]
27 }

Dynamic and Static Mappings

You can configure MongoDB Search with:

Dynamic mappings to automatically index fields based on a default or configured set of types (typeSet)
Static mappings to only index specified fields

You can also use dynamic mappings with static mappings. Static mappings override the dynamic mappings configuration.

Dynamic Mappings

MongoDB Search dynamic mappings allow you to configure MongoDB Search to automatically and recursively index fields in your data. Fields can be indexed based on the default set of types or by configuring a typeSet.

You can enable or configure dynamic mappings:

At the root mappings level to apply to the entire document.
[Recommended] Within a document field type to apply to a specified object.
[Recommended] Within an embeddedDocuments field type to apply to a specified array of objects that require element-wise query comparisons (similar to $elemMatch).

Note

Best Practices

Dynamic mappings might result in indexing a high number of unique fields, which will occupy more disk space and might be less performant. Only use dynamic mappings if you need to index fields that change regularly or that are unknown. Always use dynamic mappings within a document, not at the parent document level.

When you use dynamic mappings to index your data:

MongoDB Search also dynamically indexes all nested fields supported by the typeSet in a document object in your data.
If a field contains polymorphic data, MongoDB Search automatically indexes the field as all of the types supported by the typeSet used in the index. If a field contains data of a type not supported by the typeSet, MongoDB Search won't index that data.

Enable Default `typeSet`

MongoDB Search uses the default typeSet when dynamic is set to true. In the default typeSet, MongoDB Search indexes the BSON types as MongoDB Search field types. The following table shows the BSON types that MongoDB Search automatically indexes as MongoDB Search field types when you use the default typeSet. MongoDB Search also automatically indexes the following BSON types when they are contained within arrays and objects.

BSON Type	MongoDB Search Field Type
Boolean	boolean
Date	date
Double, 32-bit Integer, 64-Bit Integer	number
ObjectId	objectId
String	string
UUID	uuid
Null

The following is the syntax for enabling default type set for dynamic mappings:

1 {
2   "mappings": {
3     "dynamic": true
4   }
5 }

For index examples that demonstrate indexing all fields using the default typeSet, see Dynamic Mapping Examples.

Configure a `typeSet`

Important

Configurable dynamic mappings is in Preview. The feature and corresponding documentation might change at any time during the Preview period. To learn more, see Preview Features.

Specify the MongoDB Search field types to index dynamically by configuring a typeSet. You can configure any BSON type to be automatically indexed as any MongoDB Search field type except document, embeddedDocuments, or deprecated field types.

A typeSet has the following syntax:

1 {
2   "mappings": {
3     "dynamic": {
4       "typeSet": "<typeset-name>"
5     },
6     "fields": {
7       "<field-name>": {
8         "type": "<field-type>",
9         ...
10       },
11       ...
12     }
13   },
14   "typeSets": [
15     {
16       "name": "<typeset-name>",
17       "types": [
18         {
19           "type": "<field-type>"
20         },
21         ...
22       ]
23     },
24     ...
25   ]
26 }

Before configuring a typeSet, consider the following:

You cannot define the same field type multiple times in the same typeSet object. You can configure only one typeSet definition for each field type.
For example, you can't define multiple configurations for the number type in the same typeSet definition.
You can configure dynamic mappings with the multi analyzer.

You can't configure a typeSet from the Atlas UI Visual Editor. Use the Atlas UI JSON Editor instead.

For index examples that demonstrate using custom typeSet configuration, see Dynamic Mapping Examples.

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. When you use static mappings, MongoDB Search indexes only the fields that you specify in mappings.fields. You can also use static mappings to exclude fields from being indexed.

To use static mappings to configure index options for only some fields, set mappings.dynamic to false and specify the field name, data type, and other configuration options for each field that you want to index. You can specify the fields in any order.

If you omit the mappings.dynamic field, it defaults to false.

1 {
2   "mappings": { 
3     "dynamic": true|false, 
4     "fields": { 
5       "<field-name>": {
6         "type": "<field-type>",
7         ...
8       },
9       ...  
10     }
11   }
12 }

To define the index for a nested field, you must define the mappings for each parent field of that nested field. You can't use dot notation to statically index nested fields. For examples, see the Examples or Combined Mapping Example below.

You can use static mappings to index fields as multiple types. To index a field as multiple types, define the types in the field definition array for the field. You can index any field as any supported types using static mappings. To learn more, see MongoDB Search Field Types.

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

1 {
2   "mappings": { 
3     "dynamic": true|false | {
4       "typeSet": "<type-set-name>"
5     }, 
6     "fields": { 
7       "<field-name>": [
8         {
9           "type": "<field-type>",
10           ...
11         },
12         {
13           "type": "<field-type>",
14           ...
15         },
16         ...
17       ],
18       ...  
19     }
20   }.
21   "typeSets": [
22     {
23       "name": "<typeset-name>",
24       "types": [
25         {
26           "type": "<field-type>"
27         },
28         ...
29       ]
30     },
31     ...
32   ]
33 }

For other index examples that demonstrate static mappings, see Static Mapping Example.

MongoDB Search Field Types

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

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

MongoDB Search automatically stores fields of type string on mongot. You can store fields of all supported data types on MongoDB Search using the Define Stored Source Fields in Your MongoDB Search Index option in your index definition. To learn more about mongot and MongoDB Search node architecture, see MongoDB Search Deployment Options.

The following table enumerates the supported BSON data types and the MongoDB Search field types that you can use to index the BSON data types. The table also lists the operators and collectors that you can use to query the field values.

BSON Type	MongoDB Search Field Type	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 facet in near range
Date	dateFacet	facet
Double	number	equals in near range
Double	numberFacet	facet
Double	knnVector	knnBeta
GeoJSON Object	geo	geoShape geoWithin near
32-bit integer	number	equals in facet near range
32-bit integer	numberFacet	facet
64-bit integer	number	equals facet in near range
64-bit integer	numberFacet	facet
Null	N/A	equals
Object	document	Operators that support the field types in the object.
Object	embeddedDocument (for array of objects)	embeddedDocument
ObjectId	objectId	equals in range
String	string	moreLikeThis phrase queryString regex span text wildcard
String	stringFacet	facet
String	autocomplete	autocomplete
String	token	equals facet in range
UUID/BSON Binary Subtype 4	uuid	equals in

These operators do not support an array of strings.

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

Deprecated. To learn more about the deprecated facet field types and their updated counterparts, see Comparing Field Types for Facet.

Note

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

Examples

The following examples use the sample_mflix.movies collection to demonstrate how to configure the fields to index using dynamic and static mappings. If you load the sample data, you can create these indexes on the collection. To learn how to create MongoDB Search indexes, see MongoDB Search Quick Start.

Dynamic Mapping Examples

The following index definition examples demonstrate dynamic mappings.

Enable Dynamic Mapping

Enable dynamic mappings using the boolean flag to automatically index all fields using the default typeSet.

In this index definition, the dynamic boolean flag is set to true to automatically index all dynamically indexable fields in the collection.

{
  mappings: {
    "dynamic": true
  }
}

Configure Dynamic Mapping

Configure dynamic mappings to automatically index only specified field types using custom typeSet definition.

The following index definition configures dynamic mappings for the specified field types. It indexes:

All numeric values in the collection as the number field type using the default settings for that type.
All string values in the collection as the autocomplete type using the edgeGram tokenization strategy with a minimum of four and maximum of ten characters per token.

{
  "mappings": {
    "dynamic": {
      "typeSet": "movieFieldTypes"
    }
  },
  "typeSets": [
    {
      "name": "movieFieldTypes",
      "types": [
        {
          "type": "number"
        },
        {
          "type": "autocomplete",
          "analyzer": "lucene.standard",
          "tokenization": "edgeGram",
          "minGrams": 4,
          "maxGrams": 10
        }
      ]
    }
  ]
}

Multiple Dynamic Mapping Configuration

Configure different dynamic mappings at the root level and for nested fields using custom typeSet definition.

This index definition:

Specifies the default index analyzer as lucene.standard.
Specifies the default search analyzer as 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 MongoDB Search index.
Configures automatic indexing of all string fields at the root level as the following field types using the typeSet named first:
- token type using default settings for the type.
- autocomplete type using default settings for the type.
Specifies static mapping for the awards document, which contains fields with numeric and text values. However, the index definition configures automatic indexing of only fields of type number in the document using the typeSet named second.

{
  "mappings": {
    "dynamic": {
      "typeSet": "first"
    },
    "fields": {
      "awards": {
        "type": "document",
        "dynamic": {
          "typeSet": "second"
        }
      }
    }
  },
  "typeSets": [
    {
      "name": "first",
      "types": [
        {
          "type": "token"
        },
        {
          "type": "autocomplete"
        }
      ]
    },
    {
      "name": "second",
      "types": [
        {
          "type": "number"
        }
      ]
    }
  ]
}

Enable Dynamic Mappings and Configure Dynamic Mappings

Enable dynamic mappings at the root level using default typeSet and configure dynamic mappings for nested fields using custom typeSet definition.

This index definition:

Specifies the default index analyzer as lucene.standard.
Specifies the default search analyzer as 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 MongoDB Search index.
Enables automatic indexing of all dynamically indexable fields at the root level.
Enables automatic indexing of all dynamically indexable fields inside the tomatoes document, but configures automatic indexing of only the number type in the tomatoes.viewer document.

{
  "analyzer": "lucene.standard",
  "searchAnalyzer": "lucene.standard",
  "mappings": {
    "dynamic": true,
    "fields": {
      "tomatoes": {
        "type": "document",
        "dynamic": true,
        "fields": {
          "viewer": {
            "type": "document",
            "dynamic": {
              "typeSet": "numericOnly"
            }
          }
        }
      }
    }
  },
  "typeSets": [
    {
      "name": "numericOnly",
      "types": [
        {
          "type": "number"
        }
      ]
    }
  ]
}

Static Mapping Example

The following index definition example demonstrates static mappings.

Simple Example

Disable dynamic mappings, but define individual fields for indexing.

Specifies the default index analyzer as lucene.standard.
Specifies the default search analyzer as 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 MongoDB Search index.
Specifies static field mappings (dynamic: false), which means fields that are not explicitly mentioned are not indexed. So, the index definition includes:
- The awards field, which is of type document. It has three embedded sub-fields, wins, nominations and text.
  The wins and nominations sub-fields uses the lucene.standard analyzer by default for queries. MongoDB Search indexes int64 values in the nominations field.
  The text sub-field uses the lucene.english analyzer by default for queries. It uses the ignoreAbove option to ignore any string of more than 255 bytes in length.
- The title 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.
- The genres field, which is an array of strings. It uses the lucene.standard analyzer by default for queries. For indexing arrays, MongoDB 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": {
      "awards": {
        "type": "document",
        "fields": {
          "wins": {
            "type": "number"
          },
          "nominations": {
            "type": "number",
            "representation": "int64"
          },
          "text": {
            "type": "string",
            "analyzer": "lucene.english",
            "ignoreAbove": 255
          }
        }
      },
      "title": {
        "type": "string",
        "analyzer": "lucene.whitespace",
        "multi": {
          "mySecondaryAnalyzer": {
            "type": "string",
            "analyzer": "lucene.french"
          }
        }
      },
      "genres": {
        "type": "string",
        "analyzer": "lucene.standard"
      }
    }
  }
}

Exclude Fields Example

Configure dynamic mappings, but exclude fields from being indexed using static mappings.

This index definition:

Specifies the default index analyzer as lucene.standard.
Specifies the default search analyzer as 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 MongoDB Search index.
Configures dynamic mappings for specific field types using the typeSet named indexedTypes, which specifies the following:
- The fields of type string must be automatically indexed as token type using the default settings for the token type.
- The fields of type number must be automatically indexed as number type using the default settings for the number type.
Excludes the plot field from being indexed.

{
  "analyzer": "lucene.standard",
  "searchAnalyzer": "lucene.standard",
  "mappings": {
    "dynamic": {
      "typeSet": "indexedTypes"
    },
    "fields": {
      "plot": []
    }
  },
  "typeSets": [
    {
      "name": "indexedTypes",
      "types": [
        {
          "type": "token"
        },
        {
          "type": "number"
        }
      ]
    }
  ]
}

Combined Mapping Example

The following index definition examples combine dynamic mappings with static mappings.

Simple Example

Disable dynamic mappings at the root level, but define static mappings and enable dynamic mappings for nested fields.

This index definition:

Specifies the default index analyzer as lucene.standard.
Specifies the default search analyzer as 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 MongoDB Search index.

Specifies static field mappings (dynamic: false), which means fields and field types that aren't explicitly mentioned aren't indexed. So, the index definition includes:

The title 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.
The genres field, which is an array of strings. It uses the lucene.standard analyzer by default for queries.
The awards field, which is of type document. It has three embedded sub-fields, wins, nominations and text. 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": {
      "title": {
        "type": "string",
        "analyzer": "lucene.whitespace",
        "multi": {
          "mySecondaryAnalyzer": {
            "type": "string",
            "analyzer": "lucene.french"
          }
        }
      },
      "genres": {
        "type": "string",
        "analyzer": "lucene.standard"
      },
      "awards": {
        "type": "document",
        "dynamic": true
      }
    }
  }
}

Complex Example

Configure dynamic mappings for specific field types and define static mappings for individual fields.

This index definition:

Specifies the default index analyzer as lucene.standard.
Specifies the default search analyzer as 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 MongoDB Search index.

Specifies static field mappings (dynamic: false), which means fields and field types that aren't explicitly mentioned aren't indexed. So, the index definition includes only the awards field, which is of type document.

The awards field has three embedded sub-fields, wins, nominations, and text. Instead of automatically indexing all the fields in the document by explicitly setting dynamic to true or by explicitly indexing each nested field in the document using static mappings, the index definition configures dynamic mappings for the document field type using the field types definition named movieAwards:

Index fields of type string using both lucene.english and lucene.french analyzers.
Index fields of type number using the default settings for the number type.

Index fields of type string as also autocomplete type using edgeGram tokenization strategy to create tokens between three to five characters in length.

{
  "analyzer": "lucene.standard",
  "searchAnalyzer": "lucene.standard",
  "mappings": {
    "dynamic": false,
    "fields": {
      "awards": {
        "type": "document",
        "dynamic": {
          "typeSet": "movieAwards"
        }
      }
    }
  },
  "typeSets": [
    {
      "name": "movieAwards",
      "types": [
        {
          "type": "string",
          "multi": {
            "english": {
              "type": "string",
              "analyzer": "lucene.english"
            },
            "french": {
              "type": "string",
              "analyzer": "lucene.french"
            }
          }
        },
        {
          "type": "number"
        },
        {
          "type": "autocomplete",
          "analyzer": "lucene.standard",
          "tokenization": "edgeGram",
          "minGrams": 3,
          "maxGrams": 5,
          "foldDiacritics": false
        }
      ]
    }
  ]
}

Multiple Field Type Definition Example

Configure dynamic mappings at the root level and inside static mappings for nested fields.

In this index definition:

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 MongoDB Search index.
The index specifies dynamic mappings for the field types defined in the typeSet definition named first. The first typeSet definition indexes all fields of type string as the token type and all fields of type number as the number type using default settings for the field types.
The index definition specifies static mappings for the awards field, but configures dynamic mappings for fields in the awards document using the typeSet named second. The second field type definition indexes all fields of type string in the awards document as autocomplete type using default settings for that type.

{
  "analyzer": "lucene.standard",
  "searchAnalyzer": "lucene.standard",
  "mappings": {
    "dynamic": {
      "typeSet": "first"
    },
    "fields": {
      "awards": {
        "type": "document",
        "dynamic": {
          "typeSet": "second"
        }
      }
    }
  },
  "typeSets": [
    {
      "name": "first",
      "types": [
        {
          "type": "token"
        },
        {
          "type": "number"
        }
      ]
    },
    {
      "name": "second",
      "types": [
        {
          "type": "autocomplete"
        }
      ]
    }
  ]
}

Back

Token Filters

array

1	{
2	"mappings": {
3	"dynamic": true\|false \| {
4	"typeSet": "<typeset-name>"
5	},
6	"fields": {
7	"<field-name>": {
8	"type": "<field-type>",
9	...
10	},
11	...
12	}
13	},
14	"typeSets": [
15	{
16	"name": "<typeset-name>",
17	"types": [
18	{
19	"type": "<field-type>",
20	...
21	},
22	...
23	]
24	},
25	...
26	]
27	}

1	{
2	"mappings": {
3	"dynamic": {
4	"typeSet": "<typeset-name>"
5	},
6	"fields": {
7	"<field-name>": {
8	"type": "<field-type>",
9	...
10	},
11	...
12	}
13	},
14	"typeSets": [
15	{
16	"name": "<typeset-name>",
17	"types": [
18	{
19	"type": "<field-type>"
20	},
21	...
22	]
23	},
24	...
25	]
26	}

1	{
2	"mappings": {
3	"dynamic": true\|false,
4	"fields": {
5	"<field-name>": {
6	"type": "<field-type>",
7	...
8	},
9	...
10	}
11	}
12	}

1	{
2	"mappings": {
3	"dynamic": true\|false \| {
4	"typeSet": "<type-set-name>"
5	},
6	"fields": {
7	"<field-name>": [
8	{
9	"type": "<field-type>",
10	...
11	},
12	{
13	"type": "<field-type>",
14	...
15	},
16	...
17	],
18	...
19	}
20	}.
21	"typeSets": [
22	{
23	"name": "<typeset-name>",
24	"types": [
25	{
26	"type": "<field-type>"
27	},
28	...
29	]
30	},
31	...
32	]
33	}

Data Type Limitations

Syntax

Dynamic and Static Mappings

Dynamic Mappings

Note

Best Practices

Enable Default typeSet

Configure a typeSet

Important

Static Mappings

MongoDB Search Field Types

Note

Examples

Dynamic Mapping Examples

Enable Dynamic Mapping

Configure Dynamic Mapping

Multiple Dynamic Mapping Configuration

Enable Dynamic Mappings and Configure Dynamic Mappings

Static Mapping Example

Simple Example

Exclude Fields Example

Combined Mapping Example

Simple Example

Complex Example

Multiple Field Type Definition Example

Enable Default `typeSet`

Configure a `typeSet`