Запрос

Конструктор Query используется для построения запросов. Вам не нужно создавать экземпляр Query напрямую. Вместо этого используйте функции Model, такие как 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();

Задает функцию или выражение javascript для передачи в систему запросов MongoDB.

Пример:

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

// or

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

Примечание:

Используйте $where только тогда, когда у вас есть условие, которое не может быть выполнено с помощью других операторов MongoDB, таких как $lt. Обязательно ознакомьтесь со всеми предостережениями перед использованием.

Задает условие запроса $all.

При вызове с одним аргументом используется последний путь, переданный в where().

Пример:

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

Устанавливает опцию allowDiskUse, которая позволяет серверу MongoDB использовать более 100 МБ для sort() этого запроса. Эта опция может помочь обойти ошибки QueryExceededMemoryLimitNoDiskUseAllowed от сервера MongoDB.

Обратите внимание, что для этой опции требуется сервер 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, который будет разрешен с документом (документами) или отклонен с ошибкой. Как .then(), но принимает только обработчик отклонения.

Подробнее о catch() Promise на JavaScript.

УСТАРЕВШИЙ Псевдоним для 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()

Указывает этот запрос как запрос count.

Этот метод устарел. Если вы хотите подсчитать количество документов в коллекции, например, count({}), используйте функцию estimatedDocumentCount() вместо этого. В противном случае используйте функцию countDocuments().

Эта функция запускает следующий middleware.

• count()

Пример:

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

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

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

query.where('color', 'black').count();

Указывает этот запрос как запрос countDocuments(). Ведёт себя как count(), за исключением того, что всегда выполняет полный сканирование коллекции при передаче пустого фильтра {}.

Также есть небольшие различия в том, как countDocuments() обрабатывает $where и несколько геопространственных операторов по сравнению с count().

Эта функция запускает следующий middleware.

• 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.

Эта функция запускает middleware deleteMany.

Пример:

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

Эта функция вызывает функцию драйвера MongoDB Collection#deleteMany(). Возвращаемое промис разрешается до объекта, содержащего 3 свойства:

• 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.

Эта функция запускает middleware deleteOne.

Пример:

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

Эта функция вызывает функцию драйвера MongoDB Collection#deleteOne(). Возвращаемое промис разрешается до объекта, содержащего 3 свойства:

• 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().

Эта функция не запускает middleware.

Пример:

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() отклонится без выполнения.

Пример:

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().

Эта функция запускает следующий middleware.

• 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, который будет разрешён с .finally() в цепочке.

Подробнее о Promise finally() в JavaScript.

Находит все документы, которые соответствуют selector. Результат будет массивом документов.

Если в результате слишком много документов для хранения в памяти, используйте Query.prototype.cursor()

Пример:

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

Объявляет запрос как операцию findOne. При выполнении, первый найденный документ передается в обратный вызов.

Результат запроса — один документ или null, если документ не был найден.

• Примечание: conditions необязательно, и если conditions равно null или undefined, mongoose отправит пустой findOne команду в MongoDB, которая вернет произвольный документ. Если вы выполняете запрос по _id, используйте Model.findById() вместо.

Эта функция запускает следующую среду.

• findOne()

Пример:

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

Выполняет команду MongoDB findOneAndDelete.

Находит соответствующий документ, удаляет его и возвращает найденный документ (если таковой имеется).

Эта функция запускает следующую среду.

• findOneAndDelete()

Доступные опции

• sort: если несколько документов найдены по условиям, устанавливает порядок сортировки для выбора документа для обновления
• maxTimeMS: устанавливает временной лимит на запрос — требует mongodb >= 2.6.0
• rawResult: если true, возвращает исходный результат из драйвера MongoDB

Подпись обратного вызова

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

Устаревший псевдоним для findOneAndDelete().

Находит соответствующий документ, удаляет его и возвращает найденный документ (если таковой имеется).

Эта функция запускает следующую среду.

• findOneAndRemove()

Доступные опции

• sort: если несколько документов найдены по условиям, устанавливает порядок сортировки для выбора документа для обновления
• maxTimeMS: устанавливает временной лимит на запрос — требует mongodb >= 2.6.0
• rawResult: если true, возвращает исходный результат из драйвера MongoDB

Пример:

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

Выполняет команду MongoDB findOneAndReplace.

Находит соответствующий документ, удаляет его и возвращает найденный документ (если таковой имеется).

Эта функция срабатывает следующие посредники.

• findOneAndReplace()

Доступные опции

• sort: если несколько документов найдены по условиям, устанавливает порядок сортировки, чтобы выбрать, какой документ обновить
• maxTimeMS: устанавливает временной лимит на запрос - требует mongodb >= 2.6.0
• rawResult: если true, разрешает получить сырой результат из драйвера MongoDB

Подпись обратного вызова

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: если несколько документов найдены по условиям, устанавливает порядок сортировки, чтобы выбрать, какой документ обновить
• sort: устанавливает временной лимит на запрос - требует mongodb >= 2.6.0
• runValidators: если true, запускает валидаторы обновлений для этой команды. Валидаторы обновлений проверяют операцию обновления по схеме модели.
• setDefaultsOnInsert: true по умолчанию. Если setDefaultsOnInsert и upsert истинны, Mongoose применит значения по умолчанию, указанные в схеме модели, если создаётся новый документ.
• rawResult: если true, возвращает сырой результат из драйвера MongoDB

Пример:

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.

• тип {Строка}
• координаты {Массив}

Для операций обновления возвращает значение пути в $set. Полезно для написания методов get/set, которые могут работать как с операциями обновления, так и с save().

Пример:

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().

Объявляет условие запроса intersects для geometry().

Пример:

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 изменился с геттера на функцию. Если вам нужна старая синтаксис, используйте это.

Функция-обертка для вызова 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 Documents. У них нет метода save, геттеров/сеттеров, виртуальных свойств или других функций 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(), вам нужен плагин. См.:

• 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);

Объединяет другой объект Query или условия в этот.

При передаче объекта Query объединяются условия, выборка полей и параметры.

Устанавливает условие $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, для этого запроса. Ниже приведены текущие параметры, специфичные для 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, с которых следует читать.

Предпочтения:

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.

Псевдонимы

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:

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.

Псевдонимы

l   local
a   available
m   majority
lz  linearizable
s   snapshot

Подробнее о том, как использовать read concern, здесь.

Определяет условие запроса $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()

Определяет, какие поля документа включать или исключать (также известное как проекция запроса).

При использовании строкового синтаксиса добавление префикса - к пути помечает этот путь как исключённый. Если путь не имеет префикса -, он включается. Наконец, если путь имеет префикс +, это принудительно включает путь, что полезно для путей, исключённых на уровне схемы уровня схемы.

Проекция обязательно должна быть либо включительно-исключительной. Другими словами, вы должны либо перечислить поля для включения (что исключает все остальные), либо перечислить поля для исключения (что подразумевает, что все остальные поля включены). Поле _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() });

Устанавливает параметры запроса. Некоторые параметры имеют смысл только для определённых операций.

Параметры:

Следующие параметры предназначены только для find():

• таилевый
• 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(), findOneAndRemove(), findOneAndDelete(), updateOne(), и deleteOne():

• sort

Следующие параметры предназначены для findOneAndUpdate() и findOneAndRemove()

• rawResult

Следующие параметры предназначены для всех операций:

• 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()

Устанавливает опцию tailable (для использования с ограниченными коллекциями).

Пример:

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

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

Примечание:

Не может быть использован с distinct()

Выполняет запрос, возвращая Promise, который будет разрешен с документом(ами) или отклонен с ошибкой.

Подробнее о then() в JavaScript.

Преобразует этот запрос в настраиваемый, многократно используемый конструктор запроса с сохранением всех аргументов и опций.

Пример:

// 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.

• Используйте replaceOne() если вы хотите перезаписать весь документ, а не использовать атомарные операторы, такие как $set.

Примечание 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 изменился с геттера на функцию. Если вам нужна старая синтаксис, используйте это.

Устанавливает 3 параметра write concern для этого запроса:

• 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);

Возвращает asyncIterator для использования с for/await/of циклами. Эта функция только работает для find() запросов. Вам не нужно вызывать эту функцию явно, среда выполнения JavaScript вызовет её за вас.

Пример:

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

Node.js 10.x поддерживает async итераторы в явном виде без флагов. Вы можете включить async итераторы в Node.js 8.x, используя --harmony_async_iteration флаг.

Примечание: Эта функция не работает, если Symbol.asyncIterator неопределено. Если Symbol.asyncIterator неопределено, это означает, что ваша версия Node.js не поддерживает async итераторы.

Возвращает строковое представление этого запроса.

Подробнее о toString() в JavaScript.

Пример:

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

Флаг для отказа от использования $geoWithin.

mongoose.Query.use$geoWithin = false;

MongoDB 2.4 устарел $within, заменив его на $geoWithin. Mongoose использует $geoWithin по умолчанию (что полностью обратно совместимо с $within). Если вы используете более старую версию MongoDB, установите этот флаг на false, чтобы ваши запросы within() продолжали работать.