Docs Menu
Docs Home
/ / /
PHP Library Manual
/

Specify Fields To Return

On this page

  • Overview
  • Sample Data
  • Projection Types
  • Specify Fields to Include
  • Exclude the _id Field
  • Specify Fields to Exclude
  • Additional Information
  • API Documentation

In this guide, you can learn how to use the MongoDB PHP Library to specify which fields to return from a read operation by using a projection. A projection is a document that specifies which fields MongoDB returns from a query.

The examples in this guide use the restaurants collection in the sample_restaurants database from the 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:

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

To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.

You can use a projection to specify which fields to include in a return document, or to specify which fields to exclude. You cannot combine inclusion and exclusion statements in a single projection, unless you are excluding the _id field.

To specify the fields to include in the result, pass an options array to the MongoDB\Collection::findOne() or MongoDB\Collection::find() method that sets the projection option. Use the following syntax to set this option:

$options = [
'projection' => [
'<field name>' => 1,
],
];

The following example creates an options array and sets the projection option to return only the name, cuisine, and borough fields of matching documents. It then calls the find() method to find all restaurants in which the name field value is 'Emerald Pub', passing the options array as a parameter to find():

$options = [
'projection' => [
'name' => 1,
'cuisine' => 1,
'borough' => 1,
],
];
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
foreach ($cursor as $doc) {
echo json_encode($doc), PHP_EOL;
}
{"_id":{"$oid":"..."},"borough":"Manhattan","cuisine":"American","name":"Emerald Pub"}
{"_id":{"$oid":"..."},"borough":"Queens","cuisine":"American","name":"Emerald Pub"}

When you use a projection to specify fields to include in the return document, the _id field is also included by default. All other fields are implicitly excluded. To remove the _id field from the return document, you must explicitly exclude it.

When specifying fields to include, you can also exclude the _id field from the returned document.

The following example performs the same query as the preceding example but excludes the _id field from the projection:

$options = [
'projection' => [
'_id' => 0,
'name' => 1,
'cuisine' => 1,
'borough' => 1,
],
];
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
foreach ($cursor as $doc) {
echo json_encode($doc), PHP_EOL;
}
{"borough":"Manhattan","cuisine":"American","name":"Emerald Pub"}
{"borough":"Queens","cuisine":"American","name":"Emerald Pub"}

To specify the fields to exclude from the result, pass an options array to the MongoDB\Collection::findOne() or MongoDB\Collection::find() method that sets the projection option. Use the following syntax to set this option:

$options = [
'projection' => [
'<field name>' => 0,
],
];

The following example creates an options array and sets the projection option to exclude the grades and address fields of matching documents. It then calls the find() method to find all restaurants in which the name field value is 'Emerald Pub', passing the options array as a parameter to find():

$options = [
'projection' => [
'grades' => 0,
'address' => 0,
],
];
$cursor = $collection->find(['name' => 'Emerald Pub'], $options);
foreach ($cursor as $doc) {
echo json_encode($doc), PHP_EOL;
}
{"_id":{"$oid":"..."},"borough":"Manhattan","cuisine":"American",
"name":"Emerald Pub","restaurant_id":"40367329"}
{"_id":{"$oid":"..."},"borough":"Queens","cuisine":"American",
"name":"Emerald Pub","restaurant_id":"40668598"}

When you use a projection to specify which fields to exclude, any unspecified fields are implicitly included in the return document.

To learn more about projections, see the Project Fields guide in the MongoDB Server manual.

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

  • MongoDB\Collection::findOne()

  • MongoDB\Collection::find()

Back

Retrieve Data