(PECL mongo >=0.9.0)
MongoCollection::ensureIndex — Creates an index on the given field(s), or does nothing if the index already exists
$key|keys
[, array $options = array()
] )This method creates an index on the collection and the specified fields. The key specification can either be just a single field name as string, or an array containing one or more field names with their sort direction.
keys
An array of fields by which to sort the index on. Each element in the array has as key the field name, and as value either 1 for ascending sort, or -1 for descending sort.
options
This parameter is an associative array of the form array("optionname" => <boolean>, ...). Currently supported options are:
"w"
See WriteConcerns. The default value for MongoClient is 1.
"unique"
Create a unique index.
A unique index cannot be created on a field if multiple existing
documents do not contain the field. The field is effectively NULL
for these documents and thus already non-unique. Sparse indexing may
be used to overcome this, since it will prevent documents without the
field from being indexed.
"dropDups"
If a unique index is being created and duplicate values exist, drop all but one duplicate value.
"sparse"
Create a sparse index, which only includes documents containing the field. This option is only compatible with single-field indexes.
"expireAfterSeconds"
The value of this option should specify the number of seconds after which a document should be considered expired and automatically removed from the collection. This option is only compatible with single-field indexes where the field will contain MongoDate values.
This feature is available in MongoDB 2.2+. See » Expire Data from Collections by Setting TTL for more information.
"background"
By default, index creation is a blocking operation and will stop other
operations on the database from proceeding until completed. If you
specify TRUE for this option, the index will be created in the
background while other operations are taking place.
Prior to MongoDB 2.1.0, the index build operation is not a background build when it replicates to secondaries, irrespective of this option. See » Building Indexes with Replica Sets for more information.
"name"
This option allows you to override the algorithm that the driver uses to create an index name and specify your own. This can be useful if you are indexing many keys and Mongo complains about the index name being too long.
"timeout"
Integer, defaults to MongoCursor::$timeout. If acknowledged writes are used, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a MongoCursorTimeoutException will be thrown.
"safe"
Deprecated. Please use the WriteConcern w option.
Returns an array containing the status of the index creation if the
"w" option is set. Otherwise, returns TRUE.
Fields in the status array are described in the documentation for MongoCollection::insert().
| Version | Description |
|---|---|
| 1.3.0 |
The options parameter no longer accepts a boolean
to signify a unique index. Instead, this now has to be done with
array('unique' => true).
|
| 1.2.11 |
Emits E_DEPRECATED when
options is scalar.
|
| 1.2.0 | Added "timeout" option. |
| 1.0.11 |
The "safe" option will trigger a primary failover, if necessary. MongoException will be thrown if the index name (either generated or set) is longer than 128 bytes. |
| 1.0.5 | Added the "name" option to override index name creation. |
| 1.0.2 |
Changed options parameter from boolean to array.
Pre-1.0.2, the second parameter was an optional boolean value specifying
a unique index.
|
Throws MongoException if the index name is longer than 128 bytes. (Version 1.0.11+)
Throws MongoCursorException if the "w" option is set and the write fails.
Throws MongoCursorTimeoutException if the "w" option is set to a value greater than one and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout. The operation in MongoCollection::$wtimeout is milliseconds.
Example #1 MongoCollection::ensureIndex() example
<?php
$c = new MongoCollection($db, 'foo');
// create an index on 'x' ascending
$c->ensureIndex('x');
// create an index on 'y' ascending
$c->ensureIndex(array('y' => 1));
// create an index on 'z' ascending and 'zz' descending
$c->ensureIndex(array('z' => 1, 'zz' => -1));
// create a unique index on 'x'
$c->ensureIndex(array('x' => 1), array("unique" => true));
?>
Example #2 Drop duplicates example
<?php
$collection->insert(array("username" => "joeschmoe"));
$collection->insert(array("username" => "joeschmoe"));
/*
* index creation fails, you can't create a unique index on a key with
* non-unique values
*/
$collection->ensureIndex(array("username" => 1), array("unique" => 1));
/*
* index creation succeeds: one of the documents is removed from the collection
*/
$collection->ensureIndex(array("username" => 1), array("unique" => 1, "dropDups" => 1));
/*
* now we have a unique index, more inserts with the same username (such as the
* one below) will fail
*/
$collection->insert(array("username" => "joeschmoe"));
?>
Example #3 Geospatial Indexing
Mongo supports geospatial indexes, which allow you to search for documents near a given location or within a shape. For example, to create a geospatial index on the "loc" field:
<?php
$collection->ensureIndex(array("loc" => "2d"));
?>
MongoDB core docs on » vanilla indexes and » geospatial indexes.