db.collection.createIndex()
On this page
- Definition
- Compatibility
- Syntax
- 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
- Transactions
- Index Builds
- Examples
- Create an Ascending Index on a Single Field
- Create an Index on a Multiple Fields
- Create Indexes with Collation Specified
- Create a Wildcard Index
- Create Index With Commit Quorum
- Additional Information
Definition
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.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: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.
Compatibility
You can use db.collection.createIndex()
for deployments hosted in the following
environments:
MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
Syntax
The createIndex()
method has the following
form:
db.collection.createIndex( <keys>, <options>, <commitQuorum>)
The createIndex()
method takes the following
parameters:
Parameter | Type | Description |
---|---|---|
keys | 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 An asterisk ( 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.
|
options | document | Optional. A document that contains a set of options that controls the creation
of the index. 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 Supports the following values:
New in version 4.4. |
Options
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.
Options for All Index Types
The following options are available for all index types unless otherwise specified:
Parameter | Type | Description | |
---|---|---|---|
unique | 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. | |
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. | |
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:
You can specify a | |
sparse | boolean | Optional. If The following index types are sparse by default and ignore this option: For a compound index that includes TipPartial 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 | |
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 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
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. |
Option for Collation
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:
The collation option has the following syntax:
When specifying collation, the |
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.
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, 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" } )
Options for text
Indexes
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 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 For available versions, see Text Index Versions. |
Options for 2dsphere
Indexes
The following option is available for 2dsphere indexes only:
Parameter | Type | Description |
---|---|---|
2dsphereIndexVersion | integer | Optional. The For the available versions, see 2dsphere Indexes. |
Options for 2d
Indexes
The following options are available for 2d indexes only:
Parameter | Type | Description |
---|---|---|
bits | integer | |
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 . |
Options for wildcard
indexes
Wildcard indexes can use the
wildcardProjection
option.
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 a wildcard index on all document fields. You cannot specify
the
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
The
The
Wildcard indexes omit the
All of the statements in the |
Behaviors
Recreating an Existing Index
If you call db.collection.createIndex()
for an index that
already exists, MongoDB does not recreate the index.
Index Options
Non-Collation and Non-Hidden Options
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.
Collation Option
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.
Hidden Option
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 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 } );
Transactions
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.createIndex()
in a transaction, the transaction must use read
concern "local"
. If you specify a read concern level
other than "local"
, the transaction fails.
Index Builds
Changed in version 7.1.
Starting in MongoDB 7.1, index builds are improved with faster error
reporting and increased failure resilience. You can also set the minimum
available disk space required for index builds using the new
indexBuildMinAvailableDiskSpaceMB
parameter, which stops
index builds if disk space is too low.
The following table compares the index build behavior starting in MongoDB 7.1 with earlier versions.
Behavior Starting in MongoDB 7.1 | Behavior in Earlier MongoDB Versions |
---|---|
Index errors found during the collection scan phase, except
duplicate key errors, are returned immediately and then the index
build stops. Earlier MongoDB versions return errors in the commit
phase, which occurs near the end of the index build. MongoDB 7.1
helps you to rapidly diagnose index errors. For example, if an
incompatible index value format is found, the error is returned to
you immediately. | Index build errors can take a long time to be returned compared to
MongoDB 7.1 because the errors are returned near the end of the
index build in the commit phase. |
Increased resilience for your deployment. If an index build error
occurs, a secondary member can request that the
primary member stop an index build and the secondary
member does not crash. A request to stop an index build is not
always possible: if a member has already voted to commit the
index, then the secondary cannot request that the index build stop
and the secondary crashes (similar to MongoDB 7.0 and earlier). | An index build error can cause a secondary member to crash. |
Improved disk space management for index builds. An index build
may be automatically stopped if the available disk space is below
the minimum specified in the
indexBuildMinAvailableDiskSpaceMB parameter. If a
member has already voted to commit the index, then the index build
is not stopped. | An index build is not stopped if there is insufficient available
disk space. |
Examples
Create an Ascending Index on a Single Field
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.
Create an Index on a Multiple Fields
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.
Create Indexes with Collation Specified
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.
Create a 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 thewildcardProjection
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:
For examples, see:
Create a Wildcard Index on a Single Field Path
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.
Create a Wildcard Index on All Field Paths
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.
Include Specific Fields in 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 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 } } )
The pattern "$**"
includes all fields in the document. Use the
wildcardProjection
field to limit the index to fields you specify.
For complete documentation on wildcardProjection
, see
Options for wildcard
indexes.
If a field is a nested document or array, the wildcard index recurses into it and indexes all scalar fields in the document or 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.
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" ] ... }, }
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.createIndex( { "$**" : 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 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.
Create Index With Commit Quorum
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
createIndex()
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"
, 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.
Additional Information
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.