Docs Menu
Docs Home
/ / /
Go Driver
/ / /

Skip Returned Results

On this page

  • Overview
  • Skip
  • Aggregation
  • Additional Information

In this guide, you can learn how to skip a specified number of returned results from read operations.

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

type Course struct {
Title string
Enrollment int32
}

To run the examples in this guide, load these documents into the db.courses collection with the following snippet:

coll := client.Database("db").Collection("courses")
docs := []interface{}{
Course{Title: "World Fiction", Enrollment: 35},
Course{Title: "Abstract Algebra", Enrollment: 60},
Course{Title: "Modern Poetry", Enrollment: 12},
Course{Title: "Plate Tectonics", Enrollment: 45},
}
result, err := coll.InsertMany(context.TODO(), docs)

Tip

Nonexistent Databases and Collections

If the necessary database and collection don't exist when you perform a write operation, the server implicitly creates them.

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

To skip a specified number of returned results from a query, pass the number of documents you want to skip to the SetSkip() method of the read operation's options.

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

  • Find()

  • FindOne()

  • CountDocuments()

  • gridfs.Bucket.Find()

If the number of documents exceeds the number of matched documents for a query, that query returns no documents.

Tip

Passing in a negative number to the SetSkip() method results in a runtime error.

Find operations return documents in a natural order that is not sorted on any field. To avoid skipping random documents, use the SetSort() method to sort documents on a field with unique values before setting a skip option.

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

  • Sorts the results in ascending order on the enrollment field

  • Skips the first two documents

opts := options.Find().SetSort(bson.D{{"enrollment", 1}}).SetSkip(2)
cursor, err := coll.Find(context.TODO(), bson.D{}, 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))
}

You can also include the $skip stage in an aggregation pipeline to skip documents.

The following example performs an Aggregate() operation with the following behavior:

  • Sorts the results in descending order on the enrollment field

  • Skips the first document

sortStage := bson.D{{"$sort", bson.D{{"enrollment", -1}}}}
skipStage := bson.D{{"$skip", 1}}
cursor, err := coll.Aggregate(context.TODO(), mongo.Pipeline{sortStage, skipStage})
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))
}

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

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

← Sort Results