cursor.skip()

Definition

• cursor.skip()

mongo Shell Method

This page documents the mongo shell method, and doesnot refer to the MongoDB Node.js driver (or any other driver)method. For corresponding MongoDB driver API, refer to your specificMongoDB driver documentation instead.

Call the cursor.skip() method on a cursor to control whereMongoDB begins returning results. This approach may be useful inimplementing paginated results.

Note

You must apply cursor.skip() to the cursor beforeretrieving any documents from the database.

The cursor.skip() method has the following parameter:

ParameterTypeDescriptionoffsetnumberThe number of documents to skip in the results set.

Pagination Example

Using cursor.skip()

The following JavaScript function uses cursor.skip() topaginate a collection in natural order:

function printStudents(pageNumber, nPerPage) {
  print( "Page: " + pageNumber );
  db.students.find()
             .skip( pageNumber > 0 ? ( ( pageNumber - 1 ) * nPerPage ) : 0 )
             .limit( nPerPage )
             .forEach( student => {
               print( student.name );
             } );
}

The cursor.skip() method requires the server to scan from thebeginning of the input results set before beginning to return results.As the offset increases, cursor.skip() will become slower.

Using Range Queries

Range queries can use indexes to avoid scanningunwanted documents, typically yielding better performance as the offsetgrows compared to using cursor.skip() for pagination.

Descending Order

Use this procedure to implement pagination with range queries:

• Choose a field such as _id which generally changes in a consistentdirection over time and has a unique indexto prevent duplicate values,
• Query for documents whose field is less than the start valueusing the $lt and cursor.sort() operators, and
• Store the last-seen field value for the next query.

For example, the following function uses the above procedure to printpages of student names from a collection, sorted approximately in orderof newest documents first using the id field (that is, in_descending order):

function printStudents(startValue, nPerPage) {
  let endValue = null;
  db.students.find( { _id: { $lt: startValue } } )
             .sort( { _id: -1 } )
             .limit( nPerPage )
             .forEach( student => {
               print( student.name );
               endValue = student._id;
             } );
 
  return endValue;
}

You may then use the following code to print all student names using thispagination function, using MaxKey to startfrom the largest possible key:

let currentKey = MaxKey;
while (currentKey !== null) {
  currentKey = printStudents(currentKey, 10);
}

Note

While ObjectId values should increase over time, they are notnecessarily monotonic. This is because they:

• Only contain one second of temporal resolution, so ObjectIdvalues created within the same second do not have a guaranteedordering, and
• Are generated by clients, which may have differing system clocks.

Ascending Order

Returning paginated results in ascending order is similar to theprevious, but uses $gt with an ascending sort order:

function printStudents(startValue, nPerPage) {
  let endValue = null;
  db.students.find( { _id: { $gt: startValue } } )
             .sort( { _id: 1 } )
             .limit( nPerPage )
             .forEach( student => {
               print( student.name );
               endValue = student._id;
             } );
 
  return endValue;
}

Using this function is likewise similar, but withMinKey as the starting key:

let currentKey = MinKey;
while (currentKey !== null) {
  currentKey = printStudents(currentKey, 10);
}