Skip to content

Commit 706a25f

Browse files
norareidynorareidy
committed
Merge remote-tracking branch 'upstream/php-standardization' into DOCSP-41972-gridfs
2 parents e1f1190 + 54c05bf commit 706a25f

File tree

12 files changed

+783
-8
lines changed

12 files changed

+783
-8
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ toc_landing_pages = [
1818
"/reference/class/MongoDBModelDatabaseInfo",
1919
"/reference/class/MongoDBModelIndexInfo",
2020
"/get-started",
21+
"/write",
2122
]
2223

2324
[substitutions]

‎source/includes/indexes/indexes.php

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
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
33+
34+
// start-multikey
35+
$indexName = $collection->createIndex(['cast' => 1]);
36+
// end-multikey
37+
38+
// start-index-array-query
39+
$document = $collection->findOne(
40+
['cast' => ['$in' => ['Aamir Khan', 'Kajol']]]
41+
);
42+
echo json_encode($document), PHP_EOL;
43+
// end-index-array-query

‎source/includes/usage-examples/index-code-examples.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ function toJSON(object $document): string
3838

3939
// start-search-list
4040
foreach ($collection->listSearchIndexes() as $indexInfo) {
41-
echo toJSON($indexInfo) , PHP_EOL;
41+
echo toJSON($indexInfo), PHP_EOL;
4242
}
4343
// end-search-list
4444

‎source/includes/usage-examples/write-code-examples.php

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
<?php
2+
require 'vendor/autoload.php';
3+
4+
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
5+
$client = new MongoDB\Client($uri);
6+
$collection = $client->db->coll;
7+
8+
// Inserts one document that stores the specified values
9+
// start-insert-one
10+
$result = $collection->insertOne([
11+
'<field name 1>' => '<value 1>',
12+
'<field name 2>' => '<value 2>',
13+
]);
14+
// end-insert-one
15+
16+
// Inserts multiple documents that store the specified values
17+
// start-insert-multiple
18+
$result = $collection->insertMany(
19+
[
20+
'<field name 1>' => '<value 1>',
21+
'<field name 2>' => '<value 2>',
22+
],
23+
[
24+
'<field name 1>' => '<value 1>',
25+
'<field name 2>' => '<value 2>',
26+
],
27+
);
28+
// end-insert-multiple
29+
30+
// Updates a document that matches the specified criteria
31+
// start-update-one
32+
$result = $collection->updateOne(
33+
['<field to match>' => '<value to match>'],
34+
['$set' => ['<field name>' => '<value>']],
35+
);
36+
// end-update-one
37+
38+
// Updates all documents that match the specified criteria
39+
// start-update-multiple
40+
$result = $collection->updateMany(
41+
['<field to match>' => '<value to match>'],
42+
['$set' => ['<field name>' => '<value>']],
43+
);
44+
// end-update-multiple
45+
46+
// start-replace-one
47+
$result = $collection->replaceOne(
48+
['<field to match>' => '<value to match>'],
49+
[
50+
'<new field 1>' => '<value 1>',
51+
'<new field 2>' => '<value 2>',
52+
],
53+
);
54+
// end-replace-one
55+
56+
// Deletes a document that matches the specified criteria
57+
// start-delete-one
58+
$result = $collection->deleteOne(['<field name>' => '<value>']);
59+
// end-delete-one
60+
61+
// Deletes all documents that match the specified criteria
62+
// start-delete-multiple
63+
$result = $collection->deleteMany(['<field name>' => '<value>']);
64+
// end-delete-multiple
65+
66+
// Runs a bulk operation based on the instructions in each array entry
67+
// start-bulk-write
68+
$result = $collection->bulkWrite(
69+
[
70+
[
71+
'insertOne' => [
72+
['<field name>' => '<value>'],
73+
],
74+
],
75+
[
76+
'replaceOne' => [
77+
['<field to match>' => '<value to match>'],
78+
[
79+
'<first new field>' => '<value>',
80+
'<second new field>' => '<value>',
81+
],
82+
],
83+
],
84+
[
85+
'updateOne' => [
86+
['<field to match>' => '<value to match>'],
87+
['$set' => ['<field to update>' => '<value to update>']],
88+
],
89+
],
90+
[
91+
'updateMany' => [
92+
['<field to match>' => '<value to match>'],
93+
['$set' => ['<field to update>' => '<value to update>']],
94+
],
95+
],
96+
[
97+
'deleteOne' => [
98+
['<field name>' => '<value>'],
99+
],
100+
],
101+
[
102+
'deleteMany' => [
103+
['<field name>' => '<value>'],
104+
],
105+
],
106+
]
107+
);
108+
// end-bulk-write
109+
110+
// Stores a file in a GridFS bucket and writes data to the file
111+
// start-gridfs-upload
112+
$bucket = $client->selectDatabase('<database name>')->selectGridFSBucket();
113+
$stream = $bucket->openUploadStream('<file name>');
114+
fwrite($stream, '<data>');
115+
fclose($stream);
116+
// end-gridfs-upload

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ MongoDB PHP Library
1515
/write
1616
/aggregation
1717
/indexes
18+
/security
1819
/tutorial
1920
/upgrade
2021
/reference

‎source/indexes.txt

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,13 @@ 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
27+
/indexes/multikey-index
2628

2729
Overview
2830
--------
@@ -106,8 +108,8 @@ specified array-valued field:
106108
:copyable:
107109
:dedent:
108110

109-
.. TODO To learn more about multikey indexes, see the :ref:`php-multikey-index`
110-
.. guide.
111+
To learn more about multikey indexes, see the :ref:`php-multikey-index`
112+
guide.
111113

112114
Geospatial Index
113115
----------------

‎source/indexes/index-mgmt.txt

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
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+
- :ref:`php-multikey-index`
71+
72+
.. - :ref:`php-compound-index`
73+
.. - :ref:`php-atlas-search-index`
74+
75+
List Indexes
76+
------------
77+
78+
You can retrieve a list of indexes on a collection by calling the
79+
``MongoDB\Collection::listIndexes()`` method:
80+
81+
.. literalinclude:: /includes/indexes/indexes.php
82+
:language: php
83+
:start-after: start-list-indexes
84+
:end-before: end-list-indexes
85+
:dedent:
86+
87+
Remove an Index
88+
---------------
89+
90+
You can remove any unused index except the default unique index on the
91+
``_id`` field.
92+
93+
The following sections provide examples that show how to remove one or
94+
more indexes from a collection.
95+
96+
Delete a Single Index
97+
~~~~~~~~~~~~~~~~~~~~~
98+
99+
Pass the name of an index to the ``MongoDB\Collection::dropIndex()``
100+
method to remove an index from a collection.
101+
102+
The following example removes the ``'_title_'`` index from the
103+
``movies`` collection:
104+
105+
.. literalinclude:: /includes/indexes/indexes.php
106+
:language: php
107+
:start-after: start-remove-index
108+
:end-before: end-remove-index
109+
:dedent:
110+
111+
.. note::
112+
113+
You cannot remove a single field from a compound index. You must
114+
drop the entire index and create a new one to update the indexed
115+
fields.
116+
117+
Delete All Indexes
118+
~~~~~~~~~~~~~~~~~~
119+
120+
You can delete all indexes by calling the
121+
``MongoDB\Collection::dropIndexes()`` method on a collection:
122+
123+
.. literalinclude:: /includes/indexes/indexes.php
124+
:language: php
125+
:start-after: start-remove-all-indexes
126+
:end-before: end-remove-all-indexes
127+
:dedent:
128+
129+
The ``dropIndexes()`` method returns information about the number of
130+
indexes removed and a success message.
131+
132+
API Documentation
133+
~~~~~~~~~~~~~~~~~
134+
135+
To learn more about any of the methods or types discussed in this
136+
guide, see the following API documentation:
137+
138+
- :phpmethod:`MongoDB\Collection::listIndexes()`
139+
- :phpmethod:`MongoDB\Collection::dropIndex()`
140+
- :phpmethod:`MongoDB\Collection::dropIndexes()`

0 commit comments

Comments
 (0)