<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Creates an index on the given field(s), or does nothing if the index
already exists</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongocollection.drop.html">MongoCollection::drop</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongocollection.find.html">MongoCollection::find</a></div>
<div class="up"><a href="class.mongocollection.html">MongoCollection</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongocollection.ensureindex" class="refentry">
<div class="refnamediv">
<h1 class="refname">MongoCollection::ensureIndex</h1>
<p class="verinfo">(PECL mongo >=0.9.0)</p><p class="refpurpose"><span class="refname">MongoCollection::ensureIndex</span> — <span class="dc-title">
Creates an index on the given field(s), or does nothing if the index
already exists
</span></p>
</div>
<div class="refsect1 description" id="refsect1-mongocollection.ensureindex-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><strong>MongoCollection::ensureIndex</strong></span>
( <span class="methodparam"><span class="type"><span class="type string|array">string|array</span></span> <code class="parameter">$key|keys</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$options</code><span class="initializer"> = array()</span></span>
] )</div>
<p class="para rdfs-comment">
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.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-mongocollection.ensureindex-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term">
<em><code class="parameter">keys</code></em>
</span>
<dd>
<p class="para">
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
<em>1</em> for ascending sort, or <em>-1</em> for
descending sort.
</p>
</dd>
</dt>
<dt>
<span class="term">
<em><code class="parameter">options</code></em>
</span>
<dd>
<p class="para">
This parameter is an associative array of the form
<em>array("optionname" => <boolean>, ...)</em>. Currently
supported options are:
<ul class="itemizedlist">
<li class="listitem"><p class="para"><em>"w"</em></p><p class="para">See <a href="mongo.writeconcerns.html" class="link">WriteConcerns</a>. The default value for <a href="class.mongoclient.html" class="classname">MongoClient</a> is <em>1</em>.</p></li>
<li class="listitem">
<p class="para">
<em>"unique"</em>
</p>
<p class="para">
Create a unique index.
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
A unique index cannot be created on a field if multiple existing
documents do not contain the field. The field is effectively <strong><code>NULL</code></strong>
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.
</p>
</div>
</li>
<li class="listitem">
<p class="para">
<em>"dropDups"</em>
</p>
<p class="para">
If a unique index is being created and duplicate values exist, drop
all but one duplicate value.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"sparse"</em>
</p>
<p class="para">
Create a sparse index, which only includes documents containing the
field. This option is only compatible with single-field indexes.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"expireAfterSeconds"</em>
</p>
<p class="para">
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
<a href="class.mongodate.html" class="classname">MongoDate</a> values.
</p>
<p class="para">
This feature is available in MongoDB 2.2+. See
<a href="http://docs.mongodb.org/manual/tutorial/expire-data/" class="link external">» Expire Data from Collections by Setting TTL</a>
for more information.
</p>
</li>
<li class="listitem">
<p class="para">
<em>"background"</em>
</p>
<p class="para">
By default, index creation is a blocking operation and will stop other
operations on the database from proceeding until completed. If you
specify <strong><code>TRUE</code></strong> for this option, the index will be created in the
background while other operations are taking place.
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
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
<a href="http://docs.mongodb.org/manual/tutorial/build-indexes-on-replica-sets/" class="link external">» Building Indexes with Replica Sets</a>
for more information.
</p>
</div>
</li>
<li class="listitem">
<p class="para">
<em>"name"</em>
</p>
<p class="para">
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.
</p>
</li>
<li class="listitem"><p class="para"><em>"timeout"</em></p><p class="para">Integer, defaults to <em>MongoCursor::$timeout</em>. 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 <a href="class.mongocursortimeoutexception.html" class="classname">MongoCursorTimeoutException</a> will be thrown.</p></li>
<li class="listitem"><p class="para"><em>"safe"</em></p><p class="para"><em class="emphasis">Deprecated</em>. Please use the <a href="mongo.writeconcerns.html" class="link">WriteConcern</a> <em>w</em> option.</p></li>
</ul>
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-mongocollection.ensureindex-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns an array containing the status of the index creation if the
<em>"w"</em> option is set. Otherwise, returns <strong><code>TRUE</code></strong>.
</p>
<p class="para">
Fields in the status array are described in the documentation for
<span class="function"><a href="mongocollection.insert.html" class="function">MongoCollection::insert()</a></span>.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-mongocollection.ensureindex-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>1.3.0</td>
<td>
The <em><code class="parameter">options</code></em> parameter no longer accepts a boolean
to signify a unique index. Instead, this now has to be done with
<em>array('unique' => true)</em>.
</td>
</tr>
<tr>
<td>1.2.11</td>
<td>
Emits <strong><code>E_DEPRECATED</code></strong> when
<em><code class="parameter">options</code></em> is <span class="type"><span class="type scalar">scalar</span></span>.
</td>
</tr>
<tr>
<td>1.2.0</td>
<td>Added <em>"timeout"</em> option.</td>
</tr>
<tr>
<td>1.0.11</td>
<td>
<p class="para">
The <em>"safe"</em> option will trigger a primary failover,
if necessary.
</p>
<p class="para">
<a href="class.mongoexception.html" class="classname">MongoException</a> will be thrown if the index name
(either generated or set) is longer than 128 bytes.
</p>
</td>
</tr>
<tr>
<td>1.0.5</td>
<td>
Added the <em>"name"</em> option to override index name
creation.
</td>
</tr>
<tr>
<td>1.0.2</td>
<td>
Changed <em><code class="parameter">options</code></em> parameter from boolean to array.
Pre-1.0.2, the second parameter was an optional boolean value specifying
a unique index.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 errors" id="refsect1-mongocollection.ensureindex-errors">
<h3 class="title">Errors/Exceptions</h3>
<p class="para">
Throws <a href="class.mongoexception.html" class="classname">MongoException</a> if the index name is longer than
128 bytes. (Version 1.0.11+)
</p>
<p class="para">Throws <a href="class.mongocursorexception.html" class="classname">MongoCursorException</a> if the "w" option is set and the write fails.</p><p class="para">Throws <a href="class.mongocursortimeoutexception.html" class="classname">MongoCursorTimeoutException</a> if the "w" option is set to a value greater than one and the operation takes longer than <var class="varname"><var class="varname">MongoCursor::$timeout</var></var> milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout. The operation in <em>MongoCollection::$wtimeout</em> is milliseconds.</p>
</div>
<div class="refsect1 examples" id="refsect1-mongocollection.ensureindex-examples">
<h3 class="title">Examples</h3>
<div class="example" id="example-1443">
<p><strong>Example #1 <span class="function"><strong>MongoCollection::ensureIndex()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$c </span><span style="color: #007700">= new </span><span style="color: #0000BB">MongoCollection</span><span style="color: #007700">(</span><span style="color: #0000BB">$db</span><span style="color: #007700">, </span><span style="color: #DD0000">'foo'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// create an index on 'x' ascending<br /></span><span style="color: #0000BB">$c</span><span style="color: #007700">-></span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(</span><span style="color: #DD0000">'x'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// create an index on 'y' ascending<br /></span><span style="color: #0000BB">$c</span><span style="color: #007700">-></span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'y' </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">// create an index on 'z' ascending and 'zz' descending<br /></span><span style="color: #0000BB">$c</span><span style="color: #007700">-></span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'z' </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #DD0000">'zz' </span><span style="color: #007700">=> -</span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">// create a unique index on 'x'<br /></span><span style="color: #0000BB">$c</span><span style="color: #007700">-></span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'x' </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">), array(</span><span style="color: #DD0000">"unique" </span><span style="color: #007700">=> </span><span style="color: #0000BB">true</span><span style="color: #007700">));<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="example-1444">
<p><strong>Example #2 Drop duplicates example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"joeschmoe"</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"joeschmoe"</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">/*<br /> * index creation fails, you can't create a unique index on a key with <br /> * non-unique values<br /> */<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username" </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">), array(</span><span style="color: #DD0000">"unique" </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">/*<br /> * index creation succeeds: one of the documents is removed from the collection<br /> */<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username" </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">), array(</span><span style="color: #DD0000">"unique" </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #DD0000">"dropDups" </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">/* <br /> * now we have a unique index, more inserts with the same username (such as the<br /> * one below) will fail<br /> */<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"username" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"joeschmoe"</span><span style="color: #007700">));<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="example-1445">
<p><strong>Example #3 Geospatial Indexing</strong></p>
<div class="example-contents"><p>
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:
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$collection</span><span style="color: #007700">-></span><span style="color: #0000BB">ensureIndex</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"loc" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"2d"</span><span style="color: #007700">));<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</div>
<div class="refsect1 seealso" id="refsect1-mongocollection.ensureindex-seealso">
<h3 class="title">See Also</h3>
<p class="para">
MongoDB core docs on
<a href="http://docs.mongodb.org/manual/indexes/" class="link external">» vanilla indexes</a> and
<a href="http://docs.mongodb.org/manual/applications/geospatial-indexes/" class="link external">» geospatial indexes</a>.
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mongocollection.drop.html">MongoCollection::drop</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mongocollection.find.html">MongoCollection::find</a></div>
<div class="up"><a href="class.mongocollection.html">MongoCollection</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
