- Reference >
mongoShell Methods >- Collection Methods >
- db.collection.createIndexes()
db.collection.createIndexes()¶
On this page
Definition¶
-
db.collection.createIndexes([keyPatterns, ]options)¶ New in version 3.2.
Creates one or more indexes on a collection.
Parameter Type Description keyPatternsdocument 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 text, geospatial, and hashed indexes. See index types for more information.
optionsdocument Optional. A document that contains a set of options that controls the creation of the indexes. See Options for details.
Options¶
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.
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. Refer to the
options descriptions for more information.
Changed in version 3.4: Added support for collation.
Options for All Index Types¶
The following options are available for all index types unless otherwise specified:
Changed in version 3.0: The dropDups option is no longer available.
| Parameter | Type | Description |
|---|---|---|
background |
boolean | Optional. Builds the indexes in the background so the operation does
not block other database activities. Specify true to build in
the background. The default value is false. |
unique |
boolean | Optional. Specifies that each index specified in the 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. Whether user specified or MongoDB generated, index names including
their full namespace (i.e. Options specified to |
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 New in version 3.2. |
sparse |
boolean | Optional. If 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. Changed in version 2.6: 2dsphere indexes are sparse by default and
ignore this option. For a compound index that includes
2d, geoHaystack, and text indexes behave similarly to the 2dsphere 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. |
storageEngine |
document | Optional. Allows users to configure the storage engine for the created indexes. The 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. New in version 3.0. |
Option for Collation¶
The collation option is available for all index
types except for text indexes. If you wish to specify the collation
option, you cannot include a text index specification in the
db.collection.createIndexes() key patterns.
| 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: collation: {
locale: <string>,
caseLevel: <boolean>,
caseFirst: <string>,
strength: <int>,
numericOrdering: <boolean>,
alternate: <string>,
maxVariable: <string>,
backwards: <boolean>
}
When specifying collation, the New in version 3.4. |
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.
Unlike other index 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.
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" } )
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
Control Search Results with Weights to adjust the scores.
The default value is 1. |
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 a Language for 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
Use any Field to Specify the Language for a Document for an example. |
textIndexVersion |
integer | Optional. For text indexes, the In MongoDB 2.6, the default version is New in version 2.6. |
Options for 2dsphere Indexes¶
The following option is available for 2dsphere indexes only:
| Parameter | Type | Description |
|---|---|---|
2dsphereIndexVersion |
integer | Optional. For 2dsphere indexes, the In MongoDB 2.6, the default version is New in version 2.6. |
Options for 2d 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 |
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 geoHaystack Indexes¶
The following option is available for geoHaystack indexes only:
| Parameter | Type | Description |
|---|---|---|
bucketSize |
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. |
Behaviors¶
The createIndexes() method has the following
behaviors.
Warning
Foreground index builds block all other operations on the database.
Changed in version 3.4.
To add or change index options other than collation, you must drop the index using the
dropIndex()method and issue anotherdb.collection.createIndexes()operation with the new options.If you create an index with one set of options, and then issue the
db.collection.createIndexes()method with the same index fields and different options (not including collation) without first dropping the index,db.collection.createIndexes()will not rebuild the existing index with the new options.Unlike other index 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.
If you call
db.collection.createIndexes()multiple times concurrently with the same index specification, only the first operation will succeed. All other operations will have no effect.MongoDB will not create an index on a collection if the index entry for an existing document exceeds the
Maximum Index Key Length. Previous versions of MongoDB would create the index but not index such documents.
Example¶
See also
db.collection.createIndex() for examples of
various index specifications.
Create Indexes Without Options¶
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"}])
Create Indexes with Collation Specified¶
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.
Additional Information¶
For additional information about indexes, refer to:
- 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
textindexes. - Geospatial Indexes and geoHaystack Indexes for geospatial queries.
- TTL Indexes for expiration of data.