Docs Menu

Docs HomeMongoDB Atlas

Define Field Mappings

On this page

  • Static and Dynamic Mappings
  • BSON Data Types
  • Limitations
  • Index Field as Multiple Data Types
  • Index Array
  • Atlas Search Field Types
  • autocomplete
  • boolean
  • date
  • dateFacet
  • document
  • embeddedDocuments
  • geo
  • number
  • numberFacet
  • objectId
  • string
  • stringFacet
  • 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"mappings": {
2 "dynamic": <boolean>,
3 "fields": {
4 "<field-name>": [
5 {
6 "type": "<field-type>",
7 ...
8 },
9 ...
10 ],
11 ...
12 }
13}

Note

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

For Static mappings, set mappings.dynamic to false and specify the fields to index using mappings.fields. Atlas Search only indexes the specified fields with specific options.

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

Note

You must specify static mappings when mappings.dynamic is false.

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.

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 Limitations.

Note

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

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

  • Binary Data

  • Decimal128

  • JavaScript code with scope

  • Max key

  • Min key

  • Null

  • Regular Expression

  • Timestamp

The following table enumerates the supported BSON data types and the Atlas Search field type for 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.

BSON Type
Atlas Search Field Type
Dynamic Indexing?
Array
Boolean
Date
Date
Double
Double
32-bit integer
32-bit integer
64-bit integer
64-bit integer
Object
Object
embeddedDocuments (for array of objects)
ObjectId
String
String
String

Some limitations apply. To learn more, see Limitations and Index Array.

Note

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

Atlas Search doesn't support dynamic mapping to automatically index fields of any type for faceting. Instead, you must use static mappings to index the fields as the following Atlas Search field 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}

For indexing arrays, Atlas Search requires only 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.

Example

The following index definition for the sample_mflix.movies collection in the sample dataset indexes the genres field, which contains an array of string values.

{
"mappings": {
"dynamic": false,
"fields": {
"genres": {
"type": "string"
}
}
}
}

Atlas Search doesn't index the following Atlas Search field types if the field type is contained in an array or is in a document that is contained in an array:

Atlas Search supports indexing the supported data types inside an array by flattening the fields during indexing.

Example

For example, consider the following documents:

doc1 = { a: {b: [[<value1>, <value2>], <value3>] }}
doc2 = { a: {b: [<value1>, <value2>, <value3>] } }
doc3 = { a: [{ b: <value1>}, {b: <value2>}, {b: <value3>}] }

Atlas Search flattens the preceding arrays similar to the following during indexing:

LuceneDoc<n> = {"a.b":[<value1>,<value2>,<value3>]}

For querying individual documents inside an array of documents, you must use the embeddedDocuments type.

You can use the autocomplete data type to index text values for autocompletion. You can configure an autocomplete field to satisfy a variety of use cases. To learn more about the configuration options available in the autocomplete data type, such as tokenization strategy and diacritic folding, see autocomplete. You can use the autocomplete operator to query only fields indexed using autocomplete.

You can also use the autocomplete type to index:

  • Fields whose value is an array of strings. To learn more, see Index Array.

  • String fields inside an array of documents indexed as the embeddedDocuments type.

The following limitations apply:

Important

Atlas Search doesn't support indexing more than approximately two billion index objects, where each indexed document counts as a single object against this hard limit. Using the autocomplete type could result in indexing objects in excess of this limit, which will cause an index to transition to a failed state. If you have large arrays that might generate two billion objects, we recommend sharding clusters that contain indexes with autocomplete field type.

Tip

If you have a large number of documents and a wide range of data against which you wish to run Atlas Search queries using the autocomplete operator, we recommend that you create a separate index of type autocomplete because building this index could take some time. You can define an autocompete-specific index to reduce the impact on other indexes and queries while the index builds.

The autocomplete type takes the following options:

Option
Type
Necessity
Purpose
Default
type
string
required
Human-readable label that identifies this field type. Value must be autocomplete.
analyzer
string
optional

Name of the analyzer to use with this autocomplete mapping. You can use any Atlas Search analyzer except the lucene.kuromoji language analyzer and the following custom analyzer tokenizers and token filters:

lucene.standard
maxGrams
int
optional
Maximum number of characters per indexed sequence. The value limits the character length of indexed tokens. When you search for terms longer than the maxGrams value, Atlas Search truncates the tokens to the maxGrams length.
15
minGrams
int
optional
Minimum number of characters per indexed sequence. We recommend 4 for the minimum value. A value that is less than 4 could impact performance because the size of the index can become very large. We recommend the default value of 2 for edgeGram only.
2
tokenization
enum
optional

Tokenization strategy to use when indexing the field for autocompletion. Value can be one of the following:

  • edgeGram - create indexable tokens, referred to as grams, from variable-length character sequences starting at the left side of the words as delimited by the analyzer used with this autocomplete mapping.

  • rightEdgeGram - create indexable tokens, referred to as grams, from variable-length character sequences starting at the right side of the words as delimited by the analyzer used with this autocomplete mapping.

  • nGram - create indexable tokens, referred to as grams, by sliding a variable-length character window over a word. Atlas Search creates more tokens for nGram than edgeGram or rightEdgeGram. Therefore, nGram takes more space and time to index the field. nGram is better suited for querying languages with long, compound words or languages that don't use spaces.

edgeGram, rightEdgeGram, and nGram are applied at the letter-level. For example, consider the following sentence:

The quick brown fox jumps over the lazy dog.

When tokenized with minGrams value of 2 and maxGrams value of 5, Atlas Search indexes the following sequence of characters based on the tokenization value you choose:

Note

Indexing a field for autocomplete with an edgeGram, rightEdgeGram, or nGram tokenization strategy is more computationally expensive than indexing a string field. The index takes more space than an index with regular string fields.

edgeGram
foldDiacritics
boolean
optional

Flag that indicates whether diacritics should be included or removed from the indexed text. Value can be one of the following:

  • true - ignore diacritic marks in the index and query text. Returns results with and without diacritic marks. For example, a search for cafè returns results with the characters cafè and cafe.

  • false - include diacritic marks in the index and query text. Returns only results that match the strings with or without diacritics in the query. For example, a search for cafè returns results only with the characters cafè. A search for cafe returns results only with the characters cafe.

true

Example

{
"mappings": {
"dynamic": true|false,
"fields": {
"<field-name>": {
"type": "autocomplete",
"analyzer": "lucene.standard",
"tokenization": "edgeGram|rightEdgeGram|nGram",
"minGrams": <2>,
"maxGrams": <15>,
"foldDiacritics": true|false
}
}
}
}
}

Note

You can index a field as other types also by specifying the other types in the array. For example, the following index definition indexes the field as both autocomplete and string types.

{
"mappings": {
"dynamic": true|false,
"fields": {
"<field-name>": {
"type": "autocomplete",
"analyzer": "lucene.standard",
"tokenization": "edgeGram|rightEdgeGram|nGram",
"minGrams": <2>,
"maxGrams": <15>,
"foldDiacritics": true|false
},
{
"type": "string"
}
}
}
}
}

Use the boolean data type to index true and false values. It works in conjunction with the equals operator.

Example

The following example index definition maps a field named verified_user to the boolean data type and a field named teammates to the objectId data type.

{
"mappings": {
"dynamic": false,
"fields": {
"verified_user": {
"type": "boolean"
},
"teammates": {
"type": "objectId"
}
}
}
}

Note

We are extending support for faceting on numeric and date fields using number and date type from August to September 2022. You must migrate to the numberFacet and dateFacet types in all index definitions for faceting on numeric and date fields, respectively.

Use the date type to index date values. It takes the type option. The value of type must be date.

Note

You must index the date fields using dateFacet to run a facet query on date fields.

You must use the range operator only to query indexed date values inside arrays. You can't use the near operator to query date values stored in an array, even if you have an Atlas Search index on the date values inside the array.

Use the dateFacet type for indexing date values for faceting. It takes the type option. The value of type must be dateFacet.

Note

You can't index date field for faceting if it's inside an array or if it's inside a document in an array.

Atlas Search doesn't support date faceting over fields indexed as part of an embeddedDocuments field.

Example

The following index definition for the sample_mflix.movies collection in the sample dataset indexes the released field as dateFacet for faceting.

{
"mappings": {
"dynamic": false,
"fields": {
"released": {
"type": "dateFacet"
}
}
}
}

Use the document data type to index fields with embedded documents. It takes the following parameters:

Option
Type
Necessity
Purpose
Default
type
string
Required
Human-readable label that identifies the field type. Value must be document.
dynamic
boolean
Conditional

Flag that indicates whether Atlas Search recursively indexes all fields and embedded documents. If set to true, Atlas Search recursively indexes all fields and embedded documents in the document except fields of certain data types.

To index all fields in a document including fields that Atlas Search doesn't dynamically index, define the fields in the index definition.

If omitted or set to false, you must specify individual fields to index.

Important

Atlas Search dynamically indexes all fields in a document using the default settings for the detected data type. Atlas Search also dynamically indexes all nested documents under the document, unless you explicitly override by setting dynamic to false.

false
fields
document
Conditional
Document that maps field names to field definitions. To learn more, see an example. This is required if dynamic is omitted or set to false.

Note

The Atlas Search embeddedDocuments index option, embeddedDocument operator, and embedded scoring option are in preview. When an Atlas Search index on a replica set or single MongoDB shard reaches Lucene’s two billion document limit, Atlas Search doesn't index new documents or apply updates to existing documents for that index. A solution to accomodate this limitation will be in place when we make this feature generally available. Meanwhile, the MongoDB Cloud Support team will help troubleshoot any issues related to using this feature as part of your contract.

Use the embeddedDocuments type to index fields in documents that are elements of an array. Atlas Search indexes embedded documents independent of their parent document. Each indexed document contains only fields that are part of the embedded document array element.

The following limitations apply:

  • You can use embeddedDocuments only on fields with up to 5 levels of nesting. An embeddedDocuments field can't have more than 4 parent embeddedDocuments fields.

  • You can't use embeddedDocuments for date or numeric faceting.

  • You can't highlight fields or children of fields indexed as the embeddedDocuments type.

  • You can't use the Atlas UI Visual Index Builder to define fields of embeddedDocuments type.

Important

Atlas Search doesn't support indexing more than approximately two billion index objects, where each indexed embedded document counts as a single object against this hard limit. Using embeddedDocuments type could result in indexing objects in excess of this limit, which will cause an index to transition to a failed state. If you have large arrays that might generate two billion objects, we recommend sharding clusters that contain indexes with embeddedDocuments field type.

It takes the following options:

Option
Type
Necessity
Purpose
Default
type
string
Required
Human-readable label that identifies the field type. Value must be embeddedDocuments.
dynamic
boolean
Optional

Flag that specifies whether to index every dynamically indexable field in the document. Value can be one of the following:

  • true - index all indexable fields

  • false - don't index all the indexable fields

false
fields
document
Conditional

Fields to index.

If dynamic is true, Atlas Search indexes all indexable fields.

If dynamic is false, you can specify the fields to index in the field definition for fields.

Note

Atlas Search doesn't support indexing facet fields as part of an embeddedDocuments field.

{}

The following index examples use the sample_supplies.sales collection in the sample dataset.

Use the geo type to index geographic point and shape coordinates. For this type, the indexed field must be a GeoJSON object.

Option
Type
Necessity
Purpose
Default
type
string
Required
Human-readable label that identifies this field type. Value must be geo.
indexShapes
boolean
Optional

Flag that indicates whether to index shapes. By default, Atlas Search:

  • Indexes points, even when nested.

  • Doesn't index shape geometries such as lines and polygons.

Value can be:

  • true to index shapes and points

  • false to index only points

false

Example

{
"mappings": {
"dynamic": false,
"fields": {
"<field-name>": {
"indexShapes": true|false,
"type": "geo"
}
}
}
}

Note

We are extending support for faceting on numeric and date fields using number and date type from August to September 2022. You must migrate to the numberFacet and dateFacet types in all index definitions for faceting on numeric and date fields, respectively.

Use the number type to index fields with numeric values of int32, int64, dateTime, and double data types.

Note

  • You must index the number fields using numberFacet to run a facet query on number fields.

  • You can use the range operator only to query numeric values in arrays.

The number type has the following options:

Option
Type
Necessity
Purpose
Default
type
string
Required
Human-readable label that identifies this field type. Value must be number.
representation
string
Optional

Data type of the field to index. Values are:

  • int64 - for indexing large integers without loss of precision and for rounding double values to integers. You can't use this type to index large double values.

  • double - for indexing large double values without rounding.

To learn more, see example below.

double
indexIntegers
boolean
Optional
Flag that indicates whether to index or omit indexing int32 and int64 type values. Value can be true or false. To learn more, see example below.
true
indexDoubles
boolean
Optional
Flag that indicates whether to index or omit indexing double type values. Value can be true or false. To learn more, see example below.
true

Example

The following index definition for the sample_analytics.accounts collection in the sample dataset indexes the account_id field with 64-bit integer values. The following example also:

  • Indexes all other integer values in the account_id field

  • Rounds any decimal values and indexes small double type values in the account_id field

{
"mappings": {
"dynamic": false,
"fields": {
"account_id": {
"type": "number",
"representation": "int64"
}
}
}
}

Example

The following index definition for the sample_airbnb.listingsAndReviews collection in the sample dataset omits the bathrooms field with 32-bit and 64-bit integer values. The following example will index the bathrooms field with double type values.

{
"mappings": {
"dynamic": false,
"fields": {
"bathrooms": {
"type": "number",
"indexIntegers": false
}
}
}
}

Example

The following index definition for the sample_analytics.accounts collection in the sample dataset:

  • Indexes the account_id field with integer values.

  • Omits the account_id field with doubles values.

{
"mappings": {
"dynamic": false,
"fields": {
"account_id": {
"type": "number",
"representation": "int64",
"indexDoubles": false
}
}
}
}

Use the numberFacet data type for indexing numeric values using the specified representation for faceting. You can index numbers of BSON types int32, int64, and double. The following limitations apply:

  • You can't index decimal128 for faceting.

  • You can't index numeric values in arrays or in a document contained in an array for faceting.

  • You can't facet over numeric fields indexed as part of an embeddedDocuments field.

If you specify both number and numberFacet in the index definition, Atlas Search uses the numberFacet options only for faceted queries on numeric fields.

The numberFacet type has the following options:

Option
Type
Necessity
Purpose
Default
type
string
Required
The type of field. Value must be numberFacet.
representation
string
Optional

The data type of the field to index. Values can be one of the following BSON types:

  • int64 - for indexing large integers without loss of precision and for rounding double values to integers. You can't use this type to index large double values.

  • double - for indexing large double values without rounding.

To learn more, see example below.

double
indexIntegers
boolean
Optional
Indicates whether to index or omit indexing int32 and int64 type values. Value can be true or false. To learn more, see example below. Either this or indexDoubles must be true.
true
indexDoubles
boolean
Optional
Indicates whether to index or omit indexing double type values. Value can be true or false. To learn more, see example below. Either this or indexIntegers must be true.
true

Example

The following index definition for the sample_mflix.movies collection in the sample dataset indexes the year field as numberFacet for faceting.

{
"mappings": {
"dynamic": false,
"fields": {
"year": {
"type": "numberFacet"
}
}
}
}

Use the objectId data type to index ObjectId fields. It works in conjunction with the equals operator.

Use the string data type to index string fields.

Note

You can't use dynamic mapping to automatically index string fields for faceting. You must index the fields using stringFacet to run a facet query on string fields.

The string data type takes the following parameters:

Option
Type
Necessity
Purpose
Default
type
string
Required
Human-readable label that identifies this field type. Value must be string.
analyzer
string
Optional

Name of a built-in or overridden analyzer to use for indexing the field. If omitted, defaults to an analyzer in the following order:

  1. The analyzer option for the index if specified.

  2. The lucene.standard analyzer.

searchAnalyzer
string
Optional

Analyzer to use when querying the field. If omitted, defaults to an analyzer in the following order:

  1. The analyzer option for this field if specified.

  2. The searchAnalyzer option for the index if specified.

  3. The analyzer option for the index if specified.

  4. The lucene.standard analyzer.

indexOptions
string
Optional

Amount of information to store for the indexed field. Value can be one of the following:

  • docs - Only indexes documents. The frequency and position of the indexed term are ignored. Only a single occurence of the term is reflected in the score.

  • freqs - Only indexes documents and term frequency. The position of the indexed term is ignored.

  • positions - Indexes documents, term frequency, and term positions.

  • offsets - (Default) Indexes documents, term frequency, term positions, and term offsets. This option is required for Highlight Search Terms in Results.

offsets
store
boolean
Optional

Flag that indicates whether or not to store the exact document text as well as the analyzed values in the index. Value can be true or false. The value for this option must be true for Highlight Search Terms in Results.

Note

To reduce the index size and performance footprint, we recommend setting store to false. To learn more, see Index Performance.

true
ignoreAbove
int
Optional
Maximum number of characters in the value of the field to index. Atlas Search doesn't index if the field value is greater than the specified number of characters.
multi
String Field Definition
Optional
String field to index with the name of the alternate analyzer specified in the multi object. To learn more about specifying the multi object, see Multi Analyzer and example below.
norms
string
Optional

String that specifies whether to include or omit the field length in the result when scoring. The length of the field is determined by the number of tokens produced by the analyzer for the field. Value can be one of the following:

  • include - to include the field length when scoring.

  • omit - to omit the field length when scoring.

If value is include, Atlas Search uses the length of the field to determine the higher score when scoring. For example, if two documents match an Atlas Search query, the document with the shorter field length scores higher than the document with the longer field length.

If value is omit, Atlas Search ignores the field length when scoring.

include

Example

The following index definition for a library.books collection indexes string values in the field text with the lucene.english and lucene.french analyzers in addition to the default lucene.standard analyzer:

{
"mappings": {
"dynamic": false,
"fields": {
"text": {
"type": "string",
"multi": {
"english": {
"type": "string",
"analyzer": "lucene.english"
},
"french": {
"type": "string",
"analyzer": "lucene.french"
}
}
}
}
}
}

Use the stringFacet data type to index string fields for faceting, which allows you to run a facet query on that field. Atlas Search doesn't apply the analyzer when indexing string fields for faceting. The stringFacet data type takes the following parameter:

Option
Type
Necessity
Purpose
Default
type
string
Required
Human-readable label that identifies this field type. Value must be stringFacet.

Note

To perform a normal search on the same field, you must index the field as type string also.

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"
}
}
}
}

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,
"analyzer": "lucene.standard"
}
}
}
}
←  Token FiltersDefine Stored Source Fields in Your Atlas Search Index →
Share Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.