Skip Returned Results

On this page

Overview

Skip
Aggregation
Additional Information

Overview

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

Sample Data

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.

Skip

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.

Example

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))
}

{"title":"Plate Tectonics","enrollment":45}
{"title":"Abstract Algebra","enrollment":60}

Aggregation

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

Example

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))
}

{"title":"Plate Tectonics","enrollment":45}
{"title":"World Fiction","enrollment":35}
{"title":"Modern Poetry","enrollment":12}

Additional Information

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

API Documentation

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

Back

Sort Results

Limit the Number of Returned Results