Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

db.collection.createIndexes()

On this page

  • Definition
  • Options
  • Options for All Index Types
  • Option for Collation
  • Options for text Indexes
  • Options for 2dsphere Indexes
  • Options for 2d Indexes
  • Options for wildcard indexes
  • Behaviors
  • Recreating an Existing Index
  • Index Options
  • Wildcard Indexes
  • Transactions
  • Example
  • Create Indexes Without Options
  • Create Indexes with Collation Specified
  • Create a Wildcard Index
  • Create Indexes With Commit Quorum
  • Create Multiple Indexes
  • Additional Information
db.collection.createIndexes( [ keyPatterns ], options, commitQuorum )

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the createIndexes command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:

mongo shell v4.4

Creates one or more indexes on a collection.

To minimize the impact of building an index on replica sets and sharded clusters, use a rolling index build procedure as described on Rolling Index Builds on Replica Sets.

db.collection.createIndexes() takes the following parameters:

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:

See index types for more information.

Wildcard indexes support workloads where users query against custom fields or a large variety of fields in a collection:

  • You can create a wildcard index on a specific field and its subpaths or on all of the fields in a document.

    For details see, Wildcard Indexes.

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

Optional. The minimum number of data-bearing voting replica set members (i.e. commit quorum), including the primary, that must report a successful index build before the primary marks the indexes as ready. A "voting" member is any replica set member where members[n].votes is greater than 0.

Supports the following values:

  • "votingMembers" - all data-bearing voting replica set members (Default).

  • "majority" - a simple majority of data-bearing voting replica set members.

  • <int> - a specific number of data-bearing voting replica set members.

  • 0 - Disables quorum-voting behavior. Members start the index build simultaneously but do not vote or wait for quorum before completing the index build. If you start an index build with a commit quorum of 0, you cannot later modify the commit quorum using setIndexCommitQuorum.

  • A replica set tag name.

New in version 4.4.

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.

Multiple index options can be specified in the same document. However, if you specify multiple option documents the db.collection.createIndexes() operation will fail.

Consider the following db.collection.createIndexes() operation:

db.collection.createIndexes(
[
{
"a": 1
},
{
"b": 1
}
],
{
unique: true,
sparse: true,
expireAfterSeconds: 3600
}
)

If the options specification had been split into multiple documents like this: { unique: true }, { sparse: true, expireAfterSeconds: 3600 } the index creation operation would have failed.

Important

When you specify options to db.collection.createIndexes(), the options apply to all of the specified indexes. For example, if you specify a collation option, all of the created indexes will include that collation.

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

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

Parameter
Type
Description
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.

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.

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.

The following index types 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.

Tip

Partial indexes offer a superset of the functionality of sparse indexes. Unless your application has a specific requirement, use partial indexes instead of sparse indexes.

expireAfterSeconds
integer

Optional. Specifies a value, in seconds, as a time to live (TTL) to control how long MongoDB retains documents in this collection. This option only applies to TTL indexes. See Expire Data from Collections by Setting TTL for more information.

If you use TTL indexes created before MongoDB 5.0, or if you want to sync data created in MongDB 5.0 with a pre-5.0 installation, see Indexes Configured Using NaN to avoid misconfiguration issues.

The TTL index expireAfterSeconds value must be within 0 and 2147483647 inclusive.

boolean

Optional. A flag that determines whether the index is hidden from the query planner. A hidden index is not evaluated as part of the query plan selection.

Default is false.

New in version 4.4.

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.

Parameter
Type
Description
collation
document

Optional. Specifies the collation for the index.

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase 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, MongoDB creates the index with the collection's default collation.

  • If you do specify a collation when creating the index, MongoDB creates the index with the specified collation.

The collation option has the following syntax:

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; all other collation fields are optional. For descriptions of the fields, see Collation Document.

The following indexes only support simple binary comparison and do not support collation:

Tip

To create a text or 2d index on a collection that has a non-simple collation, you must explicitly specify {collation: {locale: "simple"} } when creating the index.

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

  • If you do not specify a collation when creating the index, MongoDB creates the index with the collection's default collation.

  • If you do specify a collation when creating the index, MongoDB creates the index with the specified collation.

Tip

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

You can create multiple indexes on the same key(s) with different collations. To create indexes with the same key pattern but different collations, you must supply unique index names.

To use an index for string comparisons, an operation must also specify the same collation. That is, an index with a collation cannot support an operation that performs string comparisons on the indexed fields if the operation specifies a different collation.

Warning

Because indexes that are configured with collation use ICU collation keys to achieve sort order, collation-aware index keys may be larger than index keys for indexes without collation.

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

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

The following query operation, which specifies the same collation as the 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 a different collation can still use the index to support comparisons on the index prefix keys.

For example, the collection myColl has a compound index on the numeric fields score and price and the string field category; 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 collation for 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 collation for string comparisons on the indexed category field, can use the index to fulfill only the score: 5 portion of the query:

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

Important

Matches against document keys, including embedded document keys, use simple binary comparison. This means that a query for a key like "foo.bár" will not match the key "foo.bar", regardless of the value you set for the strength parameter.

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 Assign Weights to Text Search Results to adjust the scores. The default value is 1.

Starting in MongoDB 5.0, the weights option is only allowed for text indexes.

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 the Default Language for a 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 Specify the Default Language for a Text Index 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 Text Index Versions.

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 2dsphere 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.

The following option is available for wildcard indexes only:

Parameter
Type
Description
wildcardProjection
document

Optional. Allows users to include or exclude specific field paths from a wildcard index.

This option is only valid when you create an wildcard index on all document fields. You cannot specify the wildcardProjection option when you create a wildcard index on a specific field path and its subfields.

wildcardProjection works with specifications like:

{ "$**": 1 }
{ "userID":, "$**": 1 }

However, you can't define an index that includes the same field in the wildcard fields and the regular (non-wildcard) fields. To define the index correctly, use a wildcardProjection to exclude duplicated fields from the wildcard pattern.

wildcardProjection does not work with a specification like:

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

The wildcardProjection option takes the following form:

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.

Wildcard indexes omit the _id field by default. To include the _id field in the wildcard index, you must explicitly include it in the wildcardProjection document:

{
"wildcardProjection" : {
"_id" : 1,
"<field>" : 0|1
}
}

All of the statements in the wildcardProjection document must be either inclusion or exclusion statements. You can also include the _id field with exclusion statements. This is the only exception to the rule.

Options specified to db.collection.createIndexes() apply to all of the index specifications included in the key pattern array. Specify wildcardProjection only if you are creating a single wildcard index using db.collection.createIndexes().

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

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

The hidden option can be changed without dropping and recreating the index. See Hidden Option.

To change the other index options, drop the existing index with db.collection.dropIndex() before running db.collection.createIndexes() with the new options.

You can create multiple indexes on the same key(s) with different collations. To create indexes with the same key pattern but different collations, you must supply unique index names.

New in version 4.4.

To hide or unhide existing indexes, you can use the following mongosh methods:

For example,

  • To change the hidden option for an index to true, use the db.collection.hideIndex() method:

    db.restaurants.hideIndex( { borough: 1, ratings: 1 } );
  • To change the hidden option for an index to false, use the db.collection.unhideIndex() method:

    db.restaurants.unhideIndex( { borough: 1, city: 1 } );

Tip

See also:

  • Wildcard indexes omit the _id field by default. To include the _id field in the wildcard index, you must explicitly include it in the wildcardProjection document:

    {
    "wildcardProjection" : {
    "_id" : 1,
    "<field>" : 0|1
    }
    }

    All of the statements in the wildcardProjection document must be either inclusion or exclusion statements. You can also include the _id field with exclusion statements. This is the only exception to the rule.

  • Wildcard indexes do not support:

    Wildcard indexes are sparse indexes. They do not support queries when an indexed field does not exist. A wildcard index will index the document if the wildcard field has a null value.

    Starting in MongoDB 7.0, wildcard indexes support ascending (1) and descending (-1) sort order. Earlier versions only supported ascending order.

To learn more, see:

Changed in version 4.4.

You can create collections and indexes inside a distributed transaction if the transaction is not a cross-shard write transaction.

To use db.collection.createIndexes() in a transaction, the transaction must use read concern "local". If you specify a read concern level other than "local", the transaction fails.

Tip

See also:

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

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"}])

The following example creates two indexes on the products collection: an ascending index on the manufacturer field and an ascending index on the category field. Both indexes use a collation that specifies the locale fr and comparison 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 collation rules, MongoDB can use the index. For details, see Collation and Index Use.

For complete documentation on Wildcard Indexes, see Wildcard Indexes.

The following lists examples of wildcard index creation:

Consider a collection products_catalog where documents may contain a product_attributes field. The product_attributes field can contain arbitrary nested fields, including embedded documents 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 the product_attributes field:

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

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

The wildcard index can support arbitrary single-field queries on product_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" } } )

Note

The path-specific wildcard index syntax is incompatible with the wildcardProjection option. See the parameter documentation for more information.

Consider a collection products_catalog where documents may contain a product_attributes field. The product_attributes field can contain arbitrary nested fields, including embedded documents 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 each document in the collection. If a given field is a nested document or array, the wildcard index recurses into the document/array and indexes all scalar fields in the document/array.

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

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

Note

Wildcard indexes omit the _id field by default. To include the _id field in the wildcard index, you must explicitly include it in the wildcardProjection document. See parameter documentation for more information.

Consider a collection products_catalog where documents may contain a product_attributes field. The product_attributes field can contain arbitrary nested fields, including embedded documents 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 uses the wildcardProjection option to include only scalar values of the product_attributes.elements and product_attributes.resistance fields in the index.

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

The pattern "$**" includes all fields in the document. Use the wildcardProjection field to limit the index to the specified fields.

For complete documentation on wildcardProjection, see Options for wildcard indexes.

If a field is a nested document or array, the wildcard index recurses into the document/array and indexes all scalar fields in the document/array.

The wildcard index supports queries on any scalar field included in the wildcardProjection:

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

Note

Wildcard indexes do not support mixing inclusion and exclusion statements in the wildcardProjection document except when explicitly including the _id field. For more information on wildcardProjection, see the parameter documentation.

Consider a collection products_catalog where documents may contain a product_attributes field. The product_attributes field can contain arbitrary nested fields, including embedded documents 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" ]
...
},
}

This example uses a wildcard index and a wildcardProjection document to index the scalar fields for each document in the collection. The wildcard index excludes the product_attributes.elements and product_attributes.resistance fields:

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

The wildcard pattern "$**" includes all of the fields in the document. However, the wildcardProjection field excludes the specified fields from the index.

For complete documentation on wildcardProjection, see Options for wildcard indexes.

If a field is a nested document or array, the wildcard index recurses into the document/array and indexes all scalar fields in the document/array.

The index can support queries on any scalar field except fields that are excluded by wildcardProjection:

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

Note

Wildcard indexes do not support mixing inclusion and exclusion statements in the wildcardProjection document except when explicitly including the _id field. For more information on wildcardProjection, see the parameter documentation.

Note

Requires featureCompatibilityVersion 4.4+

Each mongod in the replica set or sharded cluster must have featureCompatibilityVersion set to at least 4.4 to start index builds simultaneously across replica set members.

MongoDB 4.4 running featureCompatibilityVersion: "4.2" builds indexes on the primary before replicating the index build to secondaries.

Starting with MongoDB 4.4, index builds on a replica set or sharded cluster build simultaneously across all data-bearing replica set members. For sharded clusters, the index build occurs only on shards containing data for the collection being indexed. The primary requires a minimum number of data-bearing voting members (i.e commit quorum), including itself, that must complete the build before marking the index as ready for use. See Index Builds in Replicated Environments for more information.

To set the commit quorum, use createIndexes() to specify the commitQuorum value.

commitQuorum specifies how many data-bearing voting members, or which voting members, including the primary, must be prepared to commit the index build before the primary will execute the commit. The default commit quorum is votingMembers, which means all data-bearing members.

The following operation creates an index with a commit quorum of "majority":

db.getSiblingDB("examples").invoices.createIndexes(
{ "invoices" : 1 },
{ },
"majority"
)

The primary marks index build as ready only after a simple majority of data-bearing voting members "vote" to commit the index build. For more information on index builds and the voting process, see Index Builds in Replicated Environments.

Create a cakeSales collection that contains cake sales in the states of California (CA) and Washington (WA):

db.cakeSales.insertMany( [
{ _id: 0, type: "chocolate", orderDate: new Date("2020-05-18T14:10:30Z"),
state: "CA", price: 13, quantity: 120 },
{ _id: 1, type: "chocolate", orderDate: new Date("2021-03-20T11:30:05Z"),
state: "WA", price: 14, quantity: 140 },
{ _id: 2, type: "vanilla", orderDate: new Date("2021-01-11T06:31:15Z"),
state: "CA", price: 12, quantity: 145 },
{ _id: 3, type: "vanilla", orderDate: new Date("2020-02-08T13:13:23Z"),
state: "WA", price: 13, quantity: 104 },
{ _id: 4, type: "strawberry", orderDate: new Date("2019-05-18T16:09:01Z"),
state: "CA", price: 41, quantity: 162 },
{ _id: 5, type: "strawberry", orderDate: new Date("2019-01-08T06:12:03Z"),
state: "WA", price: 43, quantity: 134 }
] )

The following example creates multiple indexes on the cakeSales collection:

db.cakeSales.createIndexes( [
{ "type": 1 },
{ "orderDate": 1 },
{ "state": 1 },
{ "orderDate": 1, "state": -1 }
] )

The first three indexes are on single fields and in ascending order (1).

The last index is on orderDate in ascending order (1) and state in descending order (-1).

For additional information about indexes, refer to:

←  db.collection.createIndex()db.collection.dataSize() →