Navigation
This version of the documentation is archived and no longer supported.

db.collection.createIndexes()

Definition

db.collection.createIndexes([keyPatterns, ]options)

New in version 3.2.

Creates one or more indexes on a collection.

Parameter Type Description
keyPatterns document

An array containing index specification documents. Each document contains field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of 1; for descending index, specify a value of -1.

MongoDB supports several different index types including text, geospatial, and hashed indexes. See index types for more information.

options document Optional. A document that contains a set of options that controls the creation of the indexes. See Options for details.

Options

The options document contains a set of options that control the creation of the indexes. Different index types can have additional options specific for that type.

Important

When you specify options to db.collection.createIndexes(), the options apply to all of the specified indexes.

db.collection.createIndexes() will return an error if you attempt to create indexes with incompatible options. Refer to the options descriptions for more information.

Options for All Index Types

The following options are available for all index types unless otherwise specified:

Changed in version 3.0: The dropDups option is no longer available.

Parameter Type Description
background boolean Optional. Builds the indexes in the background so the operation does not block other database activities. Specify true to build in the background. The default value is false.
unique boolean

Optional. Specifies that each index specified in the keyPatterns array is a unique index. Unique indexes will not accept insertion or update of documents where the index key value matches an existing value in the index.

Specify true to create a unique index. The default value is false.

The option is unavailable for hashed indexes.

name string

Optional. The name of the index. If unspecified, MongoDB generates an index name by concatenating the names of the indexed fields and the sort order.

Whether user specified or MongoDB generated, index names including their full namespace (i.e. database.collection) cannot be longer than the Index Name Limit.

Options specified to db.collection.createIndexes apply to all of the index specifications included in the key pattern array. Since index names must be unique, you may only specify name if you are creating a single index using db.collection.createIndexes.

partialFilterExpression document

Optional. If specified, the indexes only reference documents that match the filter expression. See Partial Indexes for more information.

A filter expression can include:

You can specify a partialFilterExpression option for all MongoDB index types.

New in version 3.2.

sparse boolean

Optional. If true, the indexes only reference documents with the specified fields. These indexes use less space but behave differently in some situations (particularly sorts). The default value is false. See Sparse Indexes for more information.

Changed in version 3.2: Starting in MongoDB 3.2, MongoDB provides the option to create partial indexes. Partial indexes offer a superset of the functionality of sparse indexes. If you are using MongoDB 3.2 or later, partial indexes should be preferred over sparse indexes.

Changed in version 2.6: 2dsphere indexes are sparse by default and ignore this option. For a compound index that includes 2dsphere index key(s) along with keys of other types, only the 2dsphere index fields determine whether the index references a document.

2d, geoHaystack, and text indexes behave similarly to the 2dsphere indexes.

expireAfterSeconds integer Optional. Specifies a value, in seconds, as a TTL to control how long MongoDB retains documents in this collection. See Expire Data from Collections by Setting TTL for more information on this functionality. This applies only to TTL indexes.
storageEngine document

Optional. Allows users to configure the storage engine for the created indexes.

The storageEngine option should take the following form:

storageEngine: { <storage-engine-name>: <options> }

Storage engine configuration options specified when creating indexes are validated and logged to the oplog during replication to support replica sets with members that use different storage engines.

New in version 3.0.

Options for text Indexes

The following options are available for text indexes only:

Parameter Type Description
weights document Optional. For text indexes, a document that contains field and weight pairs. The weight is an integer ranging from 1 to 99,999 and denotes the significance of the field relative to the other indexed fields in terms of the score. You can specify weights for some or all the indexed fields. See Control Search Results with Weights to adjust the scores. The default value is 1.
default_language string Optional. For text indexes, the language that determines the list of stop words and the rules for the stemmer and tokenizer. See Text Search Languages for the available languages and Specify a Language for Text Index for more information and examples. The default value is english.
language_override string Optional. For text indexes, the name of the field, in the collection’s documents, that contains the override language for the document. The default value is language. See Use any Field to Specify the Language for a Document for an example.
textIndexVersion integer

Optional. The text index version number. Users can use this option to override the default version number.

For available versions, see Versions.

New in version 2.6.

Options for 2dsphere Indexes

The following option is available for 2dsphere indexes only:

Parameter Type Description
2dsphereIndexVersion integer

Optional. The 2dsphere index version number. Users can use this option to override the default version number.

For the available versions, see Versions.

New in version 2.6.

Options for 2d Indexes

The following options are available for 2d indexes only:

Parameter Type Description
bits integer

Optional. For 2d indexes, the number of precision of the stored geohash value of the location data.

The bits value ranges from 1 to 32 inclusive. The default value is 26.

min number Optional. For 2d indexes, the lower inclusive boundary for the longitude and latitude values. The default value is -180.0.
max number Optional. For 2d indexes, the upper inclusive boundary for the longitude and latitude values. The default value is 180.0.

Options for geoHaystack Indexes

The following option is available for geoHaystack indexes only:

Parameter Type Description
bucketSize number

For geoHaystack indexes, specify the number of units within which to group the location values; i.e. group in the same bucket those location values that are within the specified number of units to each other.

The value must be greater than 0.

Behaviors

The createIndexes() method has the following behaviors.

Warning

Foreground index builds block all other operations on the database.

  • To add or change index options, you must drop the index using the dropIndex() method and issue another db.collection.createIndexes() operation with the new options.
  • If you create an index with one set of options, and then issue the db.collection.createIndexes() method with the same index fields and different options without first dropping the index, db.collection.createIndexes() will not rebuild the existing index with the new options.
  • If you call db.collection.createIndexes() multiple times concurrently with the same index specification, only the first operation will succeed. All other operations will have no effect.
  • MongoDB will not create an index on a collection if the index entry for an existing document exceeds the Maximum Index Key Length. Previous versions of MongoDB would create the index but not index such documents.

Example

See also

db.collection.createIndex() for examples of various index specifications.

Create Indexes Without Options

Consider a restaurants collection containing documents that resemble the following:

{
   location: {
      type: "Point",
      coordinates: [-73.856077, 40.848447]
   },
   name: "Morris Park Bake Shop",
   cuisine: "Cafe",
   borough: "Bronx",
}

The following example creates two indexes on the restaurants collection: an ascending index on the borough field and a 2dsphere index on the location field.

db.restaurants.createIndexes([{"borough": 1}, {"location": "2dsphere"}])

Additional Information

For additional information about indexes, refer to: