/ /

$skip (aggregation stage)

Definition

$skip

Skips over the specified number of documents that pass into the stage and passes the remaining documents to the next stage in the pipeline.

The $skip stage has the following prototype form:

{ $skip: <positive 64-bit integer> }

$skip takes a positive integer that specifies the maximum number of documents to skip.

Note

Starting in MongoDB 5.0, the $skip pipeline aggregation has a 64-bit integer limit. Values passed to the pipeline which exceed this limit will return a invalid argument error.

Behavior

Using $skip with Sorted Results

If using the $skip stage with any of:

the $sort aggregation stage,
the sort() method, or
the sort field to the findAndModify command or the findAndModify() shell method,

be sure to include at least one field in your sort that contains unique values, before passing results to the $skip stage.

Sorting on fields that contain duplicate values may return a different sort order for those duplicate fields over multiple executions, especially when the collection is actively receiving writes.

The easiest way to guarantee sort consistency is to include the _id field in your sort query.

See the following for more information on each:

Examples

Consider the following example:

db.article.aggregate([
    { $skip : 5 }
]);

This operation skips the first 5 documents passed to it by the pipeline. $skip has no effect on the content of the documents it passes along the pipeline.

The C# examples on this page use the sample_mflix database from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see Get Started in the MongoDB .NET/C# Driver documentation.

The following Movie class models the documents in the sample_mflix.movies collection:

[BsonIgnoreExtraElements]
public class Movie
{
    [BsonId]
    public ObjectId Id { get; set; }
    [BsonElement("title")]
    public string Title { get; set; } = null!;
    [BsonElement("year")]
    public int? Year { get; set; }
    [BsonElement("runtime")]
    public int? Runtime { get; set; }
    [BsonElement("rated")]
    public string? Rated { get; set; }
    [BsonElement("metacritic")]
    public int Metacritic { get; set; }
    [BsonElement("plot")]
    public string? Plot { get; set; }
    [BsonElement("type")]
    public string? Type { get; set; }
    [BsonElement("cast")]
    public string[]? Cast { get; set; }
    [BsonElement("directors")]
    public string[]? Directors { get; set; }
    [BsonElement("writers")]
    public string[]? Writers { get; set; }
    [BsonElement("imdb")]
    public ImdbData? Imdb { get; set; }
}

To use the MongoDB .NET/C# driver to add a $skip stage to an aggregation pipeline, call the Skip() method on a PipelineDefinition object.

The following example creates a pipeline stage that sorts movies by title and ID and skips the first 5 documents:

var pipeline = new EmptyPipelineDefinition<Movie>()
    .Sort(Builders<Movie>.Sort
        .Ascending(m => m.Title)
        .Ascending(m => m.Id))
    .Skip(5)
    .Limit(5);

{"_id": "...", "title": "'Doc'", "runtime": "...", "rated": "...", "year": "...", "metacritic": "..."}
{"_id": "...", "title": "'Pimpernel' Smith", "runtime": "...", "rated": "...", "year": "...", "metacritic": "..."}
{"_id": "...", "title": "'R Xmas", "runtime": "...", "rated": "...", "year": "...", "metacritic": "..."}
{"_id": "...", "title": "'Round Midnight", "runtime": "...", "rated": "...", "year": "...", "metacritic": "..."}
{"_id": "...", "title": "'Til Madness Do Us Part", "runtime": "...", "rated": "...", "year": "...", "metacritic": "..."}

To use the MongoDB Node.js driver to add a $skip stage to an aggregation pipeline, use the $skip operator in a pipeline object.

The following example creates a pipeline stage that skips the first five documents in the input collection and passes the remaining documents to the next stage in the pipeline. The example then runs the aggregation pipeline:

const pipeline = [{ $skip: 5 }];
const cursor = collection.aggregate(pipeline);
return cursor;

Learn More

To see full aggregation examples that use the $skip stage, see the Complete Aggregation Pipeline Tutorials.

Back

$shardedDataDistribution

$sort