Define Field Mappings
On this page
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.
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.
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. 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.
BSON Data Types
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? |
---|---|---|
✓ | ||
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.
Limitations
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:
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.
Index Field as Multiple Data Types
To index a field as multiple types, define the types in the field definition array for the field.
Example
The following example shows the field definition for indexing a field as multiple types.
1 { 2 ... 3 "mappings": { 4 "dynamic": <boolean>, 5 "fields": { 6 "<field-name>": [ 7 { 8 "type": "<field-type>", 9 ... 10 }, 11 { 12 "type": "<field-type>", 13 ... 14 }, 15 ... 16 ], 17 ... 18 }, 19 ... 20 } 21 }
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.
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.
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.
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.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:
When tokenized with NoteIndexing a field for autocomplete with an | 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 |
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" } ] } } }
boolean
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" } } } }
date
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.
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 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" } } } }
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 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 ImportantAtlas Search dynamically indexes all fields in a | 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 . |
embeddedDocuments
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 to5
levels of nesting. AnembeddedDocuments
field can't have more than4
parentembeddedDocuments
fields.You can't use
embeddedDocuments
for date or numeric faceting.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:
| false |
fields | document | Conditional | Fields to index. If If NoteAtlas Search doesn't support indexing facet fields as part of an
| {} |
Examples
The following index examples use the sample_supplies.sales
collection in the sample dataset.
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:
Value can be:
| false |
Example
{ "mappings": { "dynamic": false, "fields": { "type": "document", "<field-name>": { "indexShapes": true|false, "type": "geo" } } } }
number
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 onnumber
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:
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
fieldRounds 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 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:
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.
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 | ||
searchAnalyzer | string | Optional | ||
indexOptions | string | Optional | Amount of information to store for the indexed field. Value can be one of the following:
| 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 NoteTo reduce the index size and performance footprint, we
recommend setting | 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:
If value is If value is | 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
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.
stringFacet
Examples
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 typedocument
. It has two embedded sub-fields,city
andstate
.The
city
sub-field uses the lucene.simple analyzer by default for queries. It uses theignoreAbove
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 typestring
. It uses the lucene.whitespace analyzer by default for queries. It has amulti
analyzer namedmySecondaryAnalyzer
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 typestring
. It uses the lucene.whitespace analyzer by default for queries. It has amulti
analyzer namedmySecondaryAnalyzer
which uses the lucene.french analyzer by default for queries. To learn more aboutmulti
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 typedocument
. It has two embedded sub-fields,city
andstate
. 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" } } } }