Docs Home → MongoDB Manual
db.collection.createIndex[keys, 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. To use 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
mongo shell v4.2
Creates indexes on collections.
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.createIndex[]
takes the following parameters:
| document | A document that contains the 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 MongoDB supports several different index types including text, geospatial, and hashed indexes. See index types for more information. Changed in version 4.2: MongoDB 4.2 wildcard indexes support workloads where users query against custom fields or a large variety of fields in a collection:
The wildcard index key must use one of the syntaxes listed above. For example, you cannot specify a compound index key. For more complete documentation on wildcard indexes, including restrictions on their creation, see Wildcard Index Restrictions. The
For examples of wildcard index creation, see Create a Wildcard Index. | ||||||
| document | Optional. A document that contains a set of options that controls the creation of the index. See Options for details. | ||||||
commitQuorum | 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 Supports the following values:
New in version 4.4. |
The options
document contains a set of options that controls the creation of the index. 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.createIndex[]
operation will fail.
Consider the following db.collection.createIndex[]
operation:
db.collection.createIndex[ { "a": 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.
The following options are available for all index types unless otherwise specified:
| boolean | Optional. Deprecated in MongoDB 4.2.
|
| boolean | Optional. Creates a unique index so that the collection will not accept insertion or update of documents where the index key value matches an existing value in the index. Specify The option is unavailable for hashed indexes. |
| 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. NoteChanged in MongoDB 4.2Starting in version 4.2, for featureCompatibilityVersion set to |
partialFilterExpression
document
Optional. If specified, the index only references documents that match the filter expression. See Partial Indexes for more information.
A filter expression can include:
equality expressions [i.e.
field: value
or using the$eq
operator],$exists: true
expression,$gt
,$gte
,$lt
,$lte
expressions,$type
expressions,$and
operator,$or
operator,$in
operator
You can specify a partialFilterExpression
option for all MongoDB
index types.
sparse
boolean
Optional. If true
, the index only references documents with the specified field. 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:
2dsphere
2d
geoHaystack
text
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.
Changed in version 3.2: Starting in MongoDB 3.2, MongoDB provides the option to create partial indexes. Partial indexes offer a superset of the functionality of sparse indexes. If you are using MongoDB 3.2 or later, partial indexes should be preferred over sparse indexes.
expireAfterSeconds
integer
Optional. Specifies a value, in seconds, as a TTL to control how long MongoDB retains documents in this collection. See Expire Data from Collections by Setting TTL for more information on this functionality. This applies only to TTL indexes.
hidden
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
.
To use the hidden
option, you must have featureCompatibilityVersion
set to 4.4
or greater. However, once hidden, the index remains hidden even with featureCompatibilityVersion set to 4.2
on MongoDB 4.4 binaries.
New in version 4.4.
storageEngine
document
Optional. Allows users to configure the storage engine on a per-index basis when creating an index.
The storageEngine
option should take the following form:
storageEngine: { : }
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.
Warning
Collation is not supported in MongoDB 3.2 and earlier versions. In MongoDB 3.2 and earlier versions, do not create indexes with the unsupported collation option as this will block the upgrade to 3.4, which enforces a stricter validation of index options.
| 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:
The collation option has the following syntax:
When specifying collation, the |
The following indexes only support simple binary comparison and do not support collation:
text indexes,
2d indexes, and
geoHaystack indexes.
Tip
To create a text
, a 2d
, or a geoHaystack
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.
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" } ]
The following options are available for text indexes only:
| document | Optional. For text indexes, a document that contains field and weight pairs. The weight is an integer ranging from 1 to 99,999 and denotes the significance of the field relative to the other indexed fields in terms of the score. You can specify weights for some or all the indexed fields. See
Control Search Results with Weights to adjust the scores. The default value is Starting in MongoDB 5.0, the weights option is only allowed for text indexes. |
| string | Optional. For text indexes, the language that determines the list of stop words and the rules for the stemmer and tokenizer. See Text Search Languages for the available languages and
Specify a Language for Text Index for more information and examples. The default value is |
| 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 |
| integer | Optional. The For available versions, see Versions. |
The following option is available for 2dsphere indexes only:
| integer | Optional. The For the available versions, see Versions. |
The following options are available for 2d indexes only:
| integer | Optional. For 2d indexes, the number of precision of the stored geohash value of the location data. The |
| number | Optional. For 2d indexes, the lower inclusive boundary for the longitude and latitude values. The default value is |
| number | Optional. For 2d indexes, the upper inclusive boundary for the longitude and latitude values. The default value is |
The following option is available for geoHaystack indexes only:
| number | For geoHaystack indexes, specify the number of units within which to group the location values; i.e. group in the same bucket those location values that are within the specified number of units to each other. The value must be greater than 0. |
Note
Removed in MongoDB 5.0
The following option is available for wildcard indexes only:
| document | Optional. Allows users to include or exclude specific field paths from a wildcard index using the The
The
Wildcard indexes omit the
With the exception of explicitly including |
Changed in version 4.2.
For featureCompatibilityVersion "4.2"
, db.collection.createIndex[]
uses an optimized build process that obtains and
holds an exclusive lock on the specified collection at the start and end of the index build. All subsequent operations on the collection must wait until db.collection.createIndex[]
releases the exclusive lock.
db.collection.createIndex[]
allows interleaving read and write operations 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 exclusive lock on the parent database for the entire duration of the build process. The pre-4.2 build process blocks all operations on the database and all its collections until the operation completed. background
indexes do not take an exclusive lock.
For more information on the locking behavior of db.collection.createIndex[]
, see Index Builds on Populated Collections.
If you call
db.collection.createIndex[]
for an index that already exists, MongoDB does not recreate the index.
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.createIndex[]
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.
Note
To hide or unhide existing indexes, you can use the following mongosh
methods:
db.collection.hideIndex[]
db.collection.unhideIndex[]
For example,
To change the
hidden
option for an index totrue
, use thedb.collection.hideIndex[]
method:db.restaurants.hideIndex[ { borough: 1, ratings: 1 } ];
To change the
hidden
option for an index tofalse
, use thedb.collection.unhideIndex[]
method:db.restaurants.unhideIndex[ { borough: 1, city: 1 } ];
Tip
See also:
For MongoDB 2.6 through MongoDB versions with
featureCompatibilityVersion [fCV] set to "4.0"
or earlier, MongoDB will not create an index on a collection if the index entry for an existing document exceeds the Maximum Index Key Length.
Changed in version 4.4.
Starting in MongoDB 4.4, you can create collections and indexes inside a multi-document transaction if the transaction is not a cross-shard write transaction.
To use
db.collection.createIndex[]
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:
The following example creates an ascending index on the field orderDate
.
db.collection.createIndex[ { orderDate: 1 } ]
If the keys
document specifies more than one field, then
createIndex[]
creates a compound index.
The following example creates a compound index on the orderDate
field [in ascending order] and the zipcode
field [in descending order.]
db.collection.createIndex[ { orderDate: 1, zipcode: -1 } ]
Changed
in version 4.4: Starting in MongoDB 4.4, compound indexes can include a single hashed field. Compound hashed indexes require featureCompatibilityVersion set to 4.4
.
The following example creates a compound index on the state
field
[in ascending order] and the zipcode
field [hashed]:
db.collection.createIndex[ { "state" : 1, "zipcode" : "hashed" } ]
The order of fields in a compound index is important for supporting sort[]
operations using the index.
Tip
The following example creates an index named category_fr
. The example creates the index with the
collation that specifies the locale fr
and comparison strength 2
:
db.collection.createIndex[ { category: 1 }, { name: "category_fr", collation: { locale: "fr", strength: 2 } } ]
The following example creates a compound index named date_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 collation rules, MongoDB can use the index. For details, see Collation and Index Use.
New in version 4.2.
The mongod
featureCompatibilityVersion must be 4.2
to create wildcard indexes. For instructions on setting the fCV, see
Set Feature Compatibility Version on MongoDB 6.0 Deployments.
Wildcard indexes omit the
_id
field by default. To include the_id
field in the wildcard index, you must explicitly include it in thewildcardProjection
document:{ "wildcardProjection" : { "_id" : 1, "" : 0|1 } } With the exception of explicitly including
_id
field, you cannot combine inclusion and exclusion statements in thewildcardProjection
document.Wildcard indexes do not support the following index types or properties:
Compound
TTL
Text
2d [Geospatial]
2dsphere [Geospatial]
Hashed
Unique
Note
Wildcard Indexes are distinct from and incompatible with Wildcard Text Indexes. Wildcard indexes cannot support queries using the
$text
operator.For complete documentation on wildcard index restrictions, see Wildcard Index Restrictions.
For complete documentation on Wildcard Indexes, see Wildcard 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
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.createIndex[ { "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.createIndex[ { "$**" : 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.createIndex[ { "$**" : 1 }, { "wildcardProjection" : { "product_attributes.elements" : 1, "product_attributes.resistance" : 1 } } ]
While the key pattern "$**"
covers all fields in the document, the wildcardProjection
field limits the index to only the included 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 created index can support 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" ] ... }, }
The following operation creates a
wildcard index and uses the wildcardProjection
document to index all scalar fields for each document in the collection, excluding the product_attributes.elements
and product_attributes.resistance
fields:
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, 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 created index can support queries on any scalar field except those 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.
Specify the
commitQuorum parameter to the createIndex[]
operation to set the minimum number of data-bearing voting members [i.e commit quorum], including the primary, which must complete
the index build before the primary marks the indexes as ready. The default commit quorum is votingMembers
, or all data-bearing voting replica set members.
The following operation creates an index with a commit quorum of "majority"
, or a simple majority of data-bearing voting members:
db.getSiblingDB["examples"].invoices.createIndex[ { "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.
The Indexes section of this manual for full documentation of indexes and indexing in MongoDB.
db.collection.getIndexes[]
to view the specifications of existing indexes for a collection.Text Indexes for details on creating
text
indexes.Geospatial Indexes for geospatial queries.
TTL Indexes for expiration of data.