(No version information available, might only be in Git)
MongoCollection::createIndex — Creates an index on the given field(s)
$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, -1 for descending sort, or any of the index plugins (currently, "text", "2d", or "2dsphere"").
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.
Deprecated in favour of the "socketTimeoutMS" option
"safe"
Deprecated. Please use the WriteConcern w option.
Returns an array containing the status of the index creation. The array contains whether the operation worked ("ok"), the amount of indexes before and after the operation ("numIndexesBefore" and "numIndexesAfter") and whether the collection that the index belongs to has been created ("createdCollectionAutomatically").
With MongoDB 2.4 and earlier, a status document is only returned if the
"w" option is set to 1—either through
the connection string, or with Write Concerns. If
"w" is not set to 1, it returns
TRUE. The fields in the status document are different, except for the
"ok" field which signals whether the index creation
worked.
Throws MongoException if the index name is longer than 128 bytes, or the index specification is not an array.
Throws MongoResultException if the server could not add the index.
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::createIndex() example
<?php
$c = new MongoCollection($db, 'foo');
// create an index on 'x' ascending
$c->createIndex(array('x' => 1));
// create an index on 'z' ascending and 'zz' descending
$c->createIndex(array('z' => 1, 'zz' => -1));
// create a unique index on 'x'
$c->createIndex(array('x' => 1), array("unique" => true));
// create a 2dsphere geospatial index index on 'w'
$c->createIndex(array('w' => "2dsphere"));
?>
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->createIndex(array("username" => 1), array("unique" => 1));
/*
* index creation succeeds: one of the documents is removed from the collection
*/
$collection->createIndex(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->createIndex(array("loc" => "2dsphere"));
?>
MongoDB core docs on » vanilla indexes and » geospatial indexes.