Define Field Mappings

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.

Static and Dynamic Mappings

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.

BSON Data Types

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)	number numberFacet
32-bit integer	yes (see Limitations)	number numberFacet
64-bit integer	yes (see Limitations)	number numberFacet
String	yes (see Limitations)	string stringFacet
Date	yes (see Limitations)	date dateFacet
Object	yes	document
ObjectId	no	objectId
Boolean	no	boolean
Timestamp	no
Array	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.

Limitations

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

dateFacet to run a facet query on date fields.
numberFacet to run a facet query on number fields.
stringFacet to run a facet query on string fields.

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:

autocomplete
boolean
date
dateFacet
number
numberFacet

Index Field as Multiple Data Types

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>",
          ...
        },
        ...
      ]
    }
  }
}

Index Array

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

Atlas Search Field Types

autocomplete

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:

nGram Tokenizer
edgeGram Tokenizer
daitchMokotoffSoundex Token Filter
nGram Token Filter
edgeGram Token Filter
shingle Token Filter

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

boolean

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

date

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.

dateFacet

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

document

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

geo

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

number

Note

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`

`representation` Example

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

`indexIntegers` Example

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

`indexDoubles` Example

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

numberFacet

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

objectId

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.

string

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 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`

`multi` Example

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

stringFacet

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

Example

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

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,
        "analyzer": "lucene.standard"
      }
    }
  }
}

← Token Filters Define Stored Source Fields in Your Atlas Search Index →

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

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

representation Example

indexIntegers Example

indexDoubles Example

numberFacet

objectId

string

multi Example

stringFacet

Example

Examples

Static Mapping Example

Combined Mapping Example

Define Field Mappings

`representation` Example

`indexIntegers` Example

`indexDoubles` Example

`multi` Example