limit.txt

.. _golang-limit:

====================================
Limit the Number of Returned Results
====================================

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

.. meta::
   :keywords: read operation, code example, pipeline, customize output
   :description: Learn how to limit the number of documents returned in MongoDB read operations using the Go driver, including examples with sorting and aggregation.

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

Overview
--------

In this guide, you can learn how to limit the number of documents
returned from a read operation.

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/limit.go
   :start-after: start-course-struct
   :end-before: end-course-struct
   :language: go
   :dedent:

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/limit.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 and maximum enrollment, corresponding to
the ``title`` and ``enrollment`` fields in each document.

Limit
-----

To limit the number of documents returned from a query, pass the
number of documents you want returned to the ``SetLimit()`` method of
the read operation's options.

The following read operations take an options object as a parameter:

- ``Find()``
- ``CountDocuments()``
- ``GridFSBucket.Find()``

If the limit is ``0`` or exceeds the number of matched
documents, the method returns all the documents. If the limit is a
negative number, the method uses the absolute value of the negative
number as the limit and closes the cursor after retrieving
documents.

Example
~~~~~~~

The following example shows how to return two documents that have an
``enrollment`` field value greater than 20:

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

   .. input::
      :language: go

      filter := bson.D{{"enrollment", bson.D{{"$gt", 20}}}}
      opts := options.Find().SetLimit(2)
      
      cursor, err := coll.Find(context.TODO(), filter, opts)
      
      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":"Concepts in Topology","enrollment":35}
      {"title":"Ancient Greece","enrollment":100}

Multiple Options
----------------

The driver performs the limit behavior last regardless of the order in which you set
any other options.

Example
~~~~~~~

The following example performs a ``Find()`` operation with the following behavior:

- Sorts the results in descending order on the ``enrollment`` field
- Skips the first document
- Returns the first two of the remaining documents

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

   .. input::
      :language: go

      filter := bson.D{}
      opts := options.Find().SetSort(bson.D{{"enrollment", -1}}).SetLimit(2).SetSkip(1)
      
      cursor, err := coll.Find(context.TODO(), filter, opts)
      
      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":"Physiology I","enrollment":60}
      {"title":"Concepts in Topology","enrollment":35}

.. tip::

   Using any of the following option configurations also produces the same result:

   .. code-block:: go
      :copyable: false

      opts := options.Find().SetSort(bson.D{{"enrollment", -1}}).SetSkip(1).SetLimit(2)
      opts := options.Find().SetLimit(2).SetSort(bson.D{{"enrollment", -1}}).SetSkip(1)
      opts := options.Find().SetLimit(2).SetSkip(1).SetSort(bson.D{{"enrollment", -1}})
      opts := options.Find().SetSkip(1).SetSort(bson.D{{"enrollment", -1}}).SetLimit(2)
      opts := options.Find().SetSkip(1).SetLimit(2).SetSort(bson.D{{"enrollment", -1}})

.. _golang-limit-aggregation:

Aggregation
-----------

You can also include the :manual:`$limit </reference/operator/aggregation/limit/>`
stage to specify a limit in an aggregation pipeline.

Example
~~~~~~~

The following example shows how to return three documents:

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

   .. input::
      :language: go

      limitStage := bson.D{{"$limit", 3}}
      
      cursor, err := coll.Aggregate(context.TODO(), mongo.Pipeline{limitStage})
      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":"Romantic Era Music","enrollment":15}
      {"title":"Concepts in Topology","enrollment":35}
      {"title":"Ancient Greece","enrollment":100}

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

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

- :ref:`golang-query-document`
- :ref:`golang-retrieve`
- :ref:`golang-sort-results`
- :ref:`golang-skip`
- :ref:`golang-aggregation`

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

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

- `FindOptionsBuilder.SetLimit() <{+api+}/mongo/options#FindOptionsBuilder.SetLimit>`__
- `FindOptionsBuilder.SetSort() <{+api+}/mongo/options#FindOptionsBuilder.SetSort>`__
- `FindOptionsBuilder.SetSkip() <{+api+}/mongo/options#FindOptionsBuilder.SetSkip>`__
- `Aggregate() <{+api+}/mongo#Collection.Aggregate>`__
- `CountDocuments() <{+api+}/mongo#Collection.CountDocuments>`__
- `GridFSBucket.Find() <{+api+}/mongo#GridFSBucket.Find>`__