project.txt

.. _golang-project:

==============================
Specify Which Fields to Return
==============================

.. facet::
   :name: genre
   :values: reference

.. meta::
   :keywords: read, code example, pipeline stage, customize output
   :description: Learn how to specify which fields to return in MongoDB documents using projections in Go, including examples for including or excluding fields.

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

Overview
--------

In this guide, you can learn how to specify which fields to return in a
document.

Sample Data
~~~~~~~~~~~

The examples in this guide use the following ``Course`` struct as a model for documents
in the ``courses`` collection:

.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/projection.go
   :start-after: start-course-struct
   :end-before: end-course-struct
   :language: go
   :dedent:

The ``omitempty`` :ref:`struct tag<golang-struct-tags>` directs the
driver to exclude fields when unmarshalling based on your projection
specification.

To run the examples in this guide, load the sample data into the
``db.courses`` collection with the following snippet:

.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/projection.go
   :language: go
   :dedent:
   :start-after: begin insertDocs
   :end-before: end insertDocs

.. include:: /includes/fundamentals/automatic-db-coll-creation.rst

Each document contains a description of a university course that
includes the course title, course ID, and maximum enrollment, corresponding to
the ``title``, ``course_id``, and ``enrollment`` fields in each document.

Projection
----------

A projection specifies which fields to return in matched documents. The
projection document contains field names with a ``1`` to include the
corresponding field or ``0`` to exclude it. If you are using an aggregation framework,
you can also specify a projection to include newly computed fields.

You can specify a projection by passing a projection document to the ``SetProjection()``
method. The following operations take an options object as a parameter:

- ``Find()``
- ``FindOne()``
- ``FindOneAndDelete()``
- ``FindOneAndReplace()``
- ``FindOneAndUpdate()``

.. tip::

   If you don't specify a projection, the operation returns all
   the fields in matched documents.

Exclude a Field
~~~~~~~~~~~~~~~

To exclude a field, pass the field you want to exclude with a ``0`` to
the ``SetProjection()`` method. The driver includes all fields that are
not explicitly excluded in the projection document, if you specify any
fields to exclude.

Example
```````

The following example excludes the ``course_id`` and ``enrollment``
fields from the matched documents returned by the ``Find()`` method:

.. io-code-block::
   :copyable: true

   .. input::
      :language: go

      filter := bson.D{}
      opts := options.Find().SetProjection(bson.D{{"course_id", 0}, {"enrollment", 0}})
      
      cursor, err := coll.Find(context.TODO(), filter, opts)
      if err != nil {
          panic(err)
      }
      
      var results []Course
      if err = cursor.All(context.TODO(), &results); err != nil {
          panic(err)
      }

      for _, result := range results {
          res, _ := bson.MarshalExtJSON(result, false, false)
          fmt.Println(string(res))
      }

   .. output::
      :language: none
      :visible: false

      {"title":"Primate Behavior"}
      {"title":"Revolution and Reform"}

Include a Field
~~~~~~~~~~~~~~~

To include a field, pass the field you want to include with a ``1`` to
the ``SetProjection()`` method. The driver excludes all fields that are
not explicitly included in the projection document, if you specify any
fields to include.

.. _golang-include-projection:

Example
```````

The following example includes only the ``title`` and ``enrollment`` fields
from the matched documents returned by the ``Find()`` method:

.. io-code-block::
   :copyable: true

   .. input::
      :language: go

      filter := bson.D{}
      opts := options.Find().SetProjection(bson.D{{"title", 1}, {"enrollment", 1}})
      
      cursor, err := coll.Find(context.TODO(), filter, opts)
      if err != nil {
          panic(err)
      }
      
      var results []Course
      if err = cursor.All(context.TODO(), &results); err != nil {
          panic(err)
      }
      for _, result := range results {
          res, _ := bson.MarshalExtJSON(result, false, false)
          fmt.Println(string(res))
      }

   .. output::
      :language: none
      :visible: false

      {"title":"Primate Behavior","enrollment":40}
      {"title":"Revolution and Reform","enrollment":12}

Aggregation
~~~~~~~~~~~

You can also create a :manual:`$project </reference/operator/aggregation/project/>`
stage to specify a projection in an aggregation pipeline.

Example
```````

The following example includes only the ``title`` and ``course_id`` fields
from the matched documents returned by the ``Aggregate()`` method:

.. io-code-block::
   :copyable: true

   .. input::
      :language: go

      projectStage := bson.D{{"$project", bson.D{{"title", 1}, {"course_id", 1}}}}
      
      cursor, err := coll.Aggregate(context.TODO(), mongo.Pipeline{projectStage})
      if err != nil {
          panic(err)
      }
      
      var results []Course
      if err = cursor.All(context.TODO(), &results); err != nil {
          panic(err)
      }
      for _, result := range results {
          res, _ := bson.MarshalExtJSON(result, false, false)
          fmt.Println(string(res))
      }

   .. output::
      :language: none
      :visible: false

      {"title":"Primate Behavior","course_id":"PSY2030"}
      {"title":"Revolution and Reform","course_id":"HIST3080"}

Additional Information
----------------------

To learn more about the operations mentioned, see the following
guides:

- :ref:`golang-query-document`
- :ref:`golang-retrieve`
- :ref:`golang-compound-operations`
- :ref:`golang-aggregation`

To learn about projecting text scores from your text search, see :ref:`golang-search-text`.

API Documentation
~~~~~~~~~~~~~~~~~

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

- `Find() <{+api+}/mongo#Collection.Find>`__
- `FindOptionsBuilder.SetProjection() <{+api+}/mongo/options#FindOptionsBuilder.SetProjection>`__
- `FindOne() <{+api+}/mongo#Collection.FindOne>`__
- `FindOneAndDelete() <{+api+}/mongo#Collection.FindOneAndDelete>`__
- `FindOneAndReplace() <{+api+}/mongo#Collection.FindOneAndReplace>`__
- `FindOneAndUpdate() <{+api+}/mongo#Collection.FindOneAndUpdate>`__
- `Aggregate() <{+api+}/mongo#Collection.Aggregate>`__