- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.ensureIndex()
db.collection.ensureIndex()¶
On this page
Definition¶
-
db.collection.
ensureIndex
(keys, options)¶ Creates an index on the specified field if the index does not already exist.
The
ensureIndex()
method has the following fields:Parameter Type Description keys
document For ascending/descending indexes, a document that contains pairs with the name of the field or fields to index and order of the index. A 1
specifies ascending and a-1
specifies descending. MongoDB supports several different index types including text, geospatial, and hashed indexes. See Indexing Tutorials.options
document Optional. A document that controls the creation of the index. The document contains a set of options, as described in the next table. Warning
Index names, including their full namespace (i.e.
database.collection
) cannot be longer than 128 characters. See thegetIndexes()
fieldname
for the names of existing indexes.The
options
document has one or more of the following fields:Parameter Type Description background
Boolean Optional. Builds the index in the background so that building an index does not block other database activities. Specify true
to build in the background. The default value isfalse
.unique
Boolean Optional. Creates a unique index so that the collection will not accept insertion of documents where the index key or keys match an existing value in the index. Specify true
to create a unique index. The default value isfalse
. This option applies only to ascending/descending 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. dropDups
Boolean Optional. Creates a unique index on a field that may have duplicates. MongoDB indexes only the first occurrence of a key and removes all documents from the collection that contain subsequent occurrences of that key. Specify true
to create unique index. The default value isfalse
. This option applies only to scalar indexes.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 isfalse
. This applies only to ascending/descending 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. v
index version Optional. The index version number. The default index version depends on the version of mongod
running when creating the index. Before version 2.0, the this value was 0; versions 2.0 and later use version 1, which provides a smaller and faster index format. Specify a different index version only in unusual situations.weights
document Optional. For text
indexes, the significance of the field relative to the other indexed fields. The document contains field and weight pairs. The weight is a number 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 is1
. This applies totext
indexes only.default_language
string Optional. For a text
index, 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 isenglish
. This applies totext
indexes only.language_override
string Optional. For a text
index, specify the name of the field in the document that contains, for that document, the language to override the default language. The default value islanguage
.
Examples¶
Create an Ascending Index on a Single Field¶
The following example creates an ascending index on the field
orderDate
.
If the keys
document specifies more than one field, then
ensureIndex()
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.)
A compound index cannot include a hashed index component.
Note
The order of an index is important for supporting
sort()
operations using the index.
See also
- The Indexes section of this manual for full documentation of indexes and indexing in MongoDB.
- The Create Text Index section for more information and
examples on creating
text
indexes.
Behaviors¶
The ensureIndex()
method has the behaviors
described here.
To add or change index options you must drop the index using the
dropIndex()
method and issue anotherensureIndex()
operation with the new options.If you create an index with one set of options, and then issue the
ensureIndex()
method with the same index fields and different options without first dropping the index,ensureIndex()
will not rebuild the existing index with the new options.If you call multiple
ensureIndex()
methods with the same index specification at the same time, only the first operation will succeed, all other operations will have no effect.Non-background indexing operations will block all other operations on a database.
See also
In addition to the ascending/descending indexes, MongoDB provides the following index types to provide additional functionalities:
- TTL Indexes to support expiration of data,
- Geospatial Indexes and Haystack Indexes to support geospatial queries, and
- Text Indexes to support text searches.