db.collection.createIndexes()

Definition

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

mongo Shell Method

This page documents the mongo shell method, and doesnot refer to the MongoDB Node.js driver (or any other driver)method. For corresponding MongoDB driver API, refer to your specificMongoDB driver documentation instead.

New in version 3.2.

Creates one or more indexes on a collection.

ParameterTypeDescriptionkeyPatternsdocumentAn array containing index specification documents. Each documentcontains field and value pairs where the field isthe index key and the value describes the type of index for thatfield. For an ascending index on a field, specify a value of 1; fordescending index, specify a value of -1.

MongoDB supports several different index types includingtext, geospatial, and hashed indexes. See index typesfor more information.

Changed in version 4.2: MongoDB 4.2 wildcard indexessupport workloads where users query against custom fields or alarge variety of fields in a collection:

• To create a wildcard index on all fields and subfields in adocument, specify { "$**" : 1 } as the index key. Youcannot specify a descending index key when creating a wildcardindex.

You can also either include or exclude specific fields andtheir subfields from the index using the optionalwildcardProjection parameter.

Wildcard indexes omit the _id field by default. To include the_id field in the wildcard index, you must explicitly include itin the wildcardProjection document (i.e. { "_id" : 1 }).

• You can create a wildcard index on a specific fieldand its subpaths by specifying the full path to that field as theindex key and append "$**" to the path:

{ "path.to.field.$**" : 1 }

You cannot specify a descending index key when creating awildcard index.

The path-specific wildcard index syntax is incompatible with thewildcardProjection option. You cannot specify additionalinclusions or exclusions on the specified path.

The wildcard index key must use one of the syntaxes listedabove. For example, you cannot specify acompound index key. For morecomplete documentation on wildcard indexes, including restrictionson their creation, see Wildcard Index Restrictions.

The mongodfeatureCompatibilityVersion must be 4.2 tocreate wildcard indexes. For instructions on setting the fCV, seeSet Feature Compatibility Version on MongoDB 4.2 Deployments.

For more information on creating wildcard indexes, seeWildcard Indexes.optionsdocumentOptional. A document that contains a set of options that controls the creationof the indexes. See Options for details.

The db.collection.createIndexes() is a wrapper around thecreateIndexes command.

To minimize the impact of building an index on replica sets and shardedclusters, use a rolling index build procedureas described on Build Indexes on Replica Sets.

Options

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

Important

When you specify options todb.collection.createIndexes(), the options apply toall of the specified indexes. For example, if you specify acollation option, all of the created indexes will include thatcollation.

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

Changed in version 3.4: Added support for collation.

Options for All Index Types

The following options are available for all index types unlessotherwise specified:

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

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

Option for Collation

collation: {   locale: <string>,   caseLevel: <boolean>,   caseFirst: <string>,   strength: <int>,   numericOrdering: <boolean>,   alternate: <string>,   maxVariable: <string>,   backwards: <boolean>}

The following indexes only support simple binary comparison and donot support collation:

• text indexes,
• 2d indexes, and
• geoHaystack indexes.

Tip

To create a text, a 2d, or a geoHaystack index on acollection that has a non-simple collation, you must explicitlyspecify {collation: {locale: "simple"} } when creating theindex.

Collation and Index Use

If you have specified a collation at the collection level, then:

• If you do not specify a collation when creating the index, MongoDBcreates the index with the collection’s default collation.
• If you do specify a collation when creating the index, MongoDBcreates the index with the specified collation.

Tip

By specifying a collation strength of 1 or 2, you cancreate a case-insensitive index. Index with a collation strengthof 1 is both diacritic- and case-insensitive.

Unlike other index options, you can create multiple indexes on the samekey(s) with different collations. To create indexes with the same keypattern but different collations, you must supply unique index names.

To use an index for string comparisons, an operation must alsospecify the same collation. That is, an index with a collationcannot support an operation that performs string comparisons on theindexed fields if the operation specifies a different collation.

For example, the collection myColl has an index on a stringfield category with the collation locale "fr".

db.myColl.createIndex( { category: 1 }, { collation: { locale: "fr" } } )

The following query operation, which specifies the same collation asthe index, can use the index:

db.myColl.find( { category: "cafe" } ).collation( { locale: "fr" } )

However, the following query operation, which by default uses the“simple” binary collator, cannot use the index:

db.myColl.find( { category: "cafe" } )

For a compound index where the index prefix keys are not strings,arrays, and embedded documents, an operation that specifies adifferent collation can still use the index to support comparisonson the index prefix keys.

For example, the collection myColl has a compound index on thenumeric fields score and price and the string fieldcategory; the index is created with the collation locale"fr" for string comparisons:

db.myColl.createIndex(
   { score: 1, price: 1, category: 1 },
   { collation: { locale: "fr" } } )

The following operations, which use "simple" binary collationfor string comparisons, can use the index:

db.myColl.find( { score: 5 } ).sort( { price: 1 } )
db.myColl.find( { score: 5, price: { $gt: NumberDecimal( "10" ) } } ).sort( { price: 1 } )

The following operation, which uses "simple" binary collationfor string comparisons on the indexed category field, can usethe index to fulfill only the score: 5 portion of the query:

db.myColl.find( { score: 5, category: "cafe" } )

Options for text Indexes

The following options are available for textindexes only:

Options for 2dsphere Indexes

The following option is available for 2dsphereindexes only:

Options for 2d Indexes

The following options are available for 2d indexesonly:

Options for geoHaystack Indexes

The following option is available for geoHaystackindexes only:

Options for wildcard indexes

The following option is available forwildcard indexes only:

wildcardProjection: {  "path.to.field.a" : <value>,  "path.to.field.b" : <value>}

Behaviors

Concurrency

Changed in version 4.2.

For featureCompatibilityVersion "4.2", db.collection.createIndexes()uses an optimized build process that obtains and holds an exclusive lock onthe specified collection at the start and end of the index build. Allsubsequent operations on the collection must wait until db.collection.createIndexes() releasesthe exclusive lock. db.collection.createIndexes() allows interleaving read and writeoperations during the majority of the index build.

For featureCompatibilityVersion "4.0", db.collection.createIndexes()uses the pre-4.2 index build process which by default obtains an exclusivelock on the parent database for the entire duration of the build process. Thepre-4.2 build process blocks all operations on the database and all itscollections until the operation completed. background indexes do not takean exclusive lock.

For more information on the locking behavior of db.collection.createIndexes(), seeIndex Builds on Populated Collections.

Recreating an Existing Index

If you call db.collection.createIndexes() for an index orindexes that already exist, MongoDB does not recreate the existingindex or indexes.

Index Options

Non-Collation Options

With the exception of the collation option, if you create an index with one setof index options and then try to recreate the same index but withdifferent index options, MongoDB will not change the options norrecreate the index.

To change these index options, drop the existing index withdb.collection.dropIndex() before runningdb.collection.createIndexes() with the new options.

Collation Option

Unlike other index options, you can create multiple indexes on the samekey(s) with different collations. To create indexes with the same keypattern but different collations, you must supply unique index names.

Index Key Length Limit

For MongoDB 2.6 through MongoDB versions withfeatureCompatibilityVersion (fCV) set to "4.0" orearlier, MongoDB will not create an index on a collection if theindex entry for an existing document exceeds the Maximum Index Key Length.

Wildcard Indexes

New in version 4.2.

• Wildcard indexes omit the _id field by default. To include the_id field in the wildcard index, you must explicitly include itin the wildcardProjection document (i.e. { "_id" : 1 }).

• The mongodfeatureCompatibilityVersion must be 4.2 tocreate wildcard indexes. For instructions on setting the fCV, seeSet Feature Compatibility Version on MongoDB 4.2 Deployments.

• Wildcard indexes do not support the following index types orproperties:

  • Compound
  • TTL
  • Text
  • 2d (Geospatial)
  • 2dsphere (Geospatial)
  • Hashed
  • Unique

Note

Wildcard Indexes are distinct from and incompatible withWildcard Text Indexes. Wildcard indexes cannot supportqueries using the $text operator.

For complete documentation on wildcard index restrictions, seeWildcard Index Restrictions.

For examples of wildcard index creation, seeCreate a Wildcard Index. For completedocumentation on Wildcard Indexes, see Wildcard Indexes.

Example

See also

db.collection.createIndex() for examples ofvarious index specifications.

Create Indexes Without Options

Consider a restaurants collection containing documents thatresemble 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 restaurantscollection: an ascending index on the borough field and a2dsphere index on the location field.

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

Create Indexes with Collation Specified

The following example creates two indexes on the productscollection: an ascending index on the manufacturer field and anascending index on the category field. Both indexes use a collation that specifies the locale fr andcomparison strength 2:

db.products.createIndexes( [ { "manufacturer": 1}, { "category": 1 } ],
   { collation: { locale: "fr", strength: 2 } })

For queries or sort operations on the indexed keys that uses the same collationrules, MongoDB can use the index. For details, see Collation and Index Use.

Create a Wildcard Index

New in version 4.2: The mongodfeatureCompatibilityVersion must be 4.2 tocreate wildcard indexes. For instructions on setting the fCV, seeSet Feature Compatibility Version on MongoDB 4.2 Deployments.

For complete documentation on Wildcard Indexes, seeWildcard Indexes.

The following lists examples of wildcard index creation:

• Create a Wildcard Index on a Single Field Path
• Create a Wildcard Index on All Field Paths
• Create a Wildcard Index on Multiple Specific Field Paths
• Create a Wildcard Index that Excludes Multiple Specific Field Paths

Create a Wildcard Index on a Single Field Path

Consider a collection products_catalog where documents may contain aproduct_attributes field. The product_attributes field cancontain arbitrary nested fields, including embeddeddocuments and arrays:

{
  "_id" : ObjectId("5c1d358bf383fbee028aea0b"),
  "product_name" : "Blaster Gauntlet",
  "product_attributes" : {
     "price" : {
       "cost" : 299.99
       "currency" : USD
     }
     ...
  }
},
{
  "_id" : ObjectId("5c1d358bf383fbee028aea0c"),
  "product_name" : "Super Suit",
  "product_attributes" : {
     "superFlight" : true,
     "resistance" : [ "Bludgeoning", "Piercing", "Slashing" ]
     ...
  },
}

The following operation creates a wildcard index on theproduct_attributes field:

use inventory
db.products_catalog.createIndexes(
  [ { "product_attributes.$**" : 1 } ]
)

With this wildcard index, MongoDB indexes all scalar values ofproduct_attributes. If the field is a nested document or array, thewildcard index recurses into the document/array and indexes all scalarfields in the document/array.

The wildcard index can support arbitrary single-field queries onproduct_attributes or one of its nested fields:

db.products_catalog.find( { "product_attributes.superFlight" : true } )
db.products_catalog.find( { "product_attributes.maxSpeed" : { $gt : 20 } } )
db.products_catalog.find( { "product_attributes.elements" : { $eq: "water" } } )

Create a Wildcard Index on All Field Paths

Consider a collection products_catalog where documents may contain aproduct_attributes field. The product_attributes field cancontain arbitrary nested fields, including embeddeddocuments and arrays:

{
  "_id" : ObjectId("5c1d358bf383fbee028aea0b"),
  "product_name" : "Blaster Gauntlet",
  "product_attributes" : {
     "price" : {
       "cost" : 299.99
       "currency" : USD
     }
     ...
  }
},
{
  "_id" : ObjectId("5c1d358bf383fbee028aea0c"),
  "product_name" : "Super Suit",
  "product_attributes" : {
     "superFlight" : true,
     "resistance" : [ "Bludgeoning", "Piercing", "Slashing" ]
     ...
  },
}

The following operation creates a wildcard index on all scalar fields(excluding the _id field):

use inventory
db.products_catalog.createIndexes(
  [ { "$**" : 1 } ]
)

With this wildcard index, MongoDB indexes all scalar fields for eachdocument in the collection. If a given field is a nested document orarray, the wildcard index recurses into the document/array and indexesall scalar fields in the document/array.

The created index can support queries on any arbitrary fieldwithin documents in the collection:

db.products_catalog.find( { "product_price" : { $lt : 25 } } )
db.products_catalog.find( { "product_attributes.elements" : { $eq: "water" } } )

Wildcard indexes omit the _id field by default. To include the_id field in the wildcard index, you must explicitly include itin the wildcardProjection document (i.e. { "_id" : 1 }).

Create a Wildcard Index on Multiple Specific Field Paths

Consider a collection products_catalog where documents may contain aproduct_attributes field. The product_attributes field cancontain arbitrary nested fields, including embeddeddocuments and arrays:

{
  "_id" : ObjectId("5c1d358bf383fbee028aea0b"),
  "product_name" : "Blaster Gauntlet",
  "product_attributes" : {
     "price" : {
       "cost" : 299.99
       "currency" : USD
     }
     ...
  }
},
{
  "_id" : ObjectId("5c1d358bf383fbee028aea0c"),
  "product_name" : "Super Suit",
  "product_attributes" : {
     "superFlight" : true,
     "resistance" : [ "Bludgeoning", "Piercing", "Slashing" ]
     ...
  },
}

The following operation creates a wildcard index and usesthe wildcardProjection option to include only scalar values of theproduct_attributes.elements and product_attributes.resistancefields in the index.

use inventory
db.products_catalog.createIndexes(
  [ { "$**" : 1 } ],
  {
    "wildcardProjection" : {
      "product_attributes.elements" : 1,
      "product_attributes.resistance" : 1
    }
  }
)

While the key pattern "$**" covers all fields in the document, thewildcardProjection field limits the index to only the includedfields. For complete documentation on wildcardProjection, seeOptions for wildcard indexes.

If a field is a nested document or array, the wildcardindex recurses into the document/array and indexes all scalar fields inthe document/array.

The created index can support queries on any scalar fieldincluded in the wildcardProjection:

db.products_catalog.find( { "product_attributes.elements" : { $eq: "Water" } } )
db.products_catalog.find( { "product_attributes.resistance" : "Bludgeoning" } )

Wildcard indexes omit the _id field by default. To include the_id field in the wildcard index, you must explicitly include itin the wildcardProjection document (i.e. { "_id" : 1 }).

Create a Wildcard Index that Excludes Multiple Specific Field Paths

Consider a collection products_catalog where documents may contain aproduct_attributes field. The product_attributes field cancontain arbitrary nested fields, including embeddeddocuments and arrays:

{
  "_id" : ObjectId("5c1d358bf383fbee028aea0b"),
  "product_name" : "Blaster Gauntlet",
  "product_attributes" : {
     "price" : {
       "cost" : 299.99
       "currency" : USD
     }
     ...
  }
},
{
  "_id" : ObjectId("5c1d358bf383fbee028aea0c"),
  "product_name" : "Super Suit",
  "product_attributes" : {
     "superFlight" : true,
     "resistance" : [ "Bludgeoning", "Piercing", "Slashing" ]
     ...
  },
}

The following operation creates a wildcard index and usesthe wildcardProjection document to index all scalar fieldsfor each document in the collection, excluding theproduct_attributes.elements and product_attributes.resistancefields:

use inventory
db.products_catalog.createIndexes(
  [ { "$**" : 1 } ],
  {
    "wildcardProjection" : {
      "product_attributes.elements" : 0,
      "product_attributes.resistance" : 0
    }
  }
)

While the key pattern "$**" covers all fields in the document, thewildcardProjection field excludes the specified fields from theindex. For complete documentation on wildcardProjection, seeOptions for wildcard indexes.

If a field is a nested document or array, the wildcardindex recurses into the document/array and indexes all scalar fields inthe document/array.

The created index can support queries on any scalar field exceptthose excluded by wildcardProjection:

db.products_catalog.find( { "product_attributes.maxSpeed" : { $gt: 25 } } )
db.products_catalog.find( { "product_attributes.superStrength" : true } )

As MongoDB includes an index on _id by default, wildcardindexes omit the _id field. To include the _id field in thewildcard index, you must explicitly include it in thewildcardProjection document:

"wildcardProjection" : {
  "_id" : 1
}

The _id field is the only field you can specify along withfield exclusions.

Additional Information

For additional information about indexes, refer to:

• The Indexes section of this manual for fulldocumentation of indexes and indexing in MongoDB.
• db.collection.getIndexes() to view the specifications ofexisting indexes for a collection.
• Text Indexes for details on creating textindexes.
• Geospatial Indexes andgeoHaystack Indexes for geospatial queries.
• TTL Indexes for expiration of data.