- Reference >
- JavaScript Methods >
- db.collection.ensureIndex()
db.collection.ensureIndex()¶
-
db.collection.
ensureIndex
(keys, options)¶ Creates an index on the field specified, if that index does not already exist.
Parameters: Warning
Index names, including their full namespace (i.e.
database.collection
) can be no longer than 128 characters. See thedb.collection.getIndexes()
field “name
” for the names of existing indexes.Consider the following prototype:
This command creates an index, in ascending order, on the field
[key]
.If the
keys
document specifies more than one field, thandb.collection.ensureIndex()
creates a compound index. To specify a compound index use the following form:This command creates a compound index on the
key
field (in ascending order) andkey1
field (in descending order.)Note
The order of an index is important for supporting
cursor.sort()
operations using the index.The Indexes section of this manual for full documentation of indexes and indexing in MongoDB.
ensureIndex()
provides the following- options
Option Value Default background true
orfalse
false
unique true
orfalse
false
name string none dropDups true
orfalse
false
sparse true
orfalse
false
expireAfterSeconds integer none v index version 1 Options: - background (boolean) – Specify
true
to build the index in the background so that building an index will not block other database activities. - unique (boolean) – Specify
true
to create a unique index so that the collection will not accept insertion of documents where the index key or keys matches an existing value in the index. - name (string) – Specify the name of the index. If unspecified, MongoDB will generate an index name by concatenating the names of the indexed fields and the sort order.
- dropDups (boolean) – Specify
true
when creating a unique index, on a field that may have duplicate to index only the first occurrence of a key, and remove all documents from the collection that contain subsequent occurrences of that key. - sparse (boolean) – If
true
, the index only references documents with the specified field. These indexes use less space, but behave differently in some situations (particularly sorts.) - expireAfterSeconds (integer) – Specify a value, in seconds, as a TTL to control how long MongoDB will retain documents in this collection. See “Expire Data from Collections by Setting TTL” for more information on this functionality.
- v – Only specify a different index version in unusual situations. The latest index version (version 1) provides a smaller and faster index format.
Please be aware of the following behaviors of
ensureIndex()
: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.
You cannot stop a foreground index build once it’s begun. See the Monitor and Control Index Building for more information.
[1] 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.