Database Manual / Reference / mongosh Methods / Cursors

cursor.skip() (mongosh method方法)

Definition定义

cursor.skip(<offset>)

Important

mongosh Method方法

This page documents a mongosh method. This is not the documentation for a language-specific driver, such as Node.js.本页记录了一种mongosh方法。这不是针对特定语言驱动程序（如Node.js）的文档。

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.有关MongoDB API驱动程序，请参阅特定语言的MongoDB驱动程序文档。

Call the skip() method on a cursor to control where MongoDB begins returning results. This approach may be useful in implementing paginated results.在游标上调用skip()方法来控制MongoDB开始返回结果的位置。这种方法在实现分页结果时可能很有用。

Note

You must apply skip() to the cursor before retrieving any documents from the database.在从数据库检索任何文档之前，必须对游标应用skip()。

The skip() method has the following parameter:skip()方法有以下参数：

Parameter参数Type类型Description描述
offsetnumber数字The number of documents to skip in the results set.结果集中要跳过的文档数。

Compatibility兼容性

This method is available in deployments hosted in the following environments:此方法在以下环境中托管的部署中可用：

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud：云中MongoDB部署的完全托管服务

Note

This command is supported in all MongoDB Atlas clusters. 所有MongoDB Atlas集群都支持此命令。For information on Atlas support for all commands, see Unsupported Commands.有关Atlas支持所有命令的信息，请参阅不支持的命令。

  • MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

Behavior行为

Using skip() with sort()使用skip()和sort()

If using skip() with sort(), be sure to include at least one field in your sort that contains unique values, before passing results to skip().如果将skip()与sort()一起使用，请确保在将结果传递给skip()之前，在排序中至少包含一个包含唯一值的字段。

Sorting on fields that contain duplicate values may return an inconsistent 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.保证排序一致性的最简单方法是在排序查询中包含_id字段。

See Consistent sorting with the sort() method for more information.有关更多信息，请参阅使用sort()方法进行一致排序。

Using skip() with limit()使用skip()和limit()

When you chain skip() and limit(), the method chaining order does not affect the results. The server always applies the skip operation based on the sort order before it applies the limit on how many documents to return.当你链接skip()和limit()时，方法链接顺序不会影响结果。服务器在应用要返回的文档数量限制之前，始终根据排序顺序应用跳过操作。

The following code example shows different chaining orders for skip() and limit() that always produce the same query results for the same data set:以下代码示例显示了skip()和limit()的不同链接顺序，它们总是为同一数据集生成相同的查询结果：

db.myColl.find().sort({_id: 1}).skip(3).limit(6);

db.myColl.find().sort({_id: 1}).limit(6).skip(3);

Pagination Example分页示例

Using skip()

The following JavaScript function uses skip() to paginate a collection by its _id field:以下JavaScript函数使用skip()按_id字段对集合进行分页：

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

The skip() method requires the server to scan from the beginning of the input results set before beginning to return results. As the offset increases, skip() will become slower.skip()方法要求服务器在开始返回结果之前从输入结果集的开头进行扫描。随着偏移量的增加，skip()将变慢。

Using Range Queries使用范围查询

Range queries can use indexes to avoid scanning unwanted documents, typically yielding better performance as the offset grows compared to using skip() for pagination.范围查询可以使用索引来避免扫描不需要的文档，与使用skip()进行分页相比，随着偏移量的增加，通常会产生更好的性能。

Descending Order降序

Use this procedure to implement pagination with range queries:使用以下过程通过范围查询实现分页：

  • Choose a field such as _id which generally changes in a consistent direction over time and has a unique index to prevent duplicate values,选择一个字段，如_id，它通常随时间沿一致的方向变化，并具有唯一的索引以防止重复值，
  • Query for documents whose field is less than the start value using the $lt and sort() operators, and使用$lt和sort()运算符查询字段小于起始值的文档，以及
  • Store the last-seen field value for the next query.为下一个查询存储上次看到的字段值。

For example, the following function uses the above procedure to print pages of student names from a collection, sorted approximately in order of newest documents first using the _id field (that is, in descending order):例如，以下函数使用上述过程打印集合中的学生姓名页面，首先使用_id字段（即降序）按最新文档的顺序进行排序：

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 this pagination function, using MaxKey to start from the largest possible key:然后，您可以使用以下代码使用此分页功能打印所有学生姓名，使用MaxKey从最大的键开始：

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

Note

While ObjectId values should increase over time, they are not necessarily monotonic. This is because they:虽然ObjectId值应该随着时间的推移而增加，但它们不一定是单调的。这是因为他们：

  • Only contain one second of temporal resolution, so ObjectId values created within the same second do not have a guaranteed ordering, and仅包含一秒的时间分辨率，因此在同一秒内创建的ObjectId值没有保证的顺序，并且
  • Are generated by clients, which may have differing system clocks.由可能具有不同系统时钟的客户端生成。

Ascending Order升序

Returning paginated results in ascending order is similar to the previous, but uses $gt with an ascending sort order:按升序返回分页结果与前一个类似，但使用了升序排序的$gt：

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 with MinKey as the starting key:使用此功能类似，但使用MinKey作为起始键：

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