- Reference >
- mongo Shell Methods >
- Collection Methods >
- db.collection.ensureIndex()
db.collection.ensureIndex()¶
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 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 1; for descending index, specify a value of -1.
MongoDB supports several different index types including text, geospatial, and hashed indexes. See 索引类型 for more information.
options document Optional. A document that contains a set of options that controls the creation of the index. See Options for details.
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.
Options for All Index Types¶
The following options are available for all index types unless otherwise specified:
| 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 is false. |
| 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 is false. 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. database.collection) cannot be longer than the Index Name Limit. |
| 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 is false. The option is unavailable for hashed indexes. 2.6 版后已移除. 警告 dropDups will delete data from your collection when building the index. |
| 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 稀疏索引 for more information. 在 2.6 版更改: 2dsphere indexes are sparse by default and ignore this option. 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. 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. |
| 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. |
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 通过权重控制搜索结果 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 文本搜索语言 for the available languages and 指定文本索引的语言 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 使用任意键为文档指定语言 for an example. |
| textIndexVersion | integer | Optional. For text indexes, the text index version number. Version can be either 1 or 2. In MongoDB 2.6, the default version is 2. MongoDB 2.4 can only support version 1. 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 2dsphere index version number. Version can be either 1 or 2. In MongoDB 2.6, the default version is 2. MongoDB 2.4 can only support version 1. 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 bits value ranges from 1 to 32 inclusive. The default value is 26. |
| 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 ensureIndex() method has the behaviors described here.
To add or change index options you must drop the index using the dropIndex() method and issue another ensureIndex() 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.
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.
在 2.6 版更改.
Examples¶
Create an Ascending Index on a Single Field¶
The following example creates an ascending index on the field orderDate.
db.collection.ensureIndex( { orderDate: 1 } )
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.)
db.collection.ensureIndex( { orderDate: 1, zipcode: -1 } )
A compound index cannot include a hashed index component.
注解
The order of an index is important for supporting sort() operations using the index.
参见
- The Indexes section of this manual for full documentation of indexes and indexing in MongoDB.
- 文本索引 for details on creating text indexes.
- 地理空间索引 and geoHaystack 索引 for geospatial queries.
- TTL索引 for expiration of data.
- db.collection.getIndexes() to view the specifications of existing indexes for a collection.