diff --git a/source/includes/read/limit-skip-sort.php b/source/includes/read/limit-skip-sort.php new file mode 100644 index 00000000..3ab8a16f --- /dev/null +++ b/source/includes/read/limit-skip-sort.php @@ -0,0 +1,76 @@ +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 diff --git a/source/read.txt b/source/read.txt index 5cc0e838..a3f245ca 100644 --- a/source/read.txt +++ b/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 \ No newline at end of file diff --git a/source/read/specify-documents-to-return.txt b/source/read/specify-documents-to-return.txt new file mode 100644 index 00000000..4497569f --- /dev/null +++ b/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 `: Specifies the maximum number of documents + to return from a query +- :ref:`sort `: Specifies the sort order for the returned documents +- :ref:`skip `: Specifies the number of documents to skip before + returning query results +- :ref:`typeMap `: 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 `. 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 ` 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 ` + 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/>`__