Specify Fields To Return
On this page
Overview
In this guide, you can learn how 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.
Sample Data
The examples in this guide use the restaurants
collection in the sample_restaurants
database from the Atlas sample datasets. To learn how to create a
free MongoDB Atlas cluster and load the sample datasets, see the
Get Started with Atlas guide.
The documents in this collection are modeled by the following Kotlin data class:
data class Restaurant( val id: ObjectId? = null, val name: String, val borough: String, val cuisine: String )
Projection Types
You can use a projection to specify which fields to include in a return document, or to specify which fields to exclude.
When specifying certain fields to include in a projection, all other fields are implicitly
excluded (except the _id
field, which is included by default). You cannot combine
inclusion and exclusion statements in a single projection, unless you are excluding the
_id
field.
To remove the _id
field from the returned document, you must
explicitly exclude it.
Specify Fields to Include
Use the following syntax to specify the fields to include in the result:
val projection = Projection.fields( Projections.include(<fieldName1>, <fieldName2>, ...) )
The following example uses the find()
method to find all restaurants with
the name
field value of "Emerald Pub"
. It then uses a projection to
return only the name
, cuisine
, and borough
fields of the returned
documents.
val projection = Projections.fields( Projections.include( Restaurant::name.name, Restaurant::cuisine.name, Restaurant::borough.name ) ) val results = collection .find(eq(Restaurant::name.name, "Emerald Pub")) .projection(projection) results.forEach { result -> println(result) }
Restaurant(id=5eb3d668b31de5d588f429e2, name=Emerald Pub, borough=Manhattan, cuisine=American) Restaurant(id=5eb3d668b31de5d588f432dd, name=Emerald Pub, borough=Queens, cuisine=American)
Exclude the _id
Field
When specifying fields to include, you can also exclude the _id
field from
the returned document.
The following example runs the same query as the preceding example, but
excludes the _id
field from the projection:
val projection = Projections.fields( Projections.excludeId(), Projections.include( Restaurant::name.name, Restaurant::cuisine.name, Restaurant::borough.name ) ) val results = collection .find(eq(Restaurant::name.name, "Emerald Pub")) .projection(projection) results.forEach { result -> println(result) }
Restaurant(id=null, name=Emerald Pub, borough=Manhattan, cuisine=American) Restaurant(id=null, name=Emerald Pub, borough=Queens, cuisine=American)
Additional Information
To learn more about projections, see the Project Fields guide in the MongoDB Server Manual.
API Documentation
To learn more about any of the methods or types discussed in this guide, see the following API Documentation: