indexes.txt 3.5 KB
Newer Older
1 2 3 4 5 6
=======
Indexes
=======

.. default-domain:: mongodb

7 8 9 10 11
Indexes support the efficient execution of queries in MongoDB. Without indexes,
MongoDB must perform a *collection scan*, i.e. scan every document in a
collection, to select those documents that match the query statement. If an
appropriate index exists for a query, MongoDB can use the index to limit the
number of documents it must inspect.
12 13 14 15 16 17 18

The PHP driver supports managing indexes through the
:phpclass:`MongoDB\\Collection` class, which implements MongoDB's
cross-driver `Index Management
<https://github.com/mongodb/specifications/blob/master/source/index-management.rst>`_
and `Enumerating Indexes
<https://github.com/mongodb/specifications/blob/master/source/enumerate-indexes.rst>`_
19
specifications.
20

21 22 23 24
This document provides an introduction to creating, listing, and dropping
indexes using the |php-library|. The MongoDB Manual's :manual:`Indexes
</indexes>` reference provides more thorough information about indexing in
MongoDB.
25 26 27 28

Create Indexes
--------------

29 30 31
Create indexes with the :phpmethod:`MongoDB\\Collection::createIndex()` or
:phpmethod:`MongoDB\\Collection::createIndexes()` methods. Refer to the method
reference for more details about each method.
32

33 34
The following example creates an ascending index on the ``state`` field using
the :phpmethod:`createIndex() <MongoDB\\Collection::createIndex>` method:
35 36 37 38 39

.. code-block:: php

   <?php

40
   $collection = (new MongoDB\Client)->test->zips;
41 42 43 44 45

   $result = $collection->createIndex(['state' => 1]);

   var_dump($result);

46 47 48
When you create an index, the method returns its name, which is automatically
generated from its specification. The above example would output something
similar to::
49 50 51 52 53 54

   string(7) "state_1"

List Indexes
------------

55 56 57 58 59
The :phpmethod:`MongoDB\\Collection::listIndexes()` method provides information
about the indexes in a collection. The
:phpmethod:`MongoDB\\Collection::listIndexes()` method returns an iterator of
:phpclass:`MongoDB\\Model\\IndexInfo` objects, which you can use to view
information about each index. Refer to the method reference for more details.
60

61
The following example lists all indexes in the ``zips`` collection in the
62
``test`` database:
63 64 65 66 67

.. code-block:: php

   <?php

68
   $collection = (new MongoDB\Client)->test->zips;
69 70

   foreach ($collection->listIndexes() as $indexInfo) {
71
       var_dump($indexInfo);
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
   }

The output would resemble::

   object(MongoDB\Model\IndexInfo)#10 (4) {
     ["v"]=>
     int(1)
     ["key"]=>
     array(1) {
       ["_id"]=>
       int(1)
     }
     ["name"]=>
     string(4) "_id_"
     ["ns"]=>
87
     string(9) "test.zips"
88 89 90 91 92 93 94 95 96 97 98 99
   }
   object(MongoDB\Model\IndexInfo)#13 (4) {
     ["v"]=>
     int(1)
     ["key"]=>
     array(1) {
       ["state"]=>
       int(1)
     }
     ["name"]=>
     string(7) "state_1"
     ["ns"]=>
100
     string(9) "test.zips"
101 102 103 104 105
   }

Drop Indexes
------------

106 107 108 109
The :phpmethod:`MongoDB\\Collection::dropIndex()` method lets you drop a single
index while :phpmethod:`MongoDB\\Collection::dropIndexes()` drops all of the
indexes on a collection. Refer to the method reference for more details about
each method.
110 111 112 113 114 115 116

The following example drops a single index by its name, ``state_1``:

.. code-block:: php

   <?php

117
   $collection = (new MongoDB\Client)->test->zips;
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133

   $result = $collection->dropIndex('state_1');

   var_dump($result);

The operation's output would resemble::

   object(MongoDB\Model\BSONDocument)#11 (1) {
     ["storage":"ArrayObject":private]=>
     array(2) {
       ["nIndexesWas"]=>
       int(2)
       ["ok"]=>
       float(1)
     }
   }