Creates an index on the given field(s), or does nothing if the index already exists

MongoCollection::ensureIndex

(PECL mongo >=0.9.0)

MongoCollection::ensureIndex — Creates an index on the given field(s), or does nothing if the index already exists

Description

public bool MongoCollection::ensureIndex ( string|array $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.

Parameters

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.

Warning
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.

Warning
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"

Starting with driver version 1.0.5 you can specify an index name. 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 "safe" is set, 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.

Return Values

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().

Changelog

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.2	Changed `options` parameter from boolean to array. Pre-1.0.2, the second parameter was an optional boolean value specifying a unique index.

Errors/Exceptions

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.

Examples

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"));

?>