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.

ParameterTypeDescription
backgroundbooleanOptional. Deprecated in MongoDB 4.2.-For feature compatibility version (fcv) "4.0",specifying background: true directs MongoDB to build theindex in the background. Background builds donot block operations on the collection. The default value isfalse.-Changed in version 4.2.For feature compatibility version (fcv) "4.2",all index builds use an optimizedbuild process that holds the exclusivelock only at the beginning and end of the build process. The rest ofthe build process yields to interleaving read and write operations.MongoDB ignores the background option if specified.
uniquebooleanOptional. Specifies that each index specified in the keyPatterns arrayis a unique index. Unique indexes will notaccept insertion or update of documents where the index key value matches anexisting value in the index.Specify true to create a unique index. Thedefault value is false.The option is unavailable for hashedindexes.
namestringOptional. The name of the index. If unspecified, MongoDB generates an index nameby concatenating the names of the indexed fields and the sort order.Changed in MongoDB 4.2Starting in version 4.2, for featureCompatibilityVersion set to "4.2" or greater, MongoDB removes theIndex Name Length limit of 127 byte maximum. In previousversions or MongoDB versions withfeatureCompatibilityVersion (fCV) set to"4.0", index names must fall within thelimit.Options specified to db.collection.createIndexes apply to all of the indexspecifications included in the key pattern array. Since index namesmust be unique, you mayonly specify name if you are creating a single index usingdb.collection.createIndexes.
partialFilterExpressiondocumentOptional. If specified, the indexes only reference documents that match thefilter expression. See Partial Indexes for moreinformation.A filter expression can include:- equality expressions (i.e. field: value or using the $eqoperator),- $exists: true expression,- $gt, $gte, $lt, $lte expressions,- $type expressions,- $and operator at the top-level onlyYou can specify a partialFilterExpression option for all MongoDBindex types.New in version 3.2.
sparsebooleanOptional. If true, the indexes only reference documents with the specifiedfields. These indexes use less space but behave differently in somesituations (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 createpartial indexes. Partial indexesoffer a superset of the functionality of sparse indexes. If youare 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 andignore this option. For a compound index that includes2dsphere index key(s) along with keys of other types, only the2dsphere index fields determine whether the index references adocument.2d, geoHaystack, andtext indexes behave similarly to the2dsphere indexes.
expireAfterSecondsintegerOptional. Specifies a value, in seconds, as a TTL to control how longMongoDB retains documents in this collection. SeeExpire Data from Collections by Setting TTL for more information on thisfunctionality. This applies only to TTL indexes.
storageEnginedocumentOptional. Allows users to configure the storage engine for the createdindexes.The storageEngine option should take the following form:
  1. storageEngine: { <storage-engine-name>: <options> }
Storage engine configuration options specified when creating indexes arevalidated and logged to the oplog during replication tosupport replica sets with members that use different storageengines.New in version 3.0.

Option for Collation

ParameterTypeDescription
collationdocumentOptional. Specifies the collation for the index.Collation allows users to specifylanguage-specific rules for string comparison, such as rules forlettercase and accent marks.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.The collation option has the following syntax:
  1. collation: { locale: <string>, caseLevel: <boolean>, caseFirst: <string>, strength: <int>, numericOrdering: <boolean>, alternate: <string>, maxVariable: <string>, backwards: <boolean>}
When specifying collation, the locale field is mandatory; allother collation fields are optional. For descriptions of the fields,see Collation Document.New in version 3.4.

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

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

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

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

  1. 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:

  1. 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:

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

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

  1. db.myColl.find( { score: 5 } ).sort( { price: 1 } )
  2. 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:

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

Options for text Indexes

The following options are available for textindexes only:

ParameterTypeDescription
weightsdocumentOptional. For text indexes, a document that containsfield and weight pairs. The weight is an integer ranging from 1 to99,999 and denotes the significance of the field relative to theother indexed fields in terms of the score. You can specify weightsfor some or all the indexed fields. SeeControl Search Results with Weights to adjust the scores.The default value is 1.
default_languagestringOptional. For text indexes, the language thatdetermines the list of stop words and the rules for the stemmer andtokenizer. See Text Search Languages for the availablelanguages and Specify a Language for Text Index formore information and examples. The default value is english.
language_overridestringOptional. For text indexes, the name of the field, inthe collection’s documents, that contains the override language forthe document. The default value is language. SeeUse any Field to Specify the Language for a Document for an example.
textIndexVersionintegerOptional. The text index version number. Users can use this option tooverride the default version number.For available versions, see Versions.New in version 2.6.

Options for 2dsphere Indexes

The following option is available for 2dsphereindexes only:

ParameterTypeDescription
2dsphereIndexVersionintegerOptional. The 2dsphere index version number. Users can use this option tooverride 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 indexesonly:

ParameterTypeDescription
bitsintegerOptional. For 2d indexes, the number of precision of thestored geohash value of the location data.The bits value ranges from 1 to 32 inclusive. The default valueis 26.
minnumberOptional. For 2d indexes, the lower inclusive boundary forthe longitude and latitude values. The default value is -180.0.
maxnumberOptional. For 2d indexes, the upper inclusive boundary forthe longitude and latitude values. The default value is 180.0.

Options for geoHaystack Indexes

The following option is available for geoHaystackindexes only:

ParameterTypeDescription
bucketSizenumberFor geoHaystack indexes, specify thenumber of units within which to group the location values; i.e. groupin the same bucket those location values that are within thespecified number of units to each other.The value must be greater than 0.

Options for wildcard indexes

The following option is available forwildcard indexes only:

ParameterTypeDescription
wildcardProjectiondocumentOptional. Allows users to include or exclude specific field paths fromthe wildcard index. This option is onlyvalid if creating a wildcard index.The wildcardProjection option takes the following form:
  1. wildcardProjection: { "path.to.field.a" : <value>, "path.to.field.b" : <value>}
The <value> can be either of the following:- 1 or true to include the field in the wildcard index.- 0 or false to exclude the field from the wildcard index.A wildcardProjection cannot contain both include and excludespecifications, with the exception of including the _id fieldwhile excluding other fields.NoteWildcard 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 }).Options specified to db.collection.createIndexes apply to all of the indexspecifications included in the key pattern array. SpecifywildcardProjection only if you are creating a single wildcard index usingdb.collection.createIndexes.

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.

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:

  1. {
  2. location: {
  3. type: "Point",
  4. coordinates: [-73.856077, 40.848447]
  5. },
  6. name: "Morris Park Bake Shop",
  7. cuisine: "Cafe",
  8. borough: "Bronx",
  9. }

The following example creates two indexes on the restaurantscollection: an ascending index on the borough field and a2dsphere index on the location field.

  1. 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:

  1. db.products.createIndexes( [ { "manufacturer": 1}, { "category": 1 } ],
  2. { 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

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

  1. {
  2. "_id" : ObjectId("5c1d358bf383fbee028aea0b"),
  3. "product_name" : "Blaster Gauntlet",
  4. "product_attributes" : {
  5. "price" : {
  6. "cost" : 299.99
  7. "currency" : USD
  8. }
  9. ...
  10. }
  11. },
  12. {
  13. "_id" : ObjectId("5c1d358bf383fbee028aea0c"),
  14. "product_name" : "Super Suit",
  15. "product_attributes" : {
  16. "superFlight" : true,
  17. "resistance" : [ "Bludgeoning", "Piercing", "Slashing" ]
  18. ...
  19. },
  20. }

The following operation creates a wildcard index on theproduct_attributes field:

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

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:

  1. db.products_catalog.find( { "product_attributes.superFlight" : true } )
  2. db.products_catalog.find( { "product_attributes.maxSpeed" : { $gt : 20 } } )
  3. 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:

  1. {
  2. "_id" : ObjectId("5c1d358bf383fbee028aea0b"),
  3. "product_name" : "Blaster Gauntlet",
  4. "product_attributes" : {
  5. "price" : {
  6. "cost" : 299.99
  7. "currency" : USD
  8. }
  9. ...
  10. }
  11. },
  12. {
  13. "_id" : ObjectId("5c1d358bf383fbee028aea0c"),
  14. "product_name" : "Super Suit",
  15. "product_attributes" : {
  16. "superFlight" : true,
  17. "resistance" : [ "Bludgeoning", "Piercing", "Slashing" ]
  18. ...
  19. },
  20. }

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

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

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:

  1. db.products_catalog.find( { "product_price" : { $lt : 25 } } )
  2. 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:

  1. {
  2. "_id" : ObjectId("5c1d358bf383fbee028aea0b"),
  3. "product_name" : "Blaster Gauntlet",
  4. "product_attributes" : {
  5. "price" : {
  6. "cost" : 299.99
  7. "currency" : USD
  8. }
  9. ...
  10. }
  11. },
  12. {
  13. "_id" : ObjectId("5c1d358bf383fbee028aea0c"),
  14. "product_name" : "Super Suit",
  15. "product_attributes" : {
  16. "superFlight" : true,
  17. "resistance" : [ "Bludgeoning", "Piercing", "Slashing" ]
  18. ...
  19. },
  20. }

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.

  1. use inventory
  2. db.products_catalog.createIndexes(
  3. [ { "$**" : 1 } ],
  4. {
  5. "wildcardProjection" : {
  6. "product_attributes.elements" : 1,
  7. "product_attributes.resistance" : 1
  8. }
  9. }
  10. )

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:

  1. db.products_catalog.find( { "product_attributes.elements" : { $eq: "Water" } } )
  2. 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:

  1. {
  2. "_id" : ObjectId("5c1d358bf383fbee028aea0b"),
  3. "product_name" : "Blaster Gauntlet",
  4. "product_attributes" : {
  5. "price" : {
  6. "cost" : 299.99
  7. "currency" : USD
  8. }
  9. ...
  10. }
  11. },
  12. {
  13. "_id" : ObjectId("5c1d358bf383fbee028aea0c"),
  14. "product_name" : "Super Suit",
  15. "product_attributes" : {
  16. "superFlight" : true,
  17. "resistance" : [ "Bludgeoning", "Piercing", "Slashing" ]
  18. ...
  19. },
  20. }

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:

  1. use inventory
  2. db.products_catalog.createIndexes(
  3. [ { "$**" : 1 } ],
  4. {
  5. "wildcardProjection" : {
  6. "product_attributes.elements" : 0,
  7. "product_attributes.resistance" : 0
  8. }
  9. }
  10. )

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:

  1. db.products_catalog.find( { "product_attributes.maxSpeed" : { $gt: 25 } } )
  2. 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:

  1. "wildcardProjection" : {
  2. "_id" : 1
  3. }

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

Additional Information

For additional information about indexes, refer to: