DOCSP-41977: Specify documents to return

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"

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

@@ -0,0 +1,63 @@
+<?php
+
+require 'vendor/autoload.php';
+
+$client = new MongoDB\Client('<connection string>');
+
+// start-db-coll
+$db = $client->sample_restaurants;
+$collection = $db->restaurants;
+// end-db-coll
+
+// Retrieves 5 documents that have a "cuisine" value of "Italian"
+// start-limit
+$options = [
+    'limit' => 5,
+];
+$cursor = $collection->find(['cuisine' => 'Italian'], $options);
+
+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
+$options = [
+    'sort' => ['name' => 1],
+];
+
+$cursor = $collection->find(['cuisine' => 'Italian'], $options);
+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
+$options = [
+    'skip' => 10,
+];
+
+$cursor = $collection->find(['borough' => 'Manhattan'], $options);
+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
+
+?>

source/index.txt

@@ -12,6 +12,7 @@ MongoDB PHP Library
 
    Installation </tutorial/install-php-library>
    Get Started </get-started>
+   /read
    /tutorial
    /upgrade
    /reference

source/read.txt

@@ -0,0 +1,11 @@
+.. _php-read:
+
+======================
+Read Data from MongoDB
+======================
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   /read/specify-documents-to-return

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

@@ -0,0 +1,202 @@
+.. _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 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.
+
+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 values to your ``db`` and ``collection`` variables:
+
+.. 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.
+
+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/>`__