Define Field Mappings

Dynamic Mappings

Use dynamic mapping to automatically index all fields of supported types in your collection. We recommend using dynamic mappings only if your schema changes regularly or is unknown, or if you're experimenting with Atlas Search. Dynamically mapped indexes occupy more disk space than statically mapped indexes and may be less performant.

When you dynamically index a field that contains polymorphic data, Atlas Search automatically indexes the field as all of the dynamically indexable field types that correspond to the data. If the field contains data of a type that Atlas Search doesn't index automatically, Atlas Search won't index that data.

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

To learn which data types support dynamic indexing, see the Data Types section below.

Static Mappings

Use static mapping 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 mapping, Atlas Search indexes only the fields that you specify in mappings.fields.

When you statically index a field containing polymorphic data, Atlas Search only indexes documents that correspond to the mapping specified in the index definition for that field. Atlas Search doesn't index documents that don't match the data type specified in the index definition for that field.

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 the dot notation to statically index nested fields. For examples, see the Examples or Combined Mapping Example below.

Index Field as Multiple Data Types

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

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
}

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.

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

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