Docs Menu

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
  • geo
  • number
  • numberFacet
  • objectId
  • string
  • stringFacet
  • Examples
  • Static Mapping Example
  • Combined Mapping Example

When you create an Atlas Search index, you can explicitly specify the fields to index using static mappings. Alternatively, you can configure Atlas Search to automatically index all the supported field types in the collection using dynamic mappings.

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.

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.

Note

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

The following table enumerates all the BSON data types and indicates whether they are included in an Atlas Search index with dynamic mappings. The table also shows the Atlas Search field type for supported BSON data types.

BSON Type
Included in Dynamic Index?
Atlas Search Field Type
Double
yes (see Limitations)
32-bit integer
yes (see Limitations)
64-bit integer
yes (see Limitations)
String
yes (see Limitations)
Date
yes (see Limitations)
Object
yes
ObjectId
no
Boolean
no
Timestamp
no
yes
Binary Data
no
Null
no
Regular Expression
no
JavaScript
no
Decimal128
no
Min key
no
Max key
no
Note

You can store fields of all BSON Data Types on Atlas Search using the storedSource option.

You can't use dynamic mapping to automatically index fields of date, number, and string types for faceting. You must index the fields using:

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

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

Example

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

{
...
"mappings": {
"dynamic": <boolean>,
"fields": {
"<field-name>": [
{
"type": "<field-type>",
...
},
{
"type": "<field-type>",
...
},
...
]
}
}
}

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.

Note
  • 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.
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"
}
}
}
}

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.

Note

You can't use the autocomplete type to index:

  • Fields whose value is an array of strings.
  • Fields in a document that is contained in an array.

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.

    Note

    You can specify rightEdgeGram only in the JSON Editor. You can't select the rightEdgeGram tokenization strategy in the Visual Editor.

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

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

Note
Limitations
  • Atlas Search doesn't index fields of type boolean dynamically. You must index fields of type boolean using static mappings.
  • Atlas Search doesn't index fields of type boolean in an array or in a document inside an array.
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

Atlas Search support for faceting on numeric and date fields using number and date type is being deprecated. Although you can continue using existing facet definitions on the number and date types, make a note of the following:

  • We recommend using the new numberFacet and dateFacet types in all index definitions for faceting on numeric and date fields, respectively.
  • Support for faceting on numeric and date fields using number and date types will be removed in August 2022.

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

Note

You can't index date field if it's part of an array or if it's in a document in an array.

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

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 if it's inside an array or if it's inside a document in an array for faceting.

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 learn more, see BSON Data Types.
  • Any fields that you explicitly exclude using the fields parameter.

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

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.

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.

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": {
"type": "document",
"<field-name>": {
"indexShapes": true|false,
"type": "geo"
}
}
}
}
Note

Atlas Search support for faceting on numeric and date fields using number and date type is being deprecated. Although you can continue using existing facet definitions on the number and date types, make a note of the following:

  • We recommend using the new numberFacet and dateFacet types in all index definitions for faceting on numeric and date fields, respectively.
  • Support for faceting on numeric and date fields using number and date types will be removed in August 2022.

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

Note

You can't index numeric values in arrays or in a document in an array.

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

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 in an array for faceting.

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.

Note

Fields of type objectId can't be dynamically indexed. You must index fields of type objectId using static mappings. To learn more, see the example in the boolean section on this page.

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.
lucene.standard
searchAnalyzer
string
Optional
Analyzer to use when querying the field.
lucene.standard
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.
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"
}
}
}
}
}
}
Note
Preview

Atlas Search facet and count 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.

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.

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

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

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 →
Give Feedback
© 2022 MongoDB, Inc.

About

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