From 6d1befc72fbab232e51ff44211e9920529cffeec Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 14 Aug 2024 11:28:57 -0400 Subject: [PATCH 1/6] DOCSP-41976: Projection guide --- source/includes/read/project.php | 63 ++++++++++++ source/read/project.txt | 165 +++++++++++++++++++++++++++++++ 2 files changed, 228 insertions(+) create mode 100644 source/includes/read/project.php create mode 100644 source/read/project.txt diff --git a/source/includes/read/project.php b/source/includes/read/project.php new file mode 100644 index 00000000..cbd751bc --- /dev/null +++ b/source/includes/read/project.php @@ -0,0 +1,63 @@ +'); + +// start-db-coll +$db = $client->sample_restaurants; +$collection = $db->restaurants; +// end-db-coll + +// Retrieves documents matching the "name" field query and projects their "name", "cuisine", and "borough" values +// start-project-include +$options = [ + 'projection' => [ + 'name' => 1, + 'cuisine' => 1, + 'borough' => 1, + ], +]; + +$cursor = $collection->find(['name' => 'Emerald Pub'], $options); +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-project-include + +// Retrieves documents matching the "name" field query +// and projects their "name", "cuisine", and "borough" values while excluding the "_id" values +// start-project-include-without-id +$options = [ + 'projection' => [ + '_id' => 0, + 'name' => 1, + 'cuisine' => 1, + 'borough' => 1, + ], +]; + +$cursor = $collection->find(['name' => 'Emerald Pub'], $options); +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-project-include-without-id + +// Retrieves documents matching the "name" field query and excludes their "grades" and "address" values when printing +// start-project-exclude +$options = [ + 'projection' => [ + 'grades' => 0, + 'address' => 0, + ], +]; + +$cursor = $collection->find(['name' => 'Emerald Pub'], $options); +foreach ($cursor as $doc) { + echo json_encode($doc), PHP_EOL; +} +// end-project-exclude + +?> \ No newline at end of file diff --git a/source/read/project.txt b/source/read/project.txt new file mode 100644 index 00000000..16697cdf --- /dev/null +++ b/source/read/project.txt @@ -0,0 +1,165 @@ +.. _php-project: + +======================== +Specify Fields To Return +======================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: read, filter, project, select + +Overview +-------- + +In this guide, you can learn how to use the {+php-library+} to specify which fields +to return from a read operation by using a **projection**. A projection is a document +that specifies which fields MongoDB returns from a query. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. To access this collection +from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster +and assign the following values to your ``db`` and ``collection`` variables: + +.. literalinclude:: /includes/read/project.php + :language: php + :dedent: + :start-after: start-db-coll + :end-before: end-db-coll + +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +Projection Types +---------------- + +You can use a projection to specify which fields to include in a return +document, or to specify which fields to exclude. You cannot combine inclusion and +exclusion statements in a single projection, unless you are excluding the +``_id`` field. + +Specify Fields to Include +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To specify the fields to include in the result, pass an options array to the +``MongoDB\Collection::findOne()`` or ``MongoDB\Collection::find()`` method that +sets the ``projection`` option. To set this option, use the following syntax: + +.. code-block:: php + + $options = [ + 'projection' => [ + '' => 1, + ], + ]; + +The following example creates an options array and sets the ``projection`` option +to return only the ``name``, ``cuisine``, and ``borough`` fields of matching documents. +It then calls the ``find()`` method to find all restaurants in which the ``name`` field +value is ``'Emerald Pub'``, passing the options array as a parameter to ``find()``: + +.. io-code-block:: + + .. input:: /includes/read/project.php + :start-after: start-project-include + :end-before: end-project-include + :language: php + :dedent: + + .. output:: + + { "_id" : { "$oid" : "..." }, "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub" } + { "_id" : { "$oid" : "..." }, "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub" } + +When you use a projection to specify fields to include in the return +document, the ``_id`` field is also included by default. All other fields are +implicitly excluded. To remove the ``_id`` field from the return +document, you must :ref:`explicitly exclude it `. + +.. _php-project-remove-id: + +Exclude the ``_id`` Field +~~~~~~~~~~~~~~~~~~~~~~~~~ + +When specifying fields to include, you can also exclude the ``_id`` field from +the returned document. + +The following example performs the same query as the preceding example but +excludes the ``_id`` field from the projection: + +.. io-code-block:: + + .. input:: /includes/read/project.php + :start-after: start-project-include-without-id + :end-before: end-project-include-without-id + :language: php + :dedent: + :emphasize-lines: 3 + + .. output:: + + { "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub" } + { "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub" } + +Specify Fields to Exclude +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To specify the fields to include in the result, pass an options array to the +``MongoDB\Collection::findOne()`` or ``MongoDB\Collection::find()`` method that +sets the ``projection`` option. To set this option, use the following syntax: + +.. code-block:: php + + $options = [ + 'projection' => [ + '' => 0, + ], + ]; + +The following example creates an options array and sets the ``projection`` option +to exclude the ``grades`` and ``address`` fields of matching documents. +It then calls the ``find()`` method to find all restaurants in which the ``name`` +field value is ``"Emerald Pub"``, passing the options array as a parameter to +``find()``: + +.. io-code-block:: + + .. input:: /includes/read/project.php + :start-after: start-project-exclude + :end-before: end-project-exclude + :language: php + :dedent: + + .. output:: + + { "_id" : { "$oid" : "..." }, "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub", "restaurant_id" : "40367329" } + { "_id" : { "$oid" : "..." }, "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub", "restaurant_id" : "40668598" } + +When you use a projection to specify which fields to exclude, +any unspecified fields are implicitly included in the return document. + +Additional Information +---------------------- + +To learn more about projections, see the :manual:`Project Fields +` guide in the {+mdb-server+} manual. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `MongoDB\\Collection::findOne() <{+api+}/method/MongoDBCollection-findOne/>`__ +- `MongoDB\\Collection::find() <{+api+}/method/MongoDBCollection-find/>`__ \ No newline at end of file From 892c056280d02b8c7583a90247370771e62db051 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 14 Aug 2024 11:32:25 -0400 Subject: [PATCH 2/6] edits --- snooty.toml | 1 + source/index.txt | 1 + source/read.txt | 11 +++++++++++ 3 files changed, 13 insertions(+) create mode 100644 source/read.txt diff --git a/snooty.toml b/snooty.toml index a08a8d41..507f09d6 100644 --- a/snooty.toml +++ b/snooty.toml @@ -24,3 +24,4 @@ php-library = "MongoDB PHP Library" [constants] php-library = "MongoDB PHP Library" +api = "https://www.mongodb.com/docs/php-library/current/reference" diff --git a/source/index.txt b/source/index.txt index 244f3eb2..26734024 100644 --- a/source/index.txt +++ b/source/index.txt @@ -12,6 +12,7 @@ MongoDB PHP Library Installation Get Started + /read /tutorial /upgrade /reference diff --git a/source/read.txt b/source/read.txt new file mode 100644 index 00000000..8d3b46b0 --- /dev/null +++ b/source/read.txt @@ -0,0 +1,11 @@ +.. _php-read: + +====================== +Read Data from MongoDB +====================== + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /read/project \ No newline at end of file From fd3186dc70ad5d198f0f4b6c39c358ca271155cb Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 14 Aug 2024 11:54:35 -0400 Subject: [PATCH 3/6] fixes --- snooty.toml | 1 + source/read/project.txt | 17 +++++++++++------ 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/snooty.toml b/snooty.toml index 507f09d6..d467bbde 100644 --- a/snooty.toml +++ b/snooty.toml @@ -24,4 +24,5 @@ php-library = "MongoDB PHP Library" [constants] php-library = "MongoDB PHP Library" +mdb-server = "MongoDB Server" api = "https://www.mongodb.com/docs/php-library/current/reference" diff --git a/source/read/project.txt b/source/read/project.txt index 16697cdf..a55918e9 100644 --- a/source/read/project.txt +++ b/source/read/project.txt @@ -70,7 +70,8 @@ It then calls the ``find()`` method to find all restaurants in which the ``name` value is ``'Emerald Pub'``, passing the options array as a parameter to ``find()``: .. io-code-block:: - + :copyable: + .. input:: /includes/read/project.php :start-after: start-project-include :end-before: end-project-include @@ -78,6 +79,7 @@ value is ``'Emerald Pub'``, passing the options array as a parameter to ``find() :dedent: .. output:: + :visible: false { "_id" : { "$oid" : "..." }, "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub" } { "_id" : { "$oid" : "..." }, "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub" } @@ -99,15 +101,16 @@ The following example performs the same query as the preceding example but excludes the ``_id`` field from the projection: .. io-code-block:: - + :copyable: + .. input:: /includes/read/project.php :start-after: start-project-include-without-id :end-before: end-project-include-without-id :language: php :dedent: - :emphasize-lines: 3 .. output:: + :visible: false { "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub" } { "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub" } @@ -115,7 +118,7 @@ excludes the ``_id`` field from the projection: Specify Fields to Exclude ~~~~~~~~~~~~~~~~~~~~~~~~~ -To specify the fields to include in the result, pass an options array to the +To specify the fields to exclude from the result, pass an options array to the ``MongoDB\Collection::findOne()`` or ``MongoDB\Collection::find()`` method that sets the ``projection`` option. To set this option, use the following syntax: @@ -130,11 +133,12 @@ sets the ``projection`` option. To set this option, use the following syntax: The following example creates an options array and sets the ``projection`` option to exclude the ``grades`` and ``address`` fields of matching documents. It then calls the ``find()`` method to find all restaurants in which the ``name`` -field value is ``"Emerald Pub"``, passing the options array as a parameter to +field value is ``'Emerald Pub'``, passing the options array as a parameter to ``find()``: .. io-code-block:: - + :copyable: + .. input:: /includes/read/project.php :start-after: start-project-exclude :end-before: end-project-exclude @@ -142,6 +146,7 @@ field value is ``"Emerald Pub"``, passing the options array as a parameter to :dedent: .. output:: + :visible: false { "_id" : { "$oid" : "..." }, "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub", "restaurant_id" : "40367329" } { "_id" : { "$oid" : "..." }, "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub", "restaurant_id" : "40668598" } From 99b39b9157256286cbab4114b494aa99f70dbd08 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 14 Aug 2024 13:24:09 -0400 Subject: [PATCH 4/6] code edits, output --- source/includes/read/project.php | 6 +++--- source/read/project.txt | 14 ++++++++------ 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/source/includes/read/project.php b/source/includes/read/project.php index cbd751bc..97d3dc9e 100644 --- a/source/includes/read/project.php +++ b/source/includes/read/project.php @@ -23,7 +23,7 @@ $cursor = $collection->find(['name' => 'Emerald Pub'], $options); foreach ($cursor as $doc) { - echo json_encode($doc), PHP_EOL; + echo json_encode($doc) . PHP_EOL; } // end-project-include @@ -41,7 +41,7 @@ $cursor = $collection->find(['name' => 'Emerald Pub'], $options); foreach ($cursor as $doc) { - echo json_encode($doc), PHP_EOL; + echo json_encode($doc) . PHP_EOL; } // end-project-include-without-id @@ -56,7 +56,7 @@ $cursor = $collection->find(['name' => 'Emerald Pub'], $options); foreach ($cursor as $doc) { - echo json_encode($doc), PHP_EOL; + echo json_encode($doc) . PHP_EOL; } // end-project-exclude diff --git a/source/read/project.txt b/source/read/project.txt index a55918e9..4f4f1213 100644 --- a/source/read/project.txt +++ b/source/read/project.txt @@ -81,8 +81,8 @@ value is ``'Emerald Pub'``, passing the options array as a parameter to ``find() .. output:: :visible: false - { "_id" : { "$oid" : "..." }, "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub" } - { "_id" : { "$oid" : "..." }, "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub" } + {"_id":{"$oid":"..."},"borough":"Manhattan","cuisine":"American","name":"Emerald Pub"} + {"_id":{"$oid":"..."},"borough":"Queens","cuisine":"American","name":"Emerald Pub"} When you use a projection to specify fields to include in the return document, the ``_id`` field is also included by default. All other fields are @@ -112,8 +112,8 @@ excludes the ``_id`` field from the projection: .. output:: :visible: false - { "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub" } - { "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub" } + {"borough":"Manhattan","cuisine":"American","name":"Emerald Pub"} + {"borough":"Queens","cuisine":"American","name":"Emerald Pub"} Specify Fields to Exclude ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -148,8 +148,10 @@ field value is ``'Emerald Pub'``, passing the options array as a parameter to .. output:: :visible: false - { "_id" : { "$oid" : "..." }, "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub", "restaurant_id" : "40367329" } - { "_id" : { "$oid" : "..." }, "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub", "restaurant_id" : "40668598" } + {"_id":{"$oid":"..."},"borough":"Manhattan","cuisine":"American", + "name":"Emerald Pub","restaurant_id":"40367329"} + {"_id":{"$oid":"..."},"borough":"Queens","cuisine":"American", + "name":"Emerald Pub","restaurant_id":"40668598"} When you use a projection to specify which fields to exclude, any unspecified fields are implicitly included in the return document. From ad9cf573528fd2c3c82ba27e25845f72a8af789c Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 15 Aug 2024 10:53:28 -0400 Subject: [PATCH 5/6] JS feedback --- source/read/project.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/read/project.txt b/source/read/project.txt index 4f4f1213..55386ed9 100644 --- a/source/read/project.txt +++ b/source/read/project.txt @@ -54,7 +54,7 @@ Specify Fields to Include To specify the fields to include in the result, pass an options array to the ``MongoDB\Collection::findOne()`` or ``MongoDB\Collection::find()`` method that -sets the ``projection`` option. To set this option, use the following syntax: +sets the ``projection`` option. Use the following syntax to set this option: .. code-block:: php @@ -120,7 +120,7 @@ Specify Fields to Exclude To specify the fields to exclude from the result, pass an options array to the ``MongoDB\Collection::findOne()`` or ``MongoDB\Collection::find()`` method that -sets the ``projection`` option. To set this option, use the following syntax: +sets the ``projection`` option. Use the following syntax to set this option: .. code-block:: php From 1f4beb11a2787e0daa8d809762c27388ef7c1d4f Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 19 Aug 2024 17:15:23 -0400 Subject: [PATCH 6/6] JT feedback --- source/includes/read/project.php | 10 +++------- source/includes/read/retrieve.php | 3 +-- source/read/project.txt | 2 +- source/read/retrieve.txt | 2 +- 4 files changed, 6 insertions(+), 11 deletions(-) diff --git a/source/includes/read/project.php b/source/includes/read/project.php index 97d3dc9e..1e7c42f3 100644 --- a/source/includes/read/project.php +++ b/source/includes/read/project.php @@ -2,13 +2,11 @@ require 'vendor/autoload.php'; -use MongoDB\Client; - -$client = new Client(''); +$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset'); +$client = new MongoDB\Client($uri); // start-db-coll -$db = $client->sample_restaurants; -$collection = $db->restaurants; +$collection = $client->sample_restaurants->restaurants; // end-db-coll // Retrieves documents matching the "name" field query and projects their "name", "cuisine", and "borough" values @@ -59,5 +57,3 @@ echo json_encode($doc) . PHP_EOL; } // end-project-exclude - -?> \ No newline at end of file diff --git a/source/includes/read/retrieve.php b/source/includes/read/retrieve.php index a6ee53b5..fbd64a0d 100644 --- a/source/includes/read/retrieve.php +++ b/source/includes/read/retrieve.php @@ -5,8 +5,7 @@ $client = new MongoDB\Client($uri); // start-db-coll -$db = $client->sample_training; -$collection = $db->companies; +$collection = $client->sample_training->companies; // end-db-coll // Finds one document with a "name" value of "LinkedIn" diff --git a/source/read/project.txt b/source/read/project.txt index 55386ed9..7b568185 100644 --- a/source/read/project.txt +++ b/source/read/project.txt @@ -30,7 +30,7 @@ Sample Data The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` database from the :atlas:`Atlas sample datasets `. To access this collection from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster -and assign the following values to your ``db`` and ``collection`` variables: +and assign the following value to your ``collection`` variable: .. literalinclude:: /includes/read/project.php :language: php diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index 2820e32c..cd1507db 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -31,7 +31,7 @@ Sample Data The examples in this guide use the ``companies`` collection in the ``sample_training`` database from the :atlas:`Atlas sample datasets `. To access this collection from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster -and assign the following values to your ``db`` and ``collection`` variables: +and assign the following value to your ``collection`` variable: .. literalinclude:: /includes/read/retrieve.php :language: php