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;
}

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;
}

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;
}

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;
}

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;
}

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.