Specify Documents to Return

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:

• limit: Specifies the maximum number of documents to return from a query

• sort: Specifies the sort order for the returned documents

• skip: Specifies the number of documents to skip before returning query results

• typeMap: Converts the returned documents to a specified data type

$collection = $client->sample_restaurants->restaurants;

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:

$cursor = $collection->find(
    ['cuisine' => 'Italian'],
    ['limit' => 5]
);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_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"}

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:

$cursor = $collection->find(
    ['cuisine' => 'Italian'], 
    ['sort' => ['name' => 1]]
);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_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" }

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:

$cursor = $collection->find(
    ['borough' => 'Manhattan'],
    ['skip' => 10]
);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_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"}
...

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:

$options = [
    'sort' => ['name' => 1],
    'limit' => 5,
    'skip' => 10,
];
$cursor = $collection->find(['cuisine' => 'Italian'], $options);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_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"}

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:

[
    '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.

$options = [
    'typeMap' => [
        'root' => 'array', 
        'document' => 'array'
    ]
];
$cursor = $collection->find(['cuisine' => 'Hawaiian'], $options);
foreach ($cursor as $doc) {
    print_r($doc) . PHP_EOL;
}

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 Retrieve Data guide.

For more information about specifying a query, see the Specify a Query guide.