> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # $project (aggregation stage) ## Definition Passes the documents with the requested fields to the next stage in the pipeline. The specified fields can be existing fields from the input documents or new computed fields. `$project` can: - Include fields from the input documents. - Suppress the `_id` field. - Add new fields or reset the values of existing fields. - Exclude fields from the input documents. ## Compatibility You can use `$project` for deployments hosted in the following environments: - [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud * [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB * [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB ## Syntax `$project` has the following form: ```javascript { $project: { } } ``` The `$project` specifications have the following forms: | Form | Description | | --- | --- | | `: <1 or true>` | Specifies inclusion of a field. Non-zero integers are also treated as `true`. | | `_id: <0 or false>` | Specifies suppression of the `_id` field. To exclude a field conditionally, use the [`REMOVE`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.REMOVE) variable instead. For details, see [Exclude Fields Conditionally.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#std-label-remove-var) | | `: ` | Adds a new field or resets the value of an existing field. If the expression evaluates to `$$REMOVE`, the field is excluded in the output. For details, see [Exclude Fields Conditionally.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#std-label-remove-var) | | `: <0 or false>` | Specifies exclusion of a field. To exclude a field conditionally, use the [`REMOVE`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.REMOVE) variable instead. For details, see [Exclude Fields Conditionally.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#std-label-remove-var) If you specify the exclusion of a field other than `_id`, you **cannot** use any other `$project` specification. This restriction does not apply to conditional exclusion of a field using the [`REMOVE`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.REMOVE) variable. To exclude fields, you can also use the [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) stage. | ## Behavior ### Include Fields - By default, output documents include the `_id` field. To include other fields from the input documents, specify them explicitly in `$project`. - If you specify an inclusion of a field that does not exist in the document, `$project` ignores that field inclusion and does not add the field to the document. ### \_id Field By default, the `_id` field is included in the output documents. To exclude the `_id` field from the output documents, you must explicitly suppress the `_id` field in `$project`. ### Exclude Fields If you exclude a field, all other fields appear in the output documents. ```javascript { $project: { "": 0, "": 0, ... } } // Return all but the specified fields ``` If you exclude a field other than `_id`, you cannot use other `$project` specification forms. If you exclude fields, you cannot also specify the inclusion of fields, reset the value of existing fields, or add new fields. This restriction does not apply to conditional exclusion of a field using the [`REMOVE`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.REMOVE) variable. To exclude fields, you can also use [`$unset`.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) ### Exclude Fields Conditionally You can use the variable [`REMOVE`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.REMOVE) in aggregation expressions to conditionally suppress a field. For an example, see [Conditionally Exclude Fields.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#std-label-remove-example) ### Add New Fields or Reset Existing Fields **Note:** MongoDB also provides [`$addFields`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/addfields.md#mongodb-pipeline-pipe.-addFields) to add new fields to the documents. To add a new field or to reset the value of an existing field, specify the field name and set its value to an expression. For more information on expressions, see [Expressions.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) #### Literal Values To set a field to a numeric or boolean literal rather than an expression that resolves to a literal, use the [`$literal`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/literal.md#mongodb-expression-exp.-literal) operator. Otherwise, `$project` treats the literal as a flag for including or excluding the field. #### Field Rename By specifying a new field and setting its value to the field path of an existing field, you can effectively rename a field. #### New Array Fields The `$project` stage supports using the square brackets `[]` to directly create new array fields. If you specify array fields that do not exist in a document, the operation substitutes `null` as the value for that field. For an example, see [Project New Array Fields.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#std-label-example-project-new-array-fields) You cannot use an array index with the [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage. ### Embedded Document Fields To project, add, or reset a field within an embedded document, you can use [dot notation:](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) ```javascript "contact.address.country": <1 or 0 or expression> ``` You can also nest the fields: ```javascript contact: { address: { country: <1 or 0 or expression> } } ``` When you nest fields, you *cannot* use dot notation inside the embedded document to specify the field. For example, `contact: { "address.country": <1 or 0 or expression> }` is *invalid*. ### Path Collision Errors in Embedded Fields You cannot specify both an embedded document and a field within that embedded document in the same projection. The following `$project` stage fails with a `Path collision` error because it attempts to project both the embedded `contact` document and the `contact.address.country` field: ```javascript { $project: { contact: 1, "contact.address.country": 1 } } ``` The error occurs regardless of the order in which you specify the parent and embedded field. The following `$project` fails with the same error: ```javascript { $project: { "contact.address.country": 1, contact: 1 } } ``` ### $project Stage Placement When you use a `$project` stage it should typically be the last stage in your pipeline, used to specify which fields to return to the client. Using a `$project` stage at the beginning or middle of a pipeline to reduce the number of fields passed to subsequent pipeline stages is unlikely to improve performance, because the database performs this optimization automatically. ### Empty Specification MongoDB returns an error if the `$project` stage is passed an empty document. For example, the following pipeline returns an error: ```javascript db.myCollection.aggregate( [ { $project: { } } ] ) ``` ### Array Index You cannot use an array index with the [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage. ## Examples The examples on this page use data from the [sample\_mflix dataset](https://www.mongodb.com/docs/manual/sample-data/sample-mflix.md#std-label-sample-mflix). For details on how to load this dataset into your self-managed MongoDB deployment, see [Load the Sample Dataset](https://www.mongodb.com/docs/manual/sample-data/load-sample-data-local.md#std-label-sample-dataset-local). If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page. ### MongoDB Shell ### Include Specific Fields in Output Documents The following `$project` stage includes only the `_id`, `title`, and `rated` fields: ```javascript db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { title: 1, rated: 1 } }, { $limit: 1 } ] ) ``` **Output:** ```javascript [ { _id: ObjectId('573a1390f29313caabcd42e8'), title: 'The Great Train Robbery', rated: 'TV-G' } ] ``` ### Suppress \_id Field in the Output Documents MongoDB includes the `_id` field by default. To exclude the `_id` field from the `$project` stage, set the `_id` field to `0` in the projection document. The following `$project` stage excludes the `_id` field but includes the `title` and `rated` fields: ```javascript db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project : { _id: 0, title : 1, rated : 1 } }, { $limit: 1 } ] ) ``` **Output:** ```javascript [ { title: 'The Great Train Robbery', rated: 'TV-G' } ] ``` ### Exclude Fields from Output Documents The following `$project` stage excludes the `rated` field from the output: ```javascript db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project : { "rated": 0 } }, { $limit: 1 } ] ) ``` Alternatively, use the [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) stage to exclude fields. ### Exclude Fields from Embedded Documents The following `$project` stage excludes the `imdb.id` and `type` fields from the output: ```javascript db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { "imdb.id": 0, "type": 0 } }, { $limit: 1 } ] ) ``` **Output:** ```javascript [ { _id: ObjectId('573a1390f29313caabcd42e8'), plot: 'A group of bandits stage a brazen train hold-up, only to find a determined posse hot on their heels.', genres: [ 'Short', 'Western' ], runtime: 11, cast: [ 'A.C. Abadie', "Gilbert M. 'Broncho Billy' Anderson", 'George Barnes', 'Justus D. Barnes' ], poster: 'https://m.media-amazon.com/images/M/MV5BMTU3NjE5NzYtYTYyNS00MDVmLWIwYjgtMmYwYWIxZDYyNzU2XkEyXkFqcGdeQXVyNzQzNzQxNzI@._V1_SY1000_SX677_AL_.jpg', title: 'The Great Train Robbery', fullplot: "Among the earliest existing films in American cinema - notable as the first film that presented a narrative story to tell - it depicts a group of cowboy outlaws who hold up a train and rob the passengers. They are then pursued by a Sheriff's posse. Several scenes have color included - all hand tinted.", languages: [ 'English' ], released: ISODate('1903-12-01T00:00:00.000Z'), directors: [ 'Edwin S. Porter' ], rated: 'TV-G', awards: { wins: 1, nominations: 0, text: '1 win.' }, lastupdated: '2015-08-13 00:27:59.177000000', year: 1903, imdb: { rating: 7.4, votes: 9847 }, countries: [ 'USA' ], tomatoes: { viewer: { rating: 3.7, numReviews: 2559, meter: 75 }, fresh: 6, critic: { rating: 7.6, numReviews: 6, meter: 100 }, rotten: 0, lastUpdated: ISODate('2015-08-08T19:16:10.000Z') }, num_mflix_comments: 0 } ] ``` Alternatively, you can nest the exclusion specification in a document: ```javascript db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { "imdb": { "id": 0 }, "type" : 0 } }, { $limit: 1 } ] ) ``` **Output:** ```javascript [ { _id: ObjectId('573a1390f29313caabcd42e8'), plot: 'A group of bandits stage a brazen train hold-up, only to find a determined posse hot on their heels.', genres: [ 'Short', 'Western' ], runtime: 11, cast: [ 'A.C. Abadie', "Gilbert M. 'Broncho Billy' Anderson", 'George Barnes', 'Justus D. Barnes' ], poster: 'https://m.media-amazon.com/images/M/MV5BMTU3NjE5NzYtYTYyNS00MDVmLWIwYjgtMmYwYWIxZDYyNzU2XkEyXkFqcGdeQXVyNzQzNzQxNzI@._V1_SY1000_SX677_AL_.jpg', title: 'The Great Train Robbery', fullplot: "Among the earliest existing films in American cinema - notable as the first film that presented a narrative story to tell - it depicts a group of cowboy outlaws who hold up a train and rob the passengers. They are then pursued by a Sheriff's posse. Several scenes have color included - all hand tinted.", languages: [ 'English' ], released: ISODate('1903-12-01T00:00:00.000Z'), directors: [ 'Edwin S. Porter' ], rated: 'TV-G', awards: { wins: 1, nominations: 0, text: '1 win.' }, lastupdated: '2015-08-13 00:27:59.177000000', year: 1903, imdb: { rating: 7.4, votes: 9847 }, countries: [ 'USA' ], tomatoes: { viewer: { rating: 3.7, numReviews: 2559, meter: 75 }, fresh: 6, critic: { rating: 7.6, numReviews: 6, meter: 100 }, rotten: 0, lastUpdated: ISODate('2015-08-08T19:16:10.000Z') }, num_mflix_comments: 0 } ] ``` Alternatively, use the [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) stage to exclude fields. ### Conditionally Exclude Fields You can use the variable [`REMOVE`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.REMOVE) in aggregation expressions to conditionally suppress a field. The following `$project` stage uses the [`REMOVE`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.REMOVE) variable to exclude the `imdb.votes` field if it equals `null` or is an empty string: ```javascript db.movies.aggregate( [ { $match: { title: "This Is Spinal Tap" } }, { $project: { title: 1, "imdb.rating": 1, "imdb.id": 1, "imdb.votes": { $cond: { if: { $in: [ "$imdb.votes", [ null, "" ] ] }, then: "$$REMOVE", else: "$imdb.votes" } } } }, { $limit: 1 } ] ) ``` **Output:** ```javascript [ { _id: ObjectId('573a1398f29313caabce94a3'), title: 'This Is Spinal Tap', imdb: { rating: 8, id: 88258 } } ] ``` Because `imdb.votes` is an empty string for this document, MongoDB excludes the field from the output. **Tip: Comparison with $addFields** You can use either the `$addFields` or `$project` stage to remove document fields. The best approach depends on your pipeline and how much of the original document you want to retain. To see an example using `$$REMOVE` in an `$addFields` stage, see [Remove Fields.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/addfields.md#std-label-addFields-remove-example) ### Include Specific Fields from Embedded Documents Documents in the `movies` collection contain an embedded `imdb` document with the `rating`, `votes`, and `id` fields. To include only the `rating` field from the `imdb` document, use [dot notation:](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation) ```javascript db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { "imdb.rating": 1 } }, { $limit: 1 } ] ) ``` **Output:** ```javascript [ { _id: ObjectId('573a1390f29313caabcd42e8'), imdb: { rating: 7.4 } } ] ``` Or, nest the inclusion specification in a document: ```javascript db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { imdb: { rating: 1 } } }, { $limit: 1 } ] ) ``` **Output:** ```javascript [ { _id: ObjectId('573a1390f29313caabcd42e8'), imdb: { rating: 7.4 } } ] ``` ### Include Computed Fields The following `$project` stage adds the `leadActor` and `releaseYear` fields: ```javascript db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { title: 1, leadActor: { $arrayElemAt: [ "$cast", 0 ] }, releaseYear: "$year" } }, { $limit: 1 } ] ) ``` **Output:** ```javascript [ { _id: ObjectId('573a1390f29313caabcd42e8'), title: 'The Great Train Robbery', leadActor: 'A.C. Abadie', releaseYear: 1903 } ] ``` ### Project New Array Fields The following operation projects the `year` and `runtime` fields as elements in a new `myArray` field: ```javascript db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { myArray: [ "$year", "$runtime" ] } }, { $limit: 1 } ] ) ``` **Output:** ```javascript [ { _id: ObjectId('573a1390f29313caabcd42e8'), myArray: [ 1903, 11 ] } ] ``` If the array specification includes fields that are non-existent in a document, the operation substitutes `null` as the value for that field. For example, with the same document as above, the following operation projects the fields `year`, `runtime`, and a non-existing field `$someField` as elements in a new field `myArray`: ```javascript db.movies.aggregate( [ { $match: { title: "The Great Train Robbery" } }, { $project: { myArray: [ "$year", "$runtime", "$someField" ] } }, { $limit: 1 } ] ) ``` **Output:** ```javascript [ { _id: ObjectId('573a1390f29313caabcd42e8'), myArray: [ 1903, 11, null ] } ] ``` ## Learn More For more information about common aggregation tasks, see [Complete Aggregation Pipeline Tutorials.](https://www.mongodb.com/docs/manual/tutorial/aggregation-complete-examples.md#std-label-aggregation-complete-examples) To learn more about the expressions and variables on this page, see: - [`$eq`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/eq.md#mongodb-expression-exp.-eq) - [`$cond`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/cond.md#mongodb-expression-exp.-cond) - [`$arrayElemAt`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/arrayelemat.md#mongodb-expression-exp.-arrayElemAt) - [`$concatArrays`](https://www.mongodb.com/docs/manual/reference/expression/concatarrays.md#mongodb-expression-exp.-concatArrays) - [`REMOVE`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.REMOVE)