DOCSP-41977: Specify documents to return

source/includes/read/limit-skip-sort.php

@@ -0,0 +1,76 @@
+<?php
+
+require 'vendor/autoload.php';
+
+$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
+$collection = $client->sample_restaurants->restaurants;
+// end-db-coll
+
+// Retrieves 5 documents that have a "cuisine" value of "Italian"
+// start-limit
+$cursor = $collection->find(
+    ['cuisine' => 'Italian'],
+    ['limit' => 5]
+);
+
+foreach ($cursor as $doc) {
+    echo json_encode($doc) . PHP_EOL;
+}
+// end-limit
+
+// Retrieves documents with a "cuisine" value of "Italian" and sorts in ascending "name" order
+// start-sort
+$cursor = $collection->find(
+    ['cuisine' => 'Italian'], 
+    ['sort' => ['name' => 1]]
+);
+
+foreach ($cursor as $doc) {
+    echo json_encode($doc) . PHP_EOL;
+}
+// end-sort
+
+// Retrieves documents with a "borough" value of "Manhattan" but skips the first 10 results
+// start-skip
+$cursor = $collection->find(
+    ['borough' => 'Manhattan'],
+    ['skip' => 10]
+);
+
+foreach ($cursor as $doc) {
+    echo json_encode($doc) . PHP_EOL;
+}
+// end-skip
+
+// Retrieves 5 documents with a "cuisine" value of "Italian", skips the first 10 results,
+// and sorts by ascending "name" order
+// start-limit-sort-skip
+$options = [
+    'sort' => ['name' => 1],
+    'limit' => 5,
+    'skip' => 10,
+];
+
+$cursor = $collection->find(['cuisine' => 'Italian'], $options);
+foreach ($cursor as $doc) {
+    echo json_encode($doc) . PHP_EOL;
+}
+// end-limit-sort-skip
+
+// Returns documents with a "cuisine" value of "Hawaiian" as arrays
+// start-return-type
+$options = [
+    'typeMap' => [
+        'root' => 'array', 
+        'document' => 'array'
+    ]
+];
+
+$cursor = $collection->find(['cuisine' => 'Hawaiian'], $options);
+foreach ($cursor as $doc) {
+    print_r($doc) . PHP_EOL;
+}
+// end-return-type

source/read.txt

@@ -9,6 +9,6 @@ Read Data from MongoDB
    :maxdepth: 1
 
    /read/retrieve
+   /read/specify-documents-to-return
    /read/specify-a-query
-   /read/project
-
+   /read/project

source/read/specify-documents-to-return.txt

@@ -0,0 +1,275 @@
+.. _php-specify-documents-to-return:
+
+===========================
+Specify Documents to Return
+===========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: read, paginate, pagination, order, code example
+
+Overview
+--------
+
+In this guide, you can learn how to specify which documents and which types to return
+from a read operation by passing the following options to the ``MongoDB\Collection::find()``
+or ``MongoDB\Collection::findOne()`` method:
+
+- :ref:`limit <php-return-documents-limit>`: Specifies the maximum number of documents
+  to return from a query
+- :ref:`sort <php-return-documents-sort>`: Specifies the sort order for the returned documents
+- :ref:`skip <php-return-documents-skip>`: Specifies the number of documents to skip before
+  returning query results
+- :ref:`typeMap <php-return-documents-type>`: Converts the returned documents to a specified data
+  type
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
+database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
+from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster
+and assign the following value to your ``collection`` variable:
+
+.. literalinclude:: /includes/read/limit-skip-sort.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 </getting-started>` guide.
+
+.. _php-return-documents-limit:
+
+Limit
+-----
+
+To specify the maximum number of documents returned from a read operation, create
+an array that sets the ``limit`` option and pass the array as a parameter to the
+``MongoDB\Collection::find()`` method.
+
+The following example finds all restaurants that have a ``cuisine`` field value
+of ``'Italian'`` and limits the results to ``5`` documents:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/limit-skip-sort.php
+      :start-after: start-limit
+      :end-before: end-limit
+      :language: php
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {"_id":{"$oid":"..."},...,"name":"Isle Of Capri Resturant","restaurant_id":"40364373"}
+      {"_id":{"$oid":"..."},...,"name":"Marchis Restaurant","restaurant_id":"40364668"}
+      {"_id":{"$oid":"..."},...,"name":"Crystal Room","restaurant_id":"40365013"}
+      {"_id":{"$oid":"..."},...,"name":"Forlinis Restaurant","restaurant_id":"40365098"}
+      {"_id":{"$oid":"..."},...,"name":"Angelo Of Mulberry St.","restaurant_id":"40365293"}
+
+.. tip::
+
+   The preceding example returns the first five documents matched by the query
+   according to their :manual:`natural order </reference/glossary/#std-term-natural-order>`
+   in the database. The following section describes how to return the documents
+   in a specified order.
+
+.. _php-return-documents-sort:
+
+Sort
+----
+
+To return documents in a specified order, create an array that sets the ``sort``
+option. When setting this option, include the field to sort the results by and
+the sort direction. A value of ``1`` sorts values from lowest to highest, and
+a value of ``-1`` sorts them from highest to lowest. Then, pass the array as a
+parameter to the ``MongoDB\Collection::find()`` or ``MongoDB\Collection::findOne()``
+method.
+
+The following example returns all documents that have a ``cuisine`` value of ``'Italian'``,
+sorted in ascending order of ``name`` field values:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/limit-skip-sort.php
+      :start-after: start-sort
+      :end-before: end-sort
+      :language: php
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {"_id":{"$oid":"..."},...,"name":"44 Sw Ristorante & Bar","restaurant_id":"40698807"}
+      {"_id":{"$oid":"..."},...,"name":"900 Park","restaurant_id":"41707964"}
+      {"_id":{"$oid":"..."},...,"name":"A Voce","restaurant_id":"41434084"}
+      ...
+      {"_id":{"$oid":"..."},...,"name":"Zucchero E Pomodori","restaurant_id":"41189590" }
+
+.. _php-return-documents-skip:
+
+Skip
+----
+
+To skip a specified number of documents before returning your query results, create
+an array that sets the ``skip`` option and pass the array as a parameter to the
+``MongoDB\Collection::find()`` or ``MongoDB\Collection::findOne()`` method.
+
+The following example returns all documents that have a ``borough`` field value
+of ``'Manhattan'`` and skips the first ``10`` documents:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/limit-skip-sort.php
+      :start-after: start-skip
+      :end-before: end-skip
+      :language: php
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {"_id":{"$oid":"..."},...,"name":"Cafe Metro","restaurant_id":"40363298"}
+      {"_id":{"$oid":"..."},...,"name":"Lexler Deli","restaurant_id":"40363426"}
+      {"_id":{"$oid":"..."},...,"name":"Domino'S Pizza","restaurant_id":"40363644"}
+      ...
+
+.. _php-return-documents-combine:
+
+Combine Limit, Sort, and Skip
+-----------------------------
+
+You can set the ``limit``, ``sort``, and ``skip`` options in a single
+options array and pass the array as a parameter to the read operation.
+This allows you to set a maximum number of sorted documents to return,
+skipping a specified number of documents before returning.
+
+The following example returns ``5`` documents that have a ``cuisine`` value of
+``'Italian'``. The results are sorted in ascending order by ``name`` field value,
+skipping the first ``10`` documents:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/limit-skip-sort.php
+      :start-after: start-limit-sort-skip
+      :end-before: end-limit-sort-skip
+      :language: php
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {"_id":{"$oid":"..."},...,"name":"Acqua","restaurant_id":"40871070"}
+      {"_id":{"$oid":"..."},...,"name":"Acqua Restaurant","restaurant_id":"41591488"}
+      {"_id":{"$oid":"..."},...,"name":"Acqua Santa","restaurant_id":"40735858"}
+      {"_id":{"$oid":"..."},...,"name":"Acquista Trattoria","restaurant_id":"40813992"}
+      {"_id":{"$oid":"..."},...,"name":"Acquolina Catering","restaurant_id":"41381423"}
+
+.. note::
+
+   The order in which you call these methods doesn't change the documents
+   that are returned. The {+php-library+} automatically reorders the calls to
+   perform the sort operation first, the skip operation next, and then the limit
+   operation.
+
+.. _php-return-documents-type:
+
+Specify Return Type
+-------------------
+
+To customize the data type of documents returned by a read operation, you can pass the
+``typeMap`` option in an array parameter.
+
+By default, methods called on a ``MongoDB\Client``, ``MongoDB\Database``, or ``MongoDB\Collection``
+instance use the following type map:
+
+.. code-block:: php
+
+   [
+       'array' => 'MongoDB\Model\BSONArray',
+       'document' => 'MongoDB\Model\BSONDocument',
+       'root' => 'MongoDB\Model\BSONDocument',
+   ]
+
+This default type map performs the following conversions:
+
+- Arrays to ``MongoDB\Model\BSONArray`` objects
+- Top-level and embedded BSON documents to ``MongoDB\Model\BSONDocument`` objects
+
+In a custom type map, you can specify conversions to any type that implements
+``MongoDB\BSON\Unserializable``, as well as the ``array``, ``stdClass``, and ``object``
+types.
+
+Example
+~~~~~~~
+
+The following example returns all documents that have a ``cuisine`` value of ``'Hawaiian'``
+and specifies the ``typeMap`` option to convert the documents to array values:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/limit-skip-sort.php
+      :start-after: start-return-type
+      :end-before: end-return-type
+      :language: php
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Array
+      (
+         [_id] => MongoDB\BSON\ObjectId Object
+            (
+                  [oid] => ...
+            )
+
+         [address] => Array
+            (
+                  ...
+            )
+
+         [borough] => Manhattan
+         [cuisine] => Hawaiian
+         [grades] => Array
+            (
+                  ...
+
+            )
+
+         [name] => Makana
+         [restaurant_id] => 41509012
+      )
+      ...
+
+Additional Information
+----------------------
+
+For more information about retrieving documents, see the :ref:`php-retrieve` guide.
+
+For more information about specifying a query, see the :ref:`php-specify-query` guide.
+
+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/>`__