<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision: 330305 $ -->
<refentry xml:id="mongocollection.ensureindex" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoCollection::ensureIndex</refname>
  <refpurpose>
   Creates an index on the given field(s), or does nothing if the index 
   already exists
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>bool</type><methodname>MongoCollection::ensureIndex</methodname>
   <methodparam><type>string|array</type><parameter>key|keys</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
  </methodsynopsis>
  <para>
   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.
  </para>
 </refsect1>

 <refsect1 role="parameters"> 
  &reftitle.parameters; 
  <para>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>keys</parameter>
     </term>
     <listitem>
      <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
       <literal>1</literal> for ascending sort, or <literal>-1</literal> for
       descending sort.
      </para>
     </listitem>
    </varlistentry>   
    <varlistentry>
     <term>
      <parameter>options</parameter>
     </term>
     <listitem>
      <para>
       This parameter is an associative array of the form 
       <literal>array("optionname" => &lt;boolean&gt;, ...)</literal>. Currently 
       supported options are: 
       <itemizedlist>
        &mongo.writes.parameters.writeconcern;
        <listitem>
         <para>
          <literal>"unique"</literal>
         </para>
         <para>
          Create a unique index.
         </para>
         <warning>
          <para>
           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.
          </para>
         </warning>
        </listitem>
        <listitem>
         <para>
          <literal>"dropDups"</literal>
         </para>
         <para>
          If a unique index is being created and duplicate values exist, drop
          all but one duplicate value.
         </para>
        </listitem>
        <listitem>
         <para>
          <literal>"sparse"</literal>
         </para>
         <para>
          Create a sparse index, which only includes documents containing the
          field. This option is only compatible with single-field indexes.
         </para>
        </listitem>
        <listitem>
         <para>
          <literal>"expireAfterSeconds"</literal>
         </para>
         <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
          <classname>MongoDate</classname> values.
         </para>
         <para>
          This feature is available in MongoDB 2.2+. See
          <link xlink:href="&url.mongodb.docs.expire_data;">Expire Data from Collections by Setting TTL</link>
          for more information.
         </para>
        </listitem>
        <listitem>
         <para>
          <literal>"background"</literal>
         </para>
         <para>
          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.
         </para>
         <warning>
          <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
           <link xlink:href="&url.mongodb.dochub.indexes.rs;">Building Indexes with Replica Sets</link>
           for more information.
          </para>
         </warning>
        </listitem>
        <listitem>
         <para>
          <literal>"name"</literal>
         </para>
         <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.
         </para>
        </listitem>
        &mongo.writes.parameters.timeout;
        &mongo.writes.parameters.safe;
       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an array containing the status of the index creation if the
   <literal>"w"</literal> option is set. Otherwise, returns &true;.
  </para>
  <para>
   Fields in the status array are described in the documentation for
   <function>MongoCollection::insert</function>.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>1.3.0</entry>
       <entry>
        The <parameter>options</parameter> parameter no longer accepts a boolean
        to signify a unique index. Instead, this now has to be done with
        <literal>array('unique' => true)</literal>.
       </entry>
      </row>
      <row>
       <entry>1.2.11</entry>
       <entry>
        Emits <constant>E_DEPRECATED</constant> when
        <parameter>options</parameter> is <type>scalar</type>.
       </entry>
      </row>
      <row>
       <entry>1.2.0</entry>
       <entry>Added <literal>"timeout"</literal> option.</entry>
      </row>
      <row>
       <entry>1.0.11</entry>
       <entry>
        <para>
         The <literal>"safe"</literal> option will trigger a primary failover,
         if necessary.
        </para>
        <para>
         <classname>MongoException</classname> will be thrown if the index name
         (either generated or set) is longer than 128 bytes.
        </para>
       </entry>
      </row>
      <row>
       <entry>1.0.5</entry>
       <entry>
        Added the <literal>"name"</literal> option to override index name
        creation.
       </entry>
      </row>
      <row>
       <entry>1.0.2</entry>
       <entry>
        Changed <parameter>options</parameter> parameter from boolean to array.
        Pre-1.0.2, the second parameter was an optional boolean value specifying
        a unique index.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Throws <classname>MongoException</classname> if the index name is longer than
   128 bytes. (Version 1.0.11+)
  </para>
  &mongo.errors.exceptions.writeconcern;
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>MongoCollection::ensureIndex</function> example</title>
   <programlisting role="php">
<![CDATA[
<?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));

?>
]]>
   </programlisting>
  </example>
  <example>
   <title>Drop duplicates example</title>
   <programlisting role="php">
<![CDATA[
<?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"));

?>
]]>
   </programlisting>
  </example>

  <example>
   <title>Geospatial Indexing</title>
   <para>
    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:
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$collection->ensureIndex(array("loc" => "2d"));

?>
]]>
   </programlisting>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   MongoDB core docs on 
   <link xlink:href="&url.mongodb.dochub.indexes;">vanilla indexes</link> and 
   <link xlink:href="&url.mongodb.dochub.geo;">geospatial indexes</link>.
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->