查询

用于构建查询的查询构造函数。 您无需直接实例化 Query。 相反，请使用模型函数，例如 Model.find().

示例

const query = MyModel.find(); // `query` is an instance of `Query`
query.setOptions({ lean : true });
query.collection(MyModel.collection);
query.where('age').gte(21).exec(callback);

// You can instantiate a query directly. There is no need to do
// this unless you're an advanced user with a very good reason to.
const query = new mongoose.Query();

指定要传递给 MongoDB 查询系统的 javascript 函数或表达式。

示例

query.$where('this.comments.length === 10 || this.name.length === 5')

// or

query.$where(function () {
  return this.comments.length === 10 || this.name.length === 5;
})

注意

仅当您无法使用其他 MongoDB 运算符（例如 $lt）满足条件时，才使用 $where。 在使用之前，请务必阅读有关 其所有注意事项。

指定 $all 查询条件。

当使用一个参数调用时，将使用传递给 where() 的最新路径。

示例

MyModel.find().where('pets').all(['dog', 'cat', 'ferret']);
// Equivalent:
MyModel.find().all('pets', ['dog', 'cat', 'ferret']);

设置 allowDiskUse 选项，该选项允许 MongoDB 服务器为该查询的 sort() 使用超过 100 MB 的内存。 此选项可以帮助您解决来自 MongoDB 服务器的 QueryExceededMemoryLimitNoDiskUseAllowed 错误。

请注意，此选项需要 MongoDB 服务器 >= 4.4。 对于 MongoDB 4.2 及更早版本，设置此选项是无操作。

调用 query.allowDiskUse(v) 等效于 query.setOptions({ allowDiskUse: v })

示例

await query.find().sort({ name: 1 }).allowDiskUse(true);
// Equivalent:
await query.find().sort({ name: 1 }).allowDiskUse();

指定 $and 条件的参数。

示例

query.and([{ color: 'green' }, { status: 'ok' }])

指定 batchSize 选项。

示例

query.batchSize(100)

注意

不能与 distinct() 一起使用

指定 $box 条件

示例

const lowerLeft = [40.73083, -73.99756]
const upperRight= [40.741404,  -73.988135]

query.where('loc').within().box(lowerLeft, upperRight)
query.box({ ll : lowerLeft, ur : upperRight })

将此查询转换为 model 的模式

注意

如果存在 obj，则会对其进行转换，而不是此查询。

执行查询，返回一个 Promise，该 Promise 将使用文档 (s) 解决或使用错误拒绝。 与 .then() 相似，但只接受拒绝处理程序。

有关 JavaScript 中的 Promise catch() 的更多信息。

已弃用 circle 的别名

已弃用。 请改用 circle。

已弃用 指定 $centerSphere 条件

已弃用。 请改用 circle。

示例

const area = { center: [50, 50], radius: 10 };
query.where('loc').within().centerSphere(area);

指定 $center 或 $centerSphere 条件。

示例

const area = { center: [50, 50], radius: 10, unique: true }
query.where('loc').within().circle(area)
// alternatively
query.circle('loc', area);

// spherical calculations
const area = { center: [50, 50], radius: 10, unique: true, spherical: true }
query.where('loc').within().circle(area)
// alternatively
query.circle('loc', area);

复制此查询，以便您可以重新执行它。

示例

const q = Book.findOne({ title: 'Casino Royale' });
await q.exec();
await q.exec(); // Throws an error because you can't execute a query twice

await q.clone().exec(); // Works

为此操作添加排序规则（MongoDB 3.4 及更高版本）

指定 comment 选项。

示例

query.comment('login query')

注意

不能与 distinct() 一起使用

将此查询指定为 countDocuments() 查询。 行为类似于 count()，不同之处在于，它始终在传递空过滤器 {} 时执行完整的集合扫描。

在处理 $where 和一些地理空间运算符 方面，countDocuments() 也存在细微差异。 与 count() 相比。

此函数触发以下中间件。

• countDocuments()

示例

const countQuery = model.where({ 'color': 'black' }).countDocuments();

query.countDocuments({ color: 'black' }).count().exec();

await query.countDocuments({ color: 'black' });

query.where('color', 'black').countDocuments().exec();

countDocuments() 函数类似于 count()，但有一些 countDocuments() 不支持的运算符。 以下是 count() 支持但 countDocuments() 不支持的运算符，以及建议的替代方案

• $where: $expr
• $near: 使用 $geoWithin 和 $center
• $nearSphere: 使用 $geoWithin 和 $centerSphere

返回 mongodb 驱动程序游标 的包装器。 QueryCursor 公开了 Streams3 接口以及 .next() 函数。

.cursor() 函数会触发预查找挂钩，但不会触发后查找挂钩。

示例

// There are 2 ways to use a cursor. First, as a stream:
Thing.
  find({ name: /^hello/ }).
  cursor().
  on('data', function(doc) { console.log(doc); }).
  on('end', function() { console.log('Done!'); });

// Or you can use `.next()` to manually get the next doc in the stream.
// `.next()` returns a promise, so you can use promises or callbacks.
const cursor = Thing.find({ name: /^hello/ }).cursor();
cursor.next(function(error, doc) {
  console.log(doc);
});

// Because `.next()` returns a promise, you can use co
// to easily iterate through all documents without loading them
// all into memory.
const cursor = Thing.find({ name: /^hello/ }).cursor();
for (let doc = await cursor.next(); doc != null; doc = await cursor.next()) {
  console.log(doc);
}

有效选项

• transform: 可选函数，接受 mongoose 文档。 函数的返回值将在 data 上发出，并由 .next() 返回。

声明和/或执行此查询作为 deleteMany() 操作。 工作原理类似于 remove，不同之处在于它删除集合中与 filter 匹配的所有文档，而不管 single 的值如何。

此函数触发 deleteMany 中间件。

示例

await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } });

此函数调用 MongoDB 驱动程序的 Collection#deleteMany() 函数。 返回的 promise 解析为一个包含 3 个属性的 object

• ok: 如果没有错误发生，则为 1
• deletedCount: 删除的文档数量
• n: 删除的文档数量。 等于 deletedCount。

示例

const res = await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } });
// `0` if no docs matched the filter, number of docs deleted otherwise
res.deletedCount;

声明和/或执行此查询作为 deleteOne() 操作。 工作原理类似于 remove，不同之处在于它最多删除一个文档，而不管 single 选项如何。

此函数触发 deleteOne 中间件。

示例

await Character.deleteOne({ name: 'Eddard Stark' });

此函数调用 MongoDB 驱动程序的 Collection#deleteOne() 函数。 返回的 promise 解析为一个包含 3 个属性的 object

• ok: 如果没有错误发生，则为 1
• deletedCount: 删除的文档数量
• n: 删除的文档数量。 等于 deletedCount。

示例

const res = await Character.deleteOne({ name: 'Eddard Stark' });
// `1` if MongoDB deleted a doc, `0` if no docs matched the filter `{ name: ... }`
res.deletedCount;

声明或执行 distinct() 操作。

此函数不触发任何中间件。

示例

distinct(field, conditions, options)
distinct(field, conditions)
distinct(field)
distinct()

指定 $elemMatch 条件

示例

query.elemMatch('comment', { author: 'autobot', votes: {$gte: 5}})

query.where('comment').elemMatch({ author: 'autobot', votes: {$gte: 5}})

query.elemMatch('comment', function (elem) {
  elem.where('author').equals('autobot');
  elem.where('votes').gte(5);
})

query.where('comment').elemMatch(function (elem) {
  elem.where({ author: 'autobot' });
  elem.where('votes').gte(5);
})

为使用 where() 指定的路径指定互补比较值

示例

User.where('age').equals(49);

// is the same as

User.where('age', 49);

获取/设置此查询的错误标志。 如果此标志不是 null 或 undefined，则 exec() promise 将在不执行的情况下拒绝。

示例

Query().error(); // Get current error value
Query().error(null); // Unset the current error
Query().error(new Error('test')); // `exec()` will resolve with test
Schema.pre('find', function() {
  if (!this.getQuery().userId) {
    this.error(new Error('Not allowed to query without setting userId'));
  }
});

请注意，查询转换在挂钩之后运行，因此转换错误将覆盖自定义错误。

示例

const TestSchema = new Schema({ num: Number });
const TestModel = db.model('Test', TestSchema);
TestModel.find({ num: 'not a number' }).error(new Error('woops')).exec(function(error) {
  // `error` will be a cast error because `num` failed to cast
});

将此查询指定为 estimatedDocumentCount() 查询。对于大型集合，它比使用 countDocuments() 更快，因为 estimatedDocumentCount() 使用集合元数据，而不是扫描整个集合。

estimatedDocumentCount() 不接受过滤器。 Model.find({ foo: bar }).estimatedDocumentCount() 等同于 Model.find().estimatedDocumentCount()

此函数触发以下中间件。

• estimatedDocumentCount()

示例

await Model.find().estimatedDocumentCount();

执行查询

示例

const promise = query.exec();
const promise = query.exec('update');

指定 $exists 条件

示例

// { name: { $exists: true }}
Thing.where('name').exists()
Thing.where('name').exists(true)
Thing.find().exists('name')

// { name: { $exists: false }}
Thing.where('name').exists(false);
Thing.find().exists('name', false);

设置 explain 选项，这将使此查询返回详细的执行统计信息，而不是实际的查询结果。此方法有助于确定查询使用什么索引。

调用 query.explain(v) 等同于 query.setOptions({ explain: v })

示例

const query = new Query();
const res = await query.find({ a: 1 }).explain('queryPlanner');
console.log(res);

执行查询，返回一个 Promise，该 Promise 将使用 .finally() 链式解析。

有关 JavaScript 中 Promise finally() 的更多信息。

查找与 selector 匹配的所有文档。结果将是文档数组。

如果结果中的文档太多而无法容纳在内存中，请使用 Query.prototype.cursor()

示例

const arr = await Movie.find({ year: { $gte: 1980, $lte: 1989 } });

将查询声明为 findOne 操作。执行后，第一个找到的文档将传递给回调函数。

查询结果是单个文档，如果未找到文档，则为 null。

• 注意： conditions 是可选的，如果 conditions 为 null 或未定义，则 mongoose 会向 MongoDB 发送一个空 findOne 命令，该命令将返回一个任意文档。如果您按 _id 查询，请改用 Model.findById()。

此函数触发以下中间件。

• findOne()

示例

const query = Kitten.where({ color: 'white' });
const kitten = await query.findOne();

发出一个 MongoDB findOneAndDelete 命令。

查找匹配的文档，将其删除，并返回找到的文档（如果有）。

此函数触发以下中间件。

• findOneAndDelete()

可用选项

• sort：如果根据条件找到多个文档，则设置排序顺序以选择要更新的文档
• maxTimeMS：为查询设置时间限制 - 需要 mongodb >= 2.6.0

回调签名

function(error, doc) {
  // error: any errors that occurred
  // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
}

示例

A.where().findOneAndDelete(conditions, options)  // return Query
A.where().findOneAndDelete(conditions) // returns Query
A.where().findOneAndDelete()           // returns Query

发出一个 MongoDB findOneAndReplace 命令。

查找匹配的文档，将其删除，并返回找到的文档（如果有）。

此函数触发以下中间件。

• findOneAndReplace()

可用选项

• sort：如果根据条件找到多个文档，则设置排序顺序以选择要更新的文档
• maxTimeMS：为查询设置时间限制 - 需要 mongodb >= 2.6.0
• includeResultMetadata：如果为 true，则返回完整的 来自 MongoDB 驱动程序的 ModifyResult，而不仅仅是文档

回调签名

function(error, doc) {
  // error: any errors that occurred
  // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
}

示例

A.where().findOneAndReplace(filter, replacement, options); // return Query
A.where().findOneAndReplace(filter); // returns Query
A.where().findOneAndReplace(); // returns Query

发出一个 mongodb findOneAndUpdate() 命令。

查找匹配的文档，根据 update 参数更新它，传递任何 options，并返回找到的文档（如果有）。

此函数触发以下中间件。

• findOneAndUpdate()

可用选项

• new：bool - 如果为 true，则返回修改后的文档，而不是原始文档。默认值为 false（在 4.0 中更改）
• upsert：bool - 如果不存在，则创建对象。默认值为 false。
• fields：{对象|字符串} - 字段选择。等同于 .select(fields).findOneAndUpdate()
• sort：如果根据条件找到多个文档，则设置排序顺序以选择要更新的文档
• maxTimeMS：为查询设置时间限制 - 需要 mongodb >= 2.6.0
• runValidators：如果为 true，则运行 更新验证器 以执行此命令。更新验证器会根据模型的模式验证更新操作。
• setDefaultsOnInsert：默认值为 true。如果 setDefaultsOnInsert 和 upsert 为 true，则 mongoose 会在创建新文档时应用模型模式中指定的 默认值。

示例

query.findOneAndUpdate(conditions, update, options)  // returns Query
query.findOneAndUpdate(conditions, update)           // returns Query
query.findOneAndUpdate(update)                       // returns Query
query.findOneAndUpdate()                             // returns Query

指定 $geometry 条件

示例

const polyA = [[[ 10, 20 ], [ 10, 40 ], [ 30, 40 ], [ 30, 20 ]]]
query.where('loc').within().geometry({ type: 'Polygon', coordinates: polyA })

// or
const polyB = [[ 0, 0 ], [ 1, 1 ]]
query.where('loc').within().geometry({ type: 'LineString', coordinates: polyB })

// or
const polyC = [ 0, 0 ]
query.where('loc').within().geometry({ type: 'Point', coordinates: polyC })

// or
query.where('loc').intersects().geometry({ type: 'Point', coordinates: polyC })

该参数将被分配给传递给 where() 的最新路径。

注意

geometry() 必须位于 intersects() 或 within() 之后。

object 参数必须包含 type 和 coordinates 属性。

• type {字符串}
• coordinates {数组}

对于更新操作，返回更新 $set 中路径的值。有助于编写可以在更新操作和 save() 中使用的 getter/setter。

示例

const query = Model.updateOne({}, { $set: { name: 'Jean-Luc Picard' } });
query.get('name'); // 'Jean-Luc Picard'

返回当前查询过滤器（也称为条件）作为 POJO。

示例

const query = new Query();
query.find({ a: 1 }).where('b').gt(2);
query.getFilter(); // { a: 1, b: { $gt: 2 } }

获取查询选项。

示例

const query = new Query();
query.limit(10);
query.setOptions({ maxTimeMS: 1000 });
query.getOptions(); // { limit: 10, maxTimeMS: 1000 }

获取此查询要填充的路径列表

示例

 bookSchema.pre('findOne', function() {
   let keys = this.getPopulatedPaths(); // ['author']
 });
 ...
 Book.findOne({}).populate('author');

示例

 // Deep populate
 const q = L1.find().populate({
   path: 'level2',
   populate: { path: 'level3' }
 });
 q.getPopulatedPaths(); // ['level2', 'level2.level3']

返回当前查询过滤器。等同于 getFilter()。

您应尽可能使用 getFilter() 而不是 getQuery()。getQuery() 可能会在将来的版本中被弃用。

示例

const query = new Query();
query.find({ a: 1 }).where('b').gt(2);
query.getQuery(); // { a: 1, b: { $gt: 2 } }

以 JSON 对象形式返回当前更新操作。

示例

const query = new Query();
query.updateOne({}, { $set: { a: 5 } });
query.getUpdate(); // { $set: { a: 5 } }

指定 $gt 查询条件。

当使用一个参数调用时，将使用传递给 where() 的最新路径。

示例

Thing.find().where('age').gt(21);

// or
Thing.find().gt('age', 21);

指定 $gte 查询条件。

当使用一个参数调用时，将使用传递给 where() 的最新路径。

设置查询提示。

示例

query.hint({ indexA: 1, indexB: -1 });

注意

不能与 distinct() 一起使用

指定 $in 查询条件。

当使用一个参数调用时，将使用传递给 where() 的最新路径。

为 geometry() 声明一个 intersects 查询。

示例

query.where('path').intersects().geometry({
  type: 'LineString',
  coordinates: [[180.0, 11.0], [180, 9.0]]
});

query.where('path').intersects({
  type: 'LineString',
  coordinates: [[180.0, 11.0], [180, 9.0]]
});

注意

必须在 where() 之后使用。

注意

在 Mongoose 3.7 中，intersects 从 getter 变成了函数。如果您需要旧语法，请使用 此方法。

包装函数，用于在查询上调用 isPathSelectedInclusive。

请求确认此操作已持久保存到 MongoDB 的磁盘日志中。此选项仅对写入数据库的操作有效

• deleteOne()
• deleteMany()
• findOneAndDelete()
• findOneAndReplace()
• findOneAndUpdate()
• updateOne()
• updateMany()

默认为模式的 writeConcern.j 选项

示例

await mongoose.model('Person').deleteOne({ name: 'Ned Stark' }).j(true);

设置 lean 选项。

从启用 lean 选项的查询中返回的文档是纯 JavaScript 对象，而不是 Mongoose 文档。它们没有 save 方法、getter/setter、虚拟属性或其他 Mongoose 功能。

示例

new Query().lean() // true
new Query().lean(true)
new Query().lean(false)

const docs = await Model.find().lean();
docs[0] instanceof mongoose.Document; // false

Lean 非常适合高性能的只读情况，尤其是在与 游标 结合使用时。

如果您需要使用 lean() 来使用虚拟属性、getter/setter 或默认值，则需要使用插件。请参见

• mongoose-lean-virtuals
• mongoose-lean-getters
• mongoose-lean-defaults

指定查询将返回的最大文档数。

示例

query.limit(20);

注意

不能与 distinct() 一起使用

指定 $lt 查询条件。

当使用一个参数调用时，将使用传递给 where() 的最新路径。

指定 $lte 查询条件。

当使用一个参数调用时，将使用传递给 where() 的最新路径。

指定 maxDistance 查询条件。

当使用一个参数调用时，将使用传递给 where() 的最新路径。

设置 maxTimeMS 选项。这将告诉 MongoDB 服务器，如果查询或写入操作运行时间超过 ms 毫秒，则中止操作。

调用 query.maxTimeMS(v) 等同于 query.setOptions({ maxTimeMS: v })

示例

const query = new Query();
// Throws an error 'operation exceeded time limit' as long as there's
// >= 1 doc in the queried collection
const res = await query.find({ $where: 'sleep(1000) || true' }).maxTimeMS(100);

将另一个查询或条件对象合并到此查询中。

当传递一个查询时，条件、字段选择和选项将被合并。

指定 $mod 条件，为其 path 属性为数字（等于 remainder 模 divisor）的文档过滤文档。

示例

// All find products whose inventory is odd
Product.find().mod('inventory', [2, 1]);
Product.find().where('inventory').mod([2, 1]);
// This syntax is a little strange, but supported.
Product.find().where('inventory').mod(2, 1);

与此查询关联的模型。

示例

const q = MyModel.find();
q.model === MyModel; // true

围绕此查询的当前 mongoose 特定选项的 getter/setter。以下是当前的 Mongoose 特定选项。

• populate：表示要填充哪些路径的数组。应为 Query.prototype.populate() 的每次调用包含一个条目
• lean：如果为真值，则 Mongoose 不会 填充 从此查询返回的任何文档。有关更多信息，请参见 Query.prototype.lean()。
• strict: 控制 Mongoose 如何处理更新时不在模式中的键。此选项默认情况下为 true，这意味着 Mongoose 会静默地删除更新中不在模式中的任何路径。有关更多信息，请参阅 strict 模式文档。
• strictQuery: 控制 Mongoose 如何处理查询 filter 中不在模式中的键。此选项默认情况下为 false，这意味着 Mongoose 允许 Model.find({ foo: 'bar' })，即使 foo 不在模式中。有关更多信息，请参阅 strictQuery 文档。
• nearSphere: 使用 $nearSphere 代替 near()。请参阅 Query.prototype.nearSphere() 文档

Mongoose 为内部选项维护一个单独的对象，因为 Mongoose 将 Query.prototype.options 发送到 MongoDB 服务器，并且上述选项与 MongoDB 服务器无关。

指定 $ne 查询条件。

当使用一个参数调用时，将使用传递给 where() 的最新路径。

指定 $near 或 $nearSphere 条件

这些运算符返回按距离排序的文档。

示例

query.where('loc').near({ center: [10, 10] });
query.where('loc').near({ center: [10, 10], maxDistance: 5 });
query.where('loc').near({ center: [10, 10], maxDistance: 5, spherical: true });
query.near('loc', { center: [10, 10], maxDistance: 5 });

已弃用 指定 $nearSphere 条件

示例

query.where('loc').nearSphere({ center: [10, 10], maxDistance: 5 });

已弃用。 使用 query.near() 代替，并将 spherical 选项设置为 true。

示例

query.where('loc').near({ center: [10, 10], spherical: true });

指定 $nin 查询条件。

当使用一个参数调用时，将使用传递给 where() 的最新路径。

指定 $nor 条件的参数。

示例

query.nor([{ color: 'green' }, { status: 'ok' }]);

指定 $or 条件的参数。

示例

query.or([{ color: 'red' }, { status: 'emergency' }]);

如果没有任何文档与给定的 filter 匹配，则使此查询抛出错误。这对于与 async/await 集成非常方便，因为 orFail() 可以为您省去一个额外的 if 语句来检查是否没有找到文档。

示例

// Throws if no doc returned
await Model.findOne({ foo: 'bar' }).orFail();

// Throws if no document was updated. Note that `orFail()` will still
// throw if the only document that matches is `{ foo: 'bar', name: 'test' }`,
// because `orFail()` will throw if no document was _updated_, not
// if no document was _found_.
await Model.updateOne({ foo: 'bar' }, { name: 'test' }).orFail();

// Throws "No docs found!" error if no docs match `{ foo: 'bar' }`
await Model.find({ foo: 'bar' }).orFail(new Error('No docs found!'));

// Throws "Not found" error if no document was found
await Model.findOneAndUpdate({ foo: 'bar' }, { name: 'test' }).
  orFail(() => Error('Not found'));

指定 $polygon 条件

示例

query.where('loc').within().polygon([10, 20], [13, 25], [7, 15]);
query.polygon('loc', [10, 20], [13, 25], [7, 15]);

指定应使用其他文档填充的路径。

示例

let book = await Book.findOne().populate('authors');
book.title; // 'Node.js in Action'
book.authors[0].name; // 'TJ Holowaychuk'
book.authors[1].name; // 'Nathan Rajlich'

let books = await Book.find().populate({
  path: 'authors',
  // `match` and `sort` apply to the Author model,
  // not the Book model. These options do not affect
  // which documents are in `books`, just the order and
  // contents of each book document's `authors`.
  match: { name: new RegExp('.*h.*', 'i') },
  sort: { name: -1 }
});
books[0].title; // 'Node.js in Action'
// Each book's `authors` are sorted by name, descending.
books[0].authors[0].name; // 'TJ Holowaychuk'
books[0].authors[1].name; // 'Marc Harter'

books[1].title; // 'Professional AngularJS'
// Empty array, no authors' name has the letter 'h'
books[1].authors; // []

路径在查询执行并收到响应后进行填充。然后，将为每个为填充指定的路径执行单独的查询。在每个查询的响应也返回后，结果将传递给回调。

向此查询实例添加后 中间件。不会影响其他查询。

示例

const q1 = Question.find({ answer: 42 });
q1.post(function middleware() {
  console.log(this.getFilter());
});
await q1.exec(); // Prints "{ answer: 42 }"

// Doesn't print anything, because `middleware()` is only
// registered on `q1`.
await Question.find({ answer: 42 });

向此查询实例添加前 中间件。不会影响其他查询。

示例

const q1 = Question.find({ answer: 42 });
q1.pre(function middleware() {
  console.log(this.getFilter());
});
await q1.exec(); // Prints "{ answer: 42 }"

// Doesn't print anything, because `middleware()` is only
// registered on `q1`.
await Question.find({ answer: 42 });

获取/设置当前投影（又称字段）。传递 null 以删除当前投影。

与 projection() 不同，select() 函数会就地修改当前投影。此函数会覆盖现有的投影。

示例

const q = Model.find();
q.projection(); // null

q.select('a b');
q.projection(); // { a: 1, b: 1 }

q.projection({ c: 1 });
q.projection(); // { c: 1 }

q.projection(null);
q.projection(); // null

确定要从中读取的 MongoDB 节点。

Preferences

primary - (default) Read from primary only. Operations will produce an error if primary is unavailable. Cannot be combined with tags.
secondary            Read from secondary if available, otherwise error.
primaryPreferred     Read from primary if available, otherwise a secondary.
secondaryPreferred   Read from a secondary if available, otherwise read from the primary.
nearest              All operations read from among the nearest candidates, but unlike other modes, this option will include both the primary and all secondaries in the random selection.

Aliases

p   primary
pp  primaryPreferred
s   secondary
sp  secondaryPreferred
n   nearest

示例

new Query().read('primary')
new Query().read('p')  // same as primary

new Query().read('primaryPreferred')
new Query().read('pp') // same as primaryPreferred

new Query().read('secondary')
new Query().read('s')  // same as secondary

new Query().read('secondaryPreferred')
new Query().read('sp') // same as secondaryPreferred

new Query().read('nearest')
new Query().read('n')  // same as nearest

// read from secondaries with matching tags
new Query().read('s', [{ dc:'sf', s: 1 },{ dc:'ma', s: 2 }])

详细了解如何使用读首选项 此处。

为查询设置 readConcern 选项。

示例

new Query().readConcern('local')
new Query().readConcern('l')  // same as local

new Query().readConcern('available')
new Query().readConcern('a')  // same as available

new Query().readConcern('majority')
new Query().readConcern('m')  // same as majority

new Query().readConcern('linearizable')
new Query().readConcern('lz') // same as linearizable

new Query().readConcern('snapshot')
new Query().readConcern('s')  // same as snapshot

Read Concern Level

local         MongoDB 3.2+ The query returns from the instance with no guarantee guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
available     MongoDB 3.6+ The query returns from the instance with no guarantee guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
majority      MongoDB 3.2+ The query returns the data that has been acknowledged by a majority of the replica set members. The documents returned by the read operation are durable, even in the event of failure.
linearizable  MongoDB 3.4+ The query returns data that reflects all successful majority-acknowledged writes that completed prior to the start of the read operation. The query may wait for concurrently executing writes to propagate to a majority of replica set members before returning results.
snapshot      MongoDB 4.0+ Only available for operations within multi-document transactions. Upon transaction commit with write concern "majority", the transaction operations are guaranteed to have read from a snapshot of majority-committed data.

Aliases

l   local
a   available
m   majority
lz  linearizable
s   snapshot

详细了解如何使用读关注 此处。

指定 $regex 查询条件。

当使用一个参数调用时，将使用传递给 where() 的最新路径。

声明此查询并将其执行为 replaceOne() 操作。MongoDB 将替换现有文档，并且不会接受任何 原子运算符 ($set 等)。

注意 replaceOne 不会 触发更新中间件。请改用 pre('replaceOne') 和 post('replaceOne')。

示例

const res = await Person.replaceOne({ _id: 24601 }, { name: 'Jean Valjean' });
res.acknowledged; // Indicates if this write result was acknowledged. If not, then all other members of this result will be undefined.
res.matchedCount; // Number of documents that matched the filter
res.modifiedCount; // Number of documents that were modified
res.upsertedCount; // Number of documents that were upserted
res.upsertedId; // Identifier of the inserted document (if an upsert took place)

此函数触发以下中间件。

• replaceOne()

设置此查询的 sanitizeProjection 选项。如果设置，sanitizeProjection 将执行两件事

1. 强制投影值为数字，而不是字符串。
2. 阻止使用 + 语法覆盖默认情况下取消选择的属性。

使用 sanitizeProjection()，您可以将潜在的不受信任的用户数据传递给 .select()。

示例

const userSchema = new Schema({
  name: String,
  password: { type: String, select: false }
});
const UserModel = mongoose.model('User', userSchema);
const { _id } = await UserModel.create({ name: 'John', password: 'secret' })

// The MongoDB server has special handling for string values that start with '$'
// in projections, which can lead to unexpected leaking of sensitive data.
let doc = await UserModel.findOne().select({ name: '$password' });
doc.name; // 'secret'
doc.password; // undefined

// With `sanitizeProjection`, Mongoose forces all projection values to be numbers
doc = await UserModel.findOne().sanitizeProjection(true).select({ name: '$password' });
doc.name; // 'John'
doc.password; // undefined

// By default, Mongoose supports projecting in `password` using `+password`
doc = await UserModel.findOne().select('+password');
doc.password; // 'secret'

// With `sanitizeProjection`, Mongoose prevents projecting in `password` and other
// fields that have `select: false` in the schema.
doc = await UserModel.findOne().sanitizeProjection(true).select('+password');
doc.password; // undefined

指定要包含或排除的文档字段（也称为查询“投影”）

使用字符串语法时，在路径前加 - 将标记该路径为排除。当路径没有 - 前缀时，它将被包含。最后，如果路径前缀为 +，则它强制包含路径，这对于在 模式级别 上被排除的路径很有用。

投影必须是包含式或排除式。换句话说，您必须列出要包含的字段（这将排除所有其他字段），或者列出要排除的字段（这意味着所有其他字段都将被包含）。_id 字段是唯一的例外，因为 MongoDB 默认情况下会包含它。

示例

// include a and b, exclude other fields
query.select('a b');
// Equivalent syntaxes:
query.select(['a', 'b']);
query.select({ a: 1, b: 1 });

// exclude c and d, include other fields
query.select('-c -d');

// Use `+` to override schema-level `select: false` without making the
// projection inclusive.
const schema = new Schema({
  foo: { type: String, select: false },
  bar: String
});
// ...
query.select('+foo'); // Override foo's `select: false` without excluding `bar`

// or you may use object notation, useful when
// you have keys already prefixed with a "-"
query.select({ a: 1, b: 1 });
query.select({ c: 0, d: 0 });

Additional calls to select can override the previous selection:
query.select({ a: 1, b: 1 }).select({ b: 0 }); // selection is now { a: 1 }
query.select({ a: 0, b: 0 }).select({ b: 1 }); // selection is now { a: 0 }

确定是否已进行字段选择。

确定是否已进行排除式字段选择。

query.selectedExclusively(); // false
query.select('-name');
query.selectedExclusively(); // true
query.selectedInclusively(); // false

确定是否已进行包含式字段选择。

query.selectedInclusively(); // false
query.select('name');
query.selectedInclusively(); // true

设置与此查询关联的 MongoDB 会话。会话是您将查询标记为 事务 的一部分的方式。

调用 session(null) 会从此查询中删除会话。

示例

const s = await mongoose.startSession();
await mongoose.model('Person').findOne({ name: 'Axl Rose' }).session(s);

向此查询的更新添加 $set，而不会更改操作。这对查询中间件很有用，因此您可以添加更新，无论您使用 updateOne()、updateMany()、findOneAndUpdate() 等。

示例

// Updates `{ $set: { updatedAt: new Date() } }`
new Query().updateOne({}, {}).set('updatedAt', new Date());
new Query().updateMany({}, {}).set({ updatedAt: new Date() });

设置查询选项。某些选项只对某些操作有意义。

Options

以下选项仅适用于 find()

• tailable
• limit
• skip
• allowDiskUse
• batchSize
• readPreference
• hint
• comment

以下选项仅适用于写入操作：updateOne()、updateMany()、replaceOne()、findOneAndUpdate() 和 findByIdAndUpdate()

• upsert
• writeConcern
• timestamps: 如果在模式中设置了 timestamps，请将此选项设置为 false 以跳过该特定更新的时间戳。如果在模式选项中未启用 timestamps，则不会产生任何影响。
• overwriteDiscriminatorKey: 允许在更新中设置鉴别器键。如果更新更改了鉴别器键，则将使用正确的鉴别器模式。

以下选项仅适用于 find()、findOne()、findById()、findOneAndUpdate()、findOneAndReplace()、findOneAndDelete() 和 findByIdAndUpdate()

• lean
• populate
• projection
• sanitizeProjection
• useBigInt64

以下选项仅适用于所有操作，除了 updateOne()、updateMany()、deleteOne() 和 deleteMany()

• maxTimeMS

以下选项适用于 find()、findOne()、findOneAndUpdate()、findOneAndDelete()、updateOne() 和 deleteOne()

• sort

以下选项适用于 findOneAndUpdate() 和 findOneAndDelete()

• includeResultMetadata

以下选项适用于所有操作

• strict
• collation
• session
• explain

将查询条件设置为提供的 JSON 对象。

示例

const query = new Query();
query.find({ a: 1 })
query.setQuery({ a: 2 });
query.getQuery(); // { a: 2 }

将当前更新操作设置为新值。

示例

const query = new Query();
query.updateOne({}, { $set: { a: 5 } });
query.setUpdate({ $set: { b: 6 } });
query.getUpdate(); // { $set: { b: 6 } }

指定 $size 查询条件。

当使用一个参数调用时，将使用传递给 where() 的最新路径。

示例

const docs = await MyModel.where('tags').size(0).exec();
assert(Array.isArray(docs));
console.log('documents with 0 tags', docs);

指定要跳过的文档数量。

示例

query.skip(100).limit(20);

注意

不能与 distinct() 一起使用

为数组指定 $slice 投影。

示例

query.slice('comments', 5); // Returns the first 5 comments
query.slice('comments', -5); // Returns the last 5 comments
query.slice('comments', [10, 5]); // Returns the first 5 comments after the 10-th
query.where('comments').slice(5); // Returns the first 5 comments
query.where('comments').slice([-10, 5]); // Returns the first 5 comments after the 10-th to last

注意：如果要切片的元素数量的绝对值大于数组中的元素数量，则将返回所有数组元素。

 // Given `arr`: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 query.slice('arr', 20); // Returns [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 query.slice('arr', -20); // Returns [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

注意：如果要跳过的元素数量为正数且大于数组中的元素数量，则将返回空数组。

 // Given `arr`: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 query.slice('arr', [20, 5]); // Returns []

注意：如果要跳过的元素数量为负数，并且其绝对值大于数组中的元素数量，则起始位置为数组的开头。

 // Given `arr`: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 query.slice('arr', [-20, 5]); // Returns [1, 2, 3, 4, 5]

设置排序顺序。

如果传递的是对象，则允许的值为 asc、desc、ascending、descending、1 和 -1。

如果传递的是字符串，则它必须是一个空格分隔的路径名称列表。每个路径的排序顺序为升序，除非路径名称以 - 为前缀，则将被视为降序。

示例

// sort by "field" ascending and "test" descending
query.sort({ field: 'asc', test: -1 });

// equivalent
query.sort('field -test');

// also possible is to use a array with array key-value pairs
query.sort([['field', 'asc']]);

注意

不能与 distinct() 一起使用

设置可尾随选项（用于带上限集合）。

示例

query.tailable(); // true
query.tailable(true);
query.tailable(false);

// Set both `tailable` and `awaitData` options
query.tailable({ awaitData: true });

注意

不能与 distinct() 一起使用

执行查询，返回一个 Promise，该 Promise 将使用文档或错误进行解析。

有关 JavaScript 中的 then() 的更多信息。

将此查询转换为具有所有参数和选项的自定义可重用查询构造函数。

示例

// Create a query for adventure movies and read from the primary
// node in the replica-set unless it is down, in which case we'll
// read from a secondary node.
const query = Movie.find({ tags: 'adventure' }).read('primaryPreferred');

// create a custom Query constructor based off these settings
const Adventure = query.toConstructor();

// further narrow down our query results while still using the previous settings
await Adventure().where({ name: /^Life/ }).exec();

// since Adventure is a stand-alone constructor we can also add our own
// helper methods and getters without impacting global queries
Adventure.prototype.startsWith = function (prefix) {
  this.where({ name: new RegExp('^' + prefix) })
  return this;
}
Object.defineProperty(Adventure.prototype, 'highlyRated', {
  get: function () {
    this.where({ rating: { $gt: 4.5 }});
    return this;
  }
})
await Adventure().highlyRated.startsWith('Life').exec();

运行函数 fn 并将 fn 的返回值视为查询解析到的新值。

您传递给 transform() 的任何函数将在任何后置钩子 **之后** 运行。

示例

const res = await MyModel.findOne().transform(res => {
  // Sets a `loadedAt` property on the doc that tells you the time the
  // document was loaded.
  return res == null ?
    res :
    Object.assign(res, { loadedAt: new Date() });
});

声明和/或执行此查询作为 updateMany() 操作。MongoDB 将更新与 filter 匹配的 **所有** 文档（而不是仅第一个文档）。

**注意** updateMany **不会** 触发更新中间件。请改用 pre('updateMany') 和 post('updateMany')。

示例

const res = await Person.updateMany({ name: /Stark$/ }, { isDeleted: true });
res.n; // Number of documents matched
res.nModified; // Number of documents modified

此函数触发以下中间件。

• updateMany()

声明和/或执行此查询作为 updateOne() 操作。MongoDB 将 **仅** 更新与 filter 匹配的第一个文档。

• 如果您想覆盖整个文档，而不是使用 原子运算符（如 $set），请使用 replaceOne()。

**注意** updateOne **不会** 触发更新中间件。请改用 pre('updateOne') 和 post('updateOne')。

示例

const res = await Person.updateOne({ name: 'Jean-Luc Picard' }, { ship: 'USS Enterprise' });
res.acknowledged; // Indicates if this write result was acknowledged. If not, then all other members of this result will be undefined.
res.matchedCount; // Number of documents that matched the filter
res.modifiedCount; // Number of documents that were modified
res.upsertedCount; // Number of documents that were upserted
res.upsertedId; // Identifier of the inserted document (if an upsert took place)

此函数触发以下中间件。

• updateOne()

设置必须确认此写入才能将此写入视为成功的 mongod 服务器数量或 mongod 服务器标记集。此选项仅对写入数据库的操作有效。

• deleteOne()
• deleteMany()
• findOneAndDelete()
• findOneAndReplace()
• findOneAndUpdate()
• updateOne()
• updateMany()

默认值为架构的 writeConcern.w 选项

示例

// The 'majority' option means the `deleteOne()` promise won't resolve
// until the `deleteOne()` has propagated to the majority of the replica set
await mongoose.model('Person').
  deleteOne({ name: 'Ned Stark' }).
  w('majority');

指定用于链式操作的 path。

示例

// instead of writing:
User.find({age: {$gte: 21, $lte: 65}});

// we can instead write:
User.where('age').gte(21).lte(65);

// passing query conditions is permitted
User.find().where({ name: 'vonderful' })

// chaining
User
.where('age').gte(21).lte(65)
.where('name', /^vonderful/i)
.where('friends').slice(10)
.exec()

定义用于地理空间查询的 $within 或 $geoWithin 参数。

示例

query.where(path).within().box()
query.where(path).within().circle()
query.where(path).within().geometry()

query.where('loc').within({ center: [50,50], radius: 10, unique: true, spherical: true });
query.where('loc').within({ box: [[40.73, -73.9], [40.7, -73.988]] });
query.where('loc').within({ polygon: [[],[],[],[]] });

query.where('loc').within([], [], []) // polygon
query.where('loc').within([], []) // box
query.where('loc').within({ type: 'LineString', coordinates: [...] }); // geometry

必须在 where() 之后使用。

注意

从 Mongoose 3.7 开始，$geoWithin 始终用于查询。要更改此行为，请参阅 Query.use$geoWithin。

注意

在 Mongoose 3.7 中，within 从 getter 变为函数。如果您需要旧语法，请使用 此。

设置此查询的 3 个写入关注参数。

• w: 设置必须确认此写入才能将此写入视为成功的 mongod 服务器数量或 mongod 服务器标记集。
• j: 布尔值，设置为 true 以请求确认此操作已持久保存到 MongoDB 的磁盘日志。
• wtimeout: 如果 w > 1，则此写入在操作失败之前通过副本集传播的最大等待时间。默认值为 0，表示没有超时。

此选项仅对写入数据库的操作有效。

• deleteOne()
• deleteMany()
• findOneAndDelete()
• findOneAndReplace()
• findOneAndUpdate()
• updateOne()
• updateMany()

默认值为架构的 writeConcern 选项

示例

// The 'majority' option means the `deleteOne()` promise won't resolve
// until the `deleteOne()` has propagated to the majority of the replica set
await mongoose.model('Person').
  deleteOne({ name: 'Ned Stark' }).
  writeConcern({ w: 'majority' });

如果 w > 1，则此写入在操作失败之前通过副本集传播的最大等待时间。默认值为 0，表示没有超时。

此选项仅对写入数据库的操作有效。

• deleteOne()
• deleteMany()
• findOneAndDelete()
• findOneAndReplace()
• findOneAndUpdate()
• updateOne()
• updateMany()

默认值为架构的 writeConcern.wtimeout 选项

示例

// The `deleteOne()` promise won't resolve until this `deleteOne()` has
// propagated to at least `w = 2` members of the replica set. If it takes
// longer than 1 second, this `deleteOne()` will fail.
await mongoose.model('Person').
  deleteOne({ name: 'Ned Stark' }).
  w(2).
  wtimeout(1000);

返回用于 for/await/of 循环 的异步迭代器。此函数 **仅** 对 find() 查询有效。您无需显式调用此函数，JavaScript 运行时将为您调用它。

示例

for await (const doc of Model.aggregate([{ $sort: { name: 1 } }])) {
  console.log(doc.name);
}

Node.js 10.x 原生支持异步迭代器，无需任何标志。您可以使用 --harmony_async_iteration 标志 在 Node.js 8.x 中启用异步迭代器。

**注意：** 如果 Symbol.asyncIterator 未定义，则此函数无效。如果 Symbol.asyncIterator 未定义，则意味着您的 Node.js 版本不支持异步迭代器。

返回此查询的字符串表示形式。

有关 JavaScript 中的 toString() 的更多信息。

示例

const q = Model.find();
console.log(q); // Prints "Query { find }"

选择退出使用 $geoWithin 的标志。

mongoose.Query.use$geoWithin = false;

MongoDB 2.4 不推荐使用 $within，并将其替换为 $geoWithin。Mongoose 默认使用 $geoWithin（与 $within 100% 向后兼容）。如果您运行的是旧版本的 MongoDB，请将此标志设置为 false，以便您的 within() 查询继续工作。