db.collection.createIndex()

Definition

• db.collection.createIndex(keys, 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.

Creates indexes on collections.

Changed in version 3.2: MongoDB disallows the creation of version 0 indexes. To upgrade existing version 0indexes, see Version 0 Indexes.

ParameterTypeDescriptionkeysdocumentA document that contains the 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. Starting in 3.6, youcannot specify * as the index name.

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 examples of wildcard index creation, seeCreate a Wildcard Index.optionsdocumentOptional. A document that contains a set of options that controls the creationof the index. See Options for details.

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

To minimize the impact of building an index on replica sets andsharded clusters, use a rolling index build procedure as describedon Build Indexes on Replica Sets.

Options

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

Changed in version 3.4: Added support for collation option.

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

New in version 3.4.

Warning

Collation is not supported in MongoDB 3.2 and earlier versions. InMongoDB 3.2 and earlier versions, do not create indexes with theunsupported collation option as this will block the upgrade to 3.4,which enforces a stricter validation of index options.

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

"wildcardProjection" : {  "_id" : 1}

Behaviors

Concurrency

Changed in version 4.2.

For featureCompatibilityVersion "4.2", db.collection.createIndex()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.createIndex() releasesthe exclusive lock. db.collection.createIndex() allows interleaving read and writeoperations during the majority of the index build.

For featureCompatibilityVersion "4.0", db.collection.createIndex()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.createIndex(), seeIndex Builds on Populated Collections.

Recreating an Existing Index

If you call db.collection.createIndex() for an index thatalready exists, MongoDB does not recreate the index.

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.createIndex() 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.

Examples

Create an Ascending Index on a Single Field

The following example creates an ascending index on the fieldorderDate.

db.collection.createIndex( { orderDate: 1 } )

If the keys document specifies more than one field, thencreateIndex() creates a compoundindex.

Create an Index on a Multiple Fields

The following example creates a compound index on theorderDate field (in ascending order) and the zipcodefield (in descending order.)

db.collection.createIndex( { orderDate: 1, zipcode: -1 } )

A compound index cannot include a hashed indexcomponent.

Note

The order of an index is important for supportingsort() operations using the index.

Create Indexes with Collation Specified

New in version 3.4.

The following example creates an index named category_fr. Theexample creates the index with the collation that specifies the locale fr andcomparison strength 2:

db.collection.createIndex(
   { category: 1 },
   { name: "category_fr", collation: { locale: "fr", strength: 2 } }
)

The following example creates a compound index nameddate_category_fr with a collation.The collation applies only to the index keys with string values.

db.collection.createIndex(
   { orderDate: 1, category: 1 },
   { name: "date_category_fr", collation: { locale: "fr", strength: 2 } }
)

The collation applies to the indexed keys whose values are string.

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.

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

• 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 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
• Include Specific Fields in Wildcard Index Coverage
• Omit Specific Fields from Wildcard Index Coverage

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.createIndex( { "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.createIndex( { "$**" : 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 }).

Include Specific Fields in Wildcard Index Coverage

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.createIndex(
  { "$**" : 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 }).

Omit Specific Fields from Wildcard Index Coverage

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.createIndex(
  { "$**" : 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

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