Skip to content

Commit 1f70e6d

Browse files
rustagirrustagir
authored
Merge pull request #134 from rustagir/DOCSP-41984-single-fld-idx
DOCSP-41984: single field index
2 parents 55a44c1 + afd284a commit 1f70e6d

File tree

4 files changed

+273
-5
lines changed

4 files changed

+273
-5
lines changed

‎source/includes/indexes/indexes.php

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<?php
2+
3+
require __DIR__ . '/../vendor/autoload.php';
4+
5+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
6+
$client = new MongoDB\Client($uri);
7+
8+
$database = $client->sample_mflix;
9+
$collection = $database->movies;
10+
11+
// start-list-indexes
12+
foreach ($collection->listIndexes() as $indexInfo) {
13+
echo $indexInfo;
14+
}
15+
// end-list-indexes
16+
17+
// start-remove-index
18+
$collection->dropIndex('_title_');
19+
// end-remove-index
20+
21+
// start-remove-all-indexes
22+
$collection->dropIndexes();
23+
// end-remove-all-indexes
24+
25+
// start-index-single
26+
$indexName = $collection->createIndex(['title' => 1]);
27+
// end-index-single
28+
29+
// start-index-single-query
30+
$document = $collection->findOne(['title' => 'Sweethearts']);
31+
echo json_encode($document) , PHP_EOL;
32+
// end-index-single-query

‎source/indexes.txt

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,12 @@ Optimize Queries by Using Indexes
1818
:description: Learn how to use indexes by using the MongoDB PHP Library.
1919
:keywords: query, optimization, efficiency, usage example, code example
2020

21-
.. .. toctree::
22-
.. :titlesonly:
23-
.. :maxdepth: 1
24-
..
25-
.. /work-with-indexes
21+
.. toctree::
22+
:titlesonly:
23+
:maxdepth: 1
24+
25+
/indexes/index-mgmt
26+
/indexes/single-field-index
2627

2728
Overview
2829
--------

‎source/indexes/index-mgmt.txt

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
.. _php-index-mgmt:
2+
3+
===================================
4+
Index Considerations and Management
5+
===================================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: query, optimization, efficiency
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn about using **indexes** to improve the
24+
efficiency of your queries and add functionality to querying and
25+
storing documents.
26+
27+
Without a relevant index, MongoDB scans every document in a collection
28+
to find the documents that match a query. These collection scans are
29+
slow and can negatively affect the performance of your application.
30+
However, if the appropriate index exists, MongoDB can use the index to
31+
reduce the number of documents to inspect.
32+
33+
Operational Considerations
34+
~~~~~~~~~~~~~~~~~~~~~~~~~~
35+
36+
To improve query performance, build indexes on fields that appear often in
37+
your application's queries or operations that return sorted results. Each
38+
index that you add consumes disk space and memory, so we recommend
39+
that you track memory and disk usage when doing capacity planning. In addition,
40+
when a write operation updates an indexed field, MongoDB updates the related
41+
index, which can negatively impact performance for write operations.
42+
43+
You can use :manual:`wildcard indexes </core/index-wildcard/>` in your
44+
MongoDB application to query against fields whose names are not known in
45+
advance or are arbitrary. Wildcard indexes are *not* designed to replace
46+
workload-based index planning.
47+
48+
To learn more about designing your data model and choosing
49+
indexes, see the :manual:`Indexes
50+
</core/data-model-operations/#indexes>` section of the Operational
51+
Factors and Data Models guide in the {+mdb-server+} manual.
52+
53+
Sample Data
54+
~~~~~~~~~~~
55+
56+
The examples in this guide use the ``movies`` collection in the
57+
``sample_mflix`` database from the :atlas:`Atlas sample datasets
58+
</sample-data>`. To learn how to create a free MongoDB Atlas cluster and
59+
load the sample datasets, see the :atlas:`Get Started with Atlas
60+
</getting-started>` guide.
61+
62+
Create an Index
63+
---------------
64+
65+
MongoDB supports several index types to help query your data.
66+
The following pages describe different index types and provide sample
67+
code to programmatically create each type of index.
68+
69+
- :ref:`php-single-field-index`
70+
71+
.. - :ref:`php-compound-index`
72+
.. - :ref:`php-atlas-search-index`
73+
74+
List Indexes
75+
------------
76+
77+
You can retrieve a list of indexes on a collection by calling the
78+
``MongoDB\Collection::listIndexes()`` method:
79+
80+
.. literalinclude:: /includes/indexes/indexes.php
81+
:language: php
82+
:start-after: start-list-indexes
83+
:end-before: end-list-indexes
84+
:dedent:
85+
86+
Remove an Index
87+
---------------
88+
89+
You can remove any unused index except the default unique index on the
90+
``_id`` field.
91+
92+
The following sections provide examples that show how to remove one or
93+
more indexes from a collection.
94+
95+
Delete a Single Index
96+
~~~~~~~~~~~~~~~~~~~~~
97+
98+
Pass the name of an index to the ``MongoDB\Collection::dropIndex()``
99+
method to remove an index from a collection.
100+
101+
The following example removes the ``'_title_'`` index from the
102+
``movies`` collection:
103+
104+
.. literalinclude:: /includes/indexes/indexes.php
105+
:language: php
106+
:start-after: start-remove-index
107+
:end-before: end-remove-index
108+
:dedent:
109+
110+
.. note::
111+
112+
You cannot remove a single field from a compound index. You must
113+
drop the entire index and create a new one to update the indexed
114+
fields.
115+
116+
Delete All Indexes
117+
~~~~~~~~~~~~~~~~~~
118+
119+
You can delete all indexes by calling the
120+
``MongoDB\Collection::dropIndexes()`` method on a collection:
121+
122+
.. literalinclude:: /includes/indexes/indexes.php
123+
:language: php
124+
:start-after: start-remove-all-indexes
125+
:end-before: end-remove-all-indexes
126+
:dedent:
127+
128+
The ``dropIndexes()`` method returns information about the number of
129+
indexes removed and a success message.
130+
131+
API Documentation
132+
~~~~~~~~~~~~~~~~~
133+
134+
To learn more about any of the methods or types discussed in this
135+
guide, see the following API documentation:
136+
137+
- `MongoDB\\Collection::listIndexes() <{+api+}/method/MongoDBCollection-listIndexes/>`__
138+
- `MongoDB\\Collection::dropIndex() <{+api+}/method/MongoDBCollection-dropIndex/>`__
139+
- `MongoDB\\Collection::dropIndexes() <{+api+}/method/MongoDBCollection-dropIndexes/>`__

‎source/indexes/single-field-index.txt

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
.. _php-single-field-index:
2+
3+
====================
4+
Single Field Indexes
5+
====================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: index, query, optimization, efficiency
19+
20+
Overview
21+
--------
22+
23+
Single field indexes are indexes with a reference to a single field of a
24+
document in a collection. These indexes improve single field query and
25+
sort performance. They also support :manual:`TTL Indexes </core/index-ttl>`
26+
that automatically remove documents from a collection after a certain
27+
amount of time or at a specified clock time.
28+
29+
When creating a single-field index, you must specify the following
30+
details:
31+
32+
- The field on which to create the index
33+
- The sort order for the indexed values as either ascending or
34+
descending
35+
36+
.. note::
37+
38+
The default ``_id_`` index is an example of a single-field index.
39+
This index is automatically created on the ``_id`` field when a new
40+
collection is created.
41+
42+
Sample Data
43+
~~~~~~~~~~~
44+
45+
The examples in this guide use the ``movies`` collection in the
46+
``sample_mflix`` database from the :atlas:`Atlas sample datasets
47+
</sample-data>`. To learn how to create a free MongoDB Atlas cluster and
48+
load the sample datasets, see the :atlas:`Get Started with Atlas
49+
</getting-started>` guide.
50+
51+
Create Single-Field Index
52+
-------------------------
53+
54+
Use the ``MongoDB\Collection::createIndex()`` method to create a single
55+
field index. The following example creates an index in ascending order on the
56+
``title`` field:
57+
58+
.. literalinclude:: /includes/indexes/indexes.php
59+
:start-after: start-index-single
60+
:end-before: end-index-single
61+
:language: php
62+
:copyable:
63+
:dedent:
64+
65+
The following is an example of a query that is covered by the index
66+
created in the preceding code example:
67+
68+
.. io-code-block::
69+
:copyable: true
70+
71+
.. input:: /includes/indexes/indexes.php
72+
:start-after: start-index-single-query
73+
:end-before: end-index-single-query
74+
:language: php
75+
:dedent:
76+
77+
.. output::
78+
:visible: false
79+
80+
{"_id":...,"plot":"A musical comedy duo...",
81+
"genres":["Musical"],...,"title":"Sweethearts",...}
82+
83+
Additional Information
84+
----------------------
85+
86+
To learn more about single-field indexes, see :manual:`Single Field
87+
Indexes </core/index-single>` in the {+mdb-server+} manual.
88+
89+
API Documentation
90+
~~~~~~~~~~~~~~~~~
91+
92+
To learn more about any of the methods discussed in this guide, see the following API
93+
documentation:
94+
95+
- `MongoDB\\Collection::createIndex() <{+api+}/method/MongoDBCollection-createIndex/>`__
96+
- `MongoDB\\Collection::findOne() <{+api+}/method/MongoDBCollection-findOne/>`__

0 commit comments

Comments
 (0)