Navigation

Index Definitions

When you configure an Atlas Search index, you can specify that certain fields should be indexed with a particular analyzer or with multiple analyzers. You can also specify that certain fields should be indexed while others are left unindexed, or you can dynamically index all the fields in a collection.

Static and Dynamic Mappings

Individual field mappings that you configure when you create the index are called static mappings.

Mappings that are automatically assigned when new data is inserted into a field are called dynamic mappings. Dynamic mappings are useful if you have a dynamic schema and you don’t know ahead of time all the fields that a collection may contain. You can configure an entire index to use dynamic mappings, or specify individual fields to be dynamically mapped.

Note

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

See the index configuration example.

Defining an Index

When you create a new Atlas Search index, you have the opportunity to specify a custom definition for the index. See Create an Atlas Search Index for complete instructions on creating a new Atlas Search index.

Screenshot of Create an Atlas Search Index modal window

The index name defaults to default. You can leave the default name in place or choose one of your own.

Note

If you name your index default, you don’t need to specify an index parameter when using the $searchBeta pipeline stage. Otherwise, you must specify the index name using the index parameter.

Index names must be unique within their namespace.

The default index definition will work with any collection. If you wish to create a custom index definition, you can specify which fields should be indexed with which analyzer and as which data type.

Static Mapping Example

The following example index definition file uses static mappings.

  • The default index analyzer is lucene.standard.

  • The default search analyzer is lucene.standard.

  • The index specifies static field mappings (dynamic: false).

  • The field address 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 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.

    For more information on multi analyzers, see Path construction.

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

BSON Data Types

string

The string data type takes the following parameters:

Option Purpose Default
analyzer: <string> Name of a built-in or overridden analyzer to use for indexing the field. standard
searchAnalyzer: <string> Analyzer to use when querying the field. standard
fields: Mapping from subfield name to a string-type field definition. Empty
ignoreAbove: <int> Do not index if the field value is greater than the specified number of characters. None

document

The document data type is for fields with embedded documents. It takes a fields object, with one or more field definitions.

date

The date type is for indexing date values. A date cannot be indexed if it is part of an array. It takes the type option. The value of type must be date.

number

The number type is for fields with numeric values of int32, int64, and double data types. The number type has the following options:

Option Purpose Default
type The type of field. Value must be number.  
representation

The data type of the field to index. Valid values are:

  • int64 - for indexing large integers without loss of precision and for rounding double values to integers. This cannot be used to index large double values.
  • double - for indexing large double values without rounding.

Example

The following index definition for the sample_training.tweets collection in the sample dataset indexes the id field with 64 bit integer values. The following example also indexes all other integer and small double type values in the id field after rounding any decimal values in the double type before indexing.

{
   "mappings": {
       "dynamic": false,
       "fields": {
          "id": {
             "type": "number",
             "representation": "int64"
          }
       }
   }
}
double
indexIntegers

Index or omit int32 and int64 type values. Value can be true or false.

Example

The following index definition for the sample_airbnb.listingsAndReviews collection in the sample dataset omits the bathrooms field with 32 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
         }
      }
   }
}
true
indexDoubles

Index or omit double type values. Value can be true or false.

Example

The following index definition for the sample_training.tweets collection in the sample dataset:

  • Indexes the id field with integer values.
  • Omits the id field with doubles values.
{
   "mappings": {
      "dynamic": false,
      "fields": {
         "id": {
            "type": "number",
            "representation": "int64",
            "indexDoubles": false
         }
      }
   }
}
true