Define Field Mappings for a MongoDB Search Index

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

Define Field Mappings for a MongoDB Search Index

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

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

• Static mappings: Enable you to specify which fields to index.

Data Type Limitations

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

If you plan to index fields that might exceed 2,100,000,000 objects, where an index object is a top-level document or an embedded document, use the [numPartitions](https://www.mongodb.com/docs/search/indexes/index-partition.md#std-label-fts-index-partition index option to partition your index (supported only on Search Nodes deployment) or [shard your cluster.](https://www.mongodb.com/docs/atlas/cluster-additional-settings.md#std-label-create-cluster-sharding

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

• The [autocomplete](https://www.mongodb.com/docs/search/indexes/field-types/autocomplete-type.md#std-label-bson-data-types-autocomplete field type can create large indexes and take longer to build than other field types. While you can use the autocomplete type in dynamic mappings by including it in a custom typeSet definition, we recommend using the autocomplete type in static mappings only to avoid unintended performance, storage, and scoring implications. To learn more, see [How to Index Fields for Autocompletion](https://www.mongodb.com/docs/search/indexes/field-types/autocomplete-type.md#std-label-bson-data-types-autocomplete and [Improve MongoDB Search Index Performance.](https://www.mongodb.com/docs/search/performance/index-performance.md#std-label-index-perf

Syntax

The following syntax demonstrates how to enable MongoDB Search to index fields using dynamic and static mappings. To learn more about dynamic and static mappings, see [Dynamic and Static Mappings.](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-static-dynamic-mappings

{
  "mappings": {
    "dynamic": true|false | {
        "typeSet": "<typeset-name>"
    },
    "fields": {
      "<field-name>": {
        "type": "<field-type>",
        ...
      },
      ...
    }
  },
  "typeSets": [
    {
      "name": "<typeset-name>",
      "types": [
        {
          "type": "<field-type>",
          ...
        },
        ...
      ]
    },
    ...
  ]
}

Dynamic and Static Mappings

You can configure MongoDB Search with:

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

• Static mappings to only index specified fields

You can also use dynamic mappings with [static mappings](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-fts-static-mappings. Static mappings override the dynamic mappings configuration. When you define a static mapping for a field, MongoDB Search indexes that field only according to the static mapping definition. The dynamic mapping no longer applies to that field.

For example, if you enable dynamic: true, MongoDB Search indexes string fields as the string type by default. If you then add a static autocomplete mapping for a specific string field, MongoDB Search indexes that field only as the autocomplete type. It is not also indexed as string unless you explicitly include string in the static mapping. To index the field as both types, you must define both types in the field's static mapping array.

Dynamic Mappings

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

You can enable or configure dynamic mappings:

• At the root mappings level to apply to the entire document.

• [Recommended] Within a document field type to apply to a specified object.

• [Recommended] Within an embeddedDocuments field type to apply to a specified array of objects that require element-wise query comparisons (similar to $elemMatch).

Note: Best Practices

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

See also:

• [Configure Regex Naming Pattern](https://www.mongodb.com/docs/search/about/view-support.md#std-label-fts-regex-naming-pattern-index

When you use dynamic mappings to index your data:

• MongoDB Search also dynamically indexes all nested fields supported by the typeSet in a document object in your data.

• If a field contains polymorphic data, MongoDB Search automatically indexes the field as all of the types supported by the typeSet used in the index. If a field contains data of a type not supported by the typeSet, MongoDB Search doesn't index that data.

Enable Default typeSet

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

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

{
  "mappings": {
    "dynamic": true
  }
}

For index examples that demonstrate indexing all fields using the default typeSet, see [Dynamic Mapping Examples.](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-fts-dynamic-mapping-examples

Configure a typeSet

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

A typeSet has the following syntax:

Note:

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

{
  "mappings": {
    "dynamic": {
      "typeSet": "<typeset-name>"
    },
    "fields": {
      "<field-name>": {
        "type": "<field-type>",
        ...
      },
      ...
    }
  },
  "typeSets": [
    {
      "name": "<typeset-name>",
      "types": [
        {
          "type": "<field-type>"
        },
        ...
      ]
    },
    ...
  ]
}

Before configuring a typeSet, consider the following:

• You cannot define the same field type multiple times in the same typeSet object. You can configure only one typeSet definition for each field type.

For example, you can't define multiple configurations for the number type in the same typeSet definition.

• You can configure dynamic mappings with the multi analyzer.

For index examples that demonstrate using custom typeSet configuration, see [Dynamic Mapping Examples.](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-fts-dynamic-mapping-examples

Static Mappings

Use static mappings to configure index options for fields that you don't want indexed dynamically, or to configure a single field independently from others in an index. When you use static mappings, MongoDB Search indexes only the fields that you specify in mappings.fields. You can also use static mappings to exclude fields from being indexed.

To use static mappings to configure index options for only some fields, set mappings.dynamic to false and specify the field name, [data type](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-bson-data-chart, and other configuration options for each field that you want to index. You can specify the fields in any order.

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

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

To define the index for a nested field, you must define the mappings for each parent field of that nested field. You can't use dot notation to statically index nested fields. For examples, see the [Examples](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-index-config-example or [Combined Mapping Example](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-fts-combined-mapping-example below.

You can use static mappings to index fields as multiple types. To index a field as multiple types, define the types in the field definition array for the field. You can index any field as any supported types using static mappings. To learn more, see [MongoDB Search Field Types.](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-bson-data-types

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

{
  "mappings": {
    "dynamic": true|false | {
      "typeSet": "<type-set-name>"
    },
    "fields": {
      "<field-name>": [
        {
          "type": "<field-type>",
          ...
        },
        {
          "type": "<field-type>",
          ...
        },
        ...
      ],
      ...
    }
  }.
  "typeSets": [
    {
      "name": "<typeset-name>",
      "types": [
        {
          "type": "<field-type>"
        },
        ...
      ]
    },
    ...
  ]
}

For other index examples that demonstrate static mappings, see [Static Mapping Example.](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-fts-static-mapping-examples

MongoDB Search Field Types

MongoDB Search doesn't support the following [BSON data types:](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-bson-types

• Decimal128

• JavaScript code with scope

• Max key

• Min key

• Regular Expression

• Timestamp

MongoDB Search automatically stores fields of type [string](https://www.mongodb.com/docs/search/indexes/field-types/string-type.md#std-label-bson-data-types-string on mongot. You can store fields of all supported [data types](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-bson-data-chart on MongoDB Search using the [Define Stored Source Fields in Your MongoDB Search Index](https://www.mongodb.com/docs/search/indexes/stored-source-definition.md#std-label-fts-stored-source-definition option in your index definition. To learn more about mongot and MongoDB Search node architecture, see [MongoDB Search Deployment Options.](https://www.mongodb.com/docs/search/deployment/deployment-options.md#std-label-fts-deployment-options

The following table enumerates the supported [BSON data types](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-bson-types and the [MongoDB Search field types](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-bson-data-types that you can use to index the BSON (Binary Javascript Object Notation) data types. The table also lists the [operators and collectors](https://www.mongodb.com/docs/search/query/operators-collectors/overview.md#std-label-operators-ref that you can use to query the field values.

These operators do not support an array of strings.

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

Deprecated. To learn more about the deprecated facet field types and their updated counterparts, see [Comparing Field Types for Facet.](https://www.mongodb.com/docs/search/query/operators-collectors/facet.md#std-label-fts-facet-type-differences

Array of double or int values.

Note:

You can store fields of all supported [data types](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-bson-data-chart on MongoDB Search using the storedSource [option.](https://www.mongodb.com/docs/search/indexes/index-definitions.md#std-label-index-definition-options

Examples

The following sample index definitions on the [sample_mflix.movies](https://www.mongodb.com/docs/manual/sample-data/sample-mflix.md#std-label-mflix-movies collection demonstrate how to index fields using dynamic and static mappings. You can [load the sample data](https://www.mongodb.com/docs/atlas/import/load-sample-data.md#std-label-load-sample-data on your cluster to try the examples. To learn more about how to create MongoDB Search indexes, see [MongoDB Search Quick Start.](https://www.mongodb.com/docs/search/tutorial.md#std-label-create-fts-index

Dynamic Mapping Examples

The following sample index definitions demonstrate how to use dynamic mappings.

Simple Index

Enable dynamic mappings to automatically index string field types.

The following index definition:

• Enables dynamic mappings at the root level to automatically index fields in the collection based on the typeSet definition named only_strings, which indexes string fields in the collection with the positions index option and with store set to false. These configuration options save disk space by not storing the field values or term offsets for query highlighting.

{
  "mappings": {
    "dynamic": {
      "typeSet": "only_strings"
    }
  },
  "typeSets": [
    {
      "name": "only_strings",
      "types": [
        {
          "type": "string",
          "store": false,
          "indexOptions": "positions"
        }
      ]
    }
  ]
}

Dynamically Index a Nested Document

Enable dynamic mappings within a document-type field to automatically index nested fields.

The following index definition:

• Enables dynamic mappings at the root level to dynamically index fields in the collection based on the typeSet named only_strings, which indexes string fields in the collection with the positions index option and with store set to false, which saves disk space by not storing the field values or term offsets for query highlighting.

• Indexes the awards field as the document type and uses the dynamic option with the only_numbers typeSet to dynamically index only the numeric sub-fields in the awards document. This means that the numeric sub-fields wins and nominations are indexed, but the string sub-field text is not indexed.

{
  "mappings": {
    "dynamic": {
      "typeSet": "only_strings"
    },
    "fields": {
      "awards": {
        "type": "document",
        "dynamic": {
          "typeSet": "only_numbers"
        }
      }
    }
  },
  "typeSets": [
    {
      "name": "only_numbers",
      "types": [
        {
          "type": "number"
        }
      ]
    },
    {
      "name": "only_strings",
      "types": [
        {
          "type": "string",
          "store": false,
          "indexOptions": "positions"
        }
      ]
    }
  ]
}

Exclude Fields from Index

Dynamically map specific field types except for specified fields.

The following index definition:

• Configures dynamic mappings for specific field types using the typeSet named indexedTypes, which specifies the following behavior:

• Automatically index string fields as the token type.

• Automatically index numeric fields as the number type.

• Excludes the plot field from being indexed.

{
  "mappings": {
    "dynamic": {
      "typeSet": "indexedTypes"
    },
    "fields": {
      "plot": []
    }
  },
  "typeSets": [
    {
      "name": "indexedTypes",
      "types": [
        {
          "type": "token"
        },
        {
          "type": "number"
        }
      ]
    }
  ]
}

Static Mapping Example

The following sample index definitions demonstrate how to use static mappings.

Simple Index

Disable dynamic mappings and define individual fields for indexing.

The following index definition:

• Specifies static field mappings at the root level (dynamic: false), which means that fields that are not specified in mappings.fields are not indexed. The index definition explicitly includes the following fields for indexing:

• The awards field, which is of type document. It has three embedded sub-fields, wins, nominations and text.

  The wins and nominations sub-fields contain numeric data and are indexed as the type number. nominations is indexed with the int64 representation, which allows it to support larger integer values than the default number type.

  The text sub-field contains string data and is indexed as the string type using the [lucene.english](https://www.mongodb.com/docs/search/indexes/analyzers/language.md#std-label-ref-language-analyzers analyzer, which is optimized for English text. The text field also uses the ignoreAbove option to ignore any string of more than 255 characters in length.

• The title field, which contains string data and is indexed as type string using the [lucene.whitespace](https://www.mongodb.com/docs/search/indexes/analyzers/whitespace.md#std-label-ref-whitespace-analyzer analyzer, which is optimized for text that contains a lot of whitespace, such as product names or titles. The title field uses the [multi](https://www.mongodb.com/docs/search/indexes/analyzers/multi.md#std-label-ref-multi-analyzers option to specify the [lucene.french](https://www.mongodb.com/docs/search/indexes/analyzers/language.md#std-label-ref-language-analyzers analyzer as a secondary analyzer. This allows you to specify { “value”: “title”, “multi”: “frenchAnalyzer” } as the path in your [$search](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search queries to better target French query terms.

• The genres field, which contains an array of strings and is indexed as the type string. MongoDB Search indexes the array elements using the [lucene.standard](https://www.mongodb.com/docs/search/indexes/analyzers/standard.md#std-label-ref-standard-analyzer analyzer by default. For indexing arrays, MongoDB Search only requires the data type of the array elements. You don't have to specify that the data is contained in an array in the index definition.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "awards": {
        "type": "document",
        "fields": {
          "wins": {
            "type": "number"
          },
          "nominations": {
            "type": "number",
            "representation": "int64"
          },
          "text": {
            "type": "string",
            "analyzer": "lucene.english",
            "ignoreAbove": 255
          }
        }
      },
      "title": {
        "type": "string",
        "analyzer": "lucene.whitespace",
        "multi": {
          "frenchAnalyzer": {
            "type": "string",
            "analyzer": "lucene.french"
          }
        }
      },
      "genres": {
        "type": "string"
      }
    }
  }
}

Combined Mapping Example

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

Simple Index

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

This index definition:

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

• The title field, which contains string data and is indexed as the string type using the [lucene.whitespace](https://www.mongodb.com/docs/search/indexes/analyzers/whitespace.md#std-label-ref-whitespace-analyzer analyzer, which is optimized for text that contains a lot of whitespace, such as product names or titles.

• The awards field, which is of type document and contains three sub-fields. The wins and nominations sub-fields contain numeric data, and the text sub-field contains string data. Instead of explicitly setting the data type for each nested field in the document, the index definition enables dynamic mapping for all the sub-fields in the document. This indexes wins and nominations as the number type, and text as the string type. Data in the text field is indexed using the [lucene.standard](https://www.mongodb.com/docs/search/indexes/analyzers/standard.md#std-label-ref-standard-analyzer analyzer by default.

json { "mappings": { "dynamic": false, "fields": { "title": { "type": "string", "analyzer": "lucene.whitespace" }, "awards": { "type": "document", "dynamic": true } } } }

Complex Index

Set static mappings at the root level, and dynamically map a nested field using a custom typeSet definition.

This index definition:

• Specifies static field mappings at the root level (dynamic: false), which means that fields that aren't specified in the mappings.fields option aren't indexed.

• Defines dynamic mappings for the awards field, which is of type document, using the custom typeSet named movieAwards. The awards field has three embedded sub-fields: wins, nominations, and text. Instead of automatically indexing the sub-fields by setting dynamic to true at the root level or by explicitly indexing each nested field using static mappings, the index definition configures dynamic mappings for the document field type using the typeSet definition named movieAwards. The movieAwards typeSet does the following:

• Indexes string fields as the string type using the [multi](https://www.mongodb.com/docs/search/indexes/analyzers/multi.md#std-label-ref-multi-analyzers option to specify multiple analyzers: lucene.english and lucene.french.

• Indexes numeric fields as type number using the default settings for the number type.

  json { "mappings": { "dynamic": false, "fields": { "awards": { "type": "document", "dynamic": { "typeSet": "movieAwards" } } } }, "typeSets": [ { "name": "movieAwards", "types": [ { "type": "string", "multi": { "english": { "type": "string", "analyzer": "lucene.english" }, "french": { "type": "string", "analyzer": "lucene.french" } } }, { "type": "number" } ] } ] }