MongoDB API 参考
在此页面上
- mongodb.admin()
- admin.getDBNames()
- mongodb.db()
- database.getCollectionNames()
- database.collection()
- collection.find()
- Collection.findOne()
- collection.findOneAndUpdate()
- collection.findOneAndReplace()
- collection.findOneAndDelete()
- collection.insertOne()
- collection.insertMany()
- collection.updateOne()
- collection.updateMany()
- collection.deleteOne()
- collection.deleteMany()
- collection.aggregate()
- collection.count()
- collection.distinct()
- collection.bulkWrite()
mongodb.admin()
获取链接的MongoDB数据源中 admin
数据库的处理。 您可以使用它来运行MongoDB管理命令,例如 admin.getDBNames()
。
const mongodb = context.services.get("mongodb-atlas"); const admin = mongodb.admin();
参数
admin(): AdminDatabase
返回值
mongodb.admin()
方法返回一个AdminDatabase
对象。 该对象包含包装MongoDB database命令子集的辅助方法。 请参阅admin.getDBNames()
。
admin.getDBNames()
返回 MongoDB 数据源中的数据库名称列表。
const mongodb = context.services.get("mongodb-atlas"); const admin = mongodb.admin(); const dbNames = admin.getDBNames();
参数
getDBNames(): string[]
返回值
admin.getDBNames()
方法返回一个字符串数组,其中的每个元素是数据源中的数据库名称。
mongodb.db()
获取链接的 MongoDB 数据源中的数据库的句柄。
const mongodb = context.services.get("mongodb-atlas"); const db = mongodb.db("myDB");
参数
db(name: string): Database
Parameter | 类型 | 说明 |
---|---|---|
name | 字符串 | 数据库的名称。 |
返回值
mongodb.db()
方法返回一个 Database
对象,可用于访问指定数据库中的集合。
database.getCollectionNames()
返回数据库中的集合名称列表。
const mongodb = context.services.get("mongodb-atlas"); const db = mongodb.db("myDB"); const collectionNames = db.getCollectionNames();
参数
getCollectionNames(): string[]
返回值
database.getCollectionNames()
方法返回一个字符串数组,其中的每个元素是数据库中的集合名称。
database.collection()
从database
句柄获取链接的 MongoDB 数据源中集合的句柄。
const mongodb = context.services.get("mongodb-atlas"); const db = mongodb.db("myDB"); const collection = db.collection("myCollection");
参数
collection(name: string): Collection
Parameter | 类型 | 说明 |
---|---|---|
name | 字符串 | 集合的名称。 |
返回值
database.collection()
方法返回一个集合对象,可用于查询指定的集合。
collection.find()
查找集合或视图中与所提供的查询筛选器匹配的所有文档。返回一个游标对象,该对象允许您访问匹配的文档。
const query = { "reviews.0": { "$exists": true } }; const projection = { "_id": 0 }; return itemsCollection.find(query, projection) .sort({ name: 1 }) .toArray() .then(items => { console.log(`Successfully found ${items.length} documents.`) items.forEach(console.log) return items }) .catch(err => console.error(`Failed to find documents: ${err}`))
参数
find( query?: object, projection?: object, options?: object ): Cursor
Parameter | 类型 | 说明 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
query | object | |||||||||||
projection | object | 可选。 指定 MongoDB 应在匹配文档中包含或省略哪些字段的文档。 要返回匹配文档中的所有字段,请忽略此参数或指定空投影文档 ( 要返回特定字段和文档的
要保留特定字段,请在投影文档中指定值为
注意您可以指定要包含的字段或要排除的字段,但不能同时指定两者。例如,以下投影无效,因为它同时包含
该规则的例外是
| ||||||||||
options | object | 指定其他配置选项的对象。 | ||||||||||
options.session | ClientSession | 可选。 一个会话对象,表示操作发生的事务上下文。要了解详情,请参阅事务。 |
返回值
collection.find()
方法返回一个游标对象,它指向与指定查询匹配的任何文档。您可以使用以下游标方法处理和访问查询结果集中的文档:
方法 | 说明 | ||
---|---|---|---|
cursor.next() | |||
cursor.toArray() | 迭代游标直到耗尽,并返回一个 Promise,它解析为包含所有迭代的文档的数组。 例子
| ||
cursor.skip(amount) | 指定要从查询结果集中省略的匹配文档的数量。MongoDB 按排序顺序从结果集中省略文档,直到跳过指定的数字。如果查询还指定了限制,则已跳过的文档不会计入限制阈值。 注意在使用 | ||
cursor.limit(limit) | 指定在查询结果集中包含的最大文档数。如果结果集包含的文档超过指定的 注意在使用 | ||
cursor.sort(sort) | 根据 注意在使用 例子以下排序文档指定文档应先按
|
注意
您无法从函数中返回游标。相反,请使用 cursor.next()
或 cursor.toArray()
计算游标并返回结果。
Collection.findOne()
从集合或视图中查找单个文档。 如果有多个文档与查询匹配,则返回集合中第一个匹配的文档。
注意
findOne() 无法使用排序
作为一种变通方法,可使用带有sort()
和next()
游标方法的find()
从已排序的集合中返回单个文档。
collection.find({}).sort({"<Field Name>": 1}).next() .then(result => console.log("Found Document: ", result))
const query = { "quantity": { "$gte": 25 } }; const projection = { "title": 1, "quantity": 1, } return itemsCollection.findOne(query, projection) .then(result => { if(result) { console.log(`Successfully found document: ${result}.`); } else { console.log("No document matches the provided query."); } return result; }) .catch(err => console.error(`Failed to find document: ${err}`));
参数
findOne( query?: object, projection?: object, options?: object ): Promise<object | null>
Parameter | 类型 | 说明 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
query | object | |||||||||||
projection | object | 可选。 指定 MongoDB 应在匹配文档中包含或省略哪些字段的文档。 要返回匹配文档中的所有字段,请忽略此参数或指定空投影文档 ( 要返回特定字段和文档的
要保留特定字段,请在投影文档中指定值为
注意您可以指定要包含的字段或要排除的字段,但不能同时指定两者。例如,以下投影无效,因为它同时包含
该规则的例外是
| ||||||||||
options | object | 指定其他配置选项的对象。 | ||||||||||
options.session | ClientSession | 可选。 一个会话对象,表示操作发生的事务上下文。要了解详情,请参阅事务。 |
返回值
collection.findOne()
方法返回 Promise 解析为集合中与查询匹配的第一个文档。如果没有文档与指定的查询匹配,则该 Promise 解析为null
。
Promise<object | null>
collection.findOneAndUpdate()
更新集合或视图中的单个文档,并以其更新前或更新后的形式返回文档。
与collection.updateOne()
不同,此操作允许您使用相同命令以原子方式查找、修改和返回文档。 这样可以避免其他更新操作在单独的查找和更新操作之间更改文档的风险。
// Find the document that describes "lego" const query = { "name": "lego" }; // Set some fields in that document const update = { "$set": { "name": "blocks", "price": 20.99, "category": "toys" } }; // Return the updated document instead of the original document const options = { returnNewDocument: true }; return itemsCollection.findOneAndUpdate(query, update, options) .then(updatedDocument => { if(updatedDocument) { console.log(`Successfully updated document: ${updatedDocument}.`) } else { console.log("No document matches the provided query.") } return updatedDocument }) .catch(err => console.error(`Failed to find and update document: ${err}`))
参数
findOneAndUpdate( query: object, update: object, options?: object ): Promise<object | null>
Parameter | 类型 | 说明 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
query | object | |||||||||||
update | object | 一个更新文档,其中指定要使用MongoDB更新操作符执行的修改。 | ||||||||||
options | object | 指定其他配置选项的对象。 | ||||||||||
options.upsert | boolean | 可选。默认值: 一个布尔值,如果为 | ||||||||||
options.sort | boolean | 可选。 指定查询排序顺序。您可以指定一个或多个字段以进行排序,其中每个字段的值指示 MongoDB 应按升序 ( 例子以下排序文档指定文档应先按
| ||||||||||
options.projection | boolean | 指定 MongoDB 应在匹配文档中包含或省略哪些字段的文档。 要返回匹配文档中的所有字段,请忽略此参数或指定空投影文档 ( 要返回特定字段和文档的
要保留特定字段,请在投影文档中指定值为
注意您可以指定要包含的字段或要排除的字段,但不能同时指定两者。例如,以下投影无效,因为它同时包含
该规则的例外是
| ||||||||||
options.returnNewDocument | boolean | 可选。默认值: 如果为 | ||||||||||
options.session | ClientSession | 可选。 一个会话对象,表示操作发生的事务上下文。要了解详情,请参阅事务。 |
返回值
collection.findOneAndUpdate()
方法返回 Promise 解析为查询覆盖的单个文档。如果没有与指定查询匹配的文档,则该 Promise 解析为null
。
Promise<object | null>
注意
您可以通过设置 options.returnNewDocument
的值,来指定是返回文档的替换前版本还是替换后版本。默认情况下,returnNewDocument
为 false
,这表示 Promise 应解析为文档的更新前版本。
collection.findOneAndReplace()
覆盖集合或视图中的单个文档,并以替换前或替换后的形式返回该文档。
与collection.updateOne()
不同,此操作允许您使用相同命令以原子方式查找、修改和返回文档。 这样可以避免其他更新操作在单独的查找和更新操作之间更改文档的风险。
// Find the document that describes "lego" const query = { "name": "lego" }; // Replace it with a new document const replacement = { "name": "blocks", "price": 20.99, "category": "toys" }; // Return the original document as it was before being replaced const options = { "returnNewDocument": false }; return itemsCollection.findOneAndReplace(query, replacement, options) .then(replacedDocument => { if(replacedDocument) { console.log(`Successfully replaced the following document: ${replacedDocument}.`) } else { console.log("No document matches the provided query.") } return updatedDocument }) .catch(err => console.error(`Failed to find and replace document: ${err}`))
参数
findOneAndReplace( query: object, replacement: object, options?: object ): Promise<object | null>
Parameter | 类型 | 说明 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
query | object | |||||||||||
replacement | object | 将替换匹配文档的文档。 替换文档不能包含任何 MongoDB更新操作符。 | ||||||||||
options | object | 指定其他配置选项的对象。 | ||||||||||
options.upsert | boolean | 可选。默认值: 一个布尔值,如果为 | ||||||||||
options.sort | boolean | 可选。 指定查询排序顺序。您可以指定一个或多个字段以进行排序,其中每个字段的值指示 MongoDB 应按升序 ( 例子以下排序文档指定文档应先按
| ||||||||||
options.projection | boolean | 指定 MongoDB 应在匹配文档中包含或省略哪些字段的文档。 要返回匹配文档中的所有字段,请忽略此参数或指定空投影文档 ( 要返回特定字段和文档的
要保留特定字段,请在投影文档中指定值为
注意您可以指定要包含的字段或要排除的字段,但不能同时指定两者。例如,以下投影无效,因为它同时包含
该规则的例外是
| ||||||||||
options.returnNewDocument | boolean | 可选。默认值: 如果为 | ||||||||||
options.session | ClientSession | 可选。 一个会话对象,表示操作发生的事务上下文。要了解详情,请参阅事务。 |
返回值
collection.findOneAndReplace()
方法返回 Promise 解析为查询覆盖的单个文档。如果没有与指定查询匹配的文档,则该 Promise 解析为null
。
Promise<object | null>
注意
您可以通过设置 options.returnNewDocument
的值,来指定是返回文档的替换前版本还是替换后版本。默认情况下,returnNewDocument
为 false
,这表示 Promise 应解析为文档的更新前版本。
collection.findOneAndDelete()
从集合中删除单个文档,并返回已删除文档的原始状态。
与collection.updateOne()
不同,此操作允许您使用相同命令以原子方式查找、修改和返回文档。 这样可以避免其他更新操作在单独的查找和更新操作之间更改文档的风险。
// Find the first document that has a quantity greater than 25 const query = { "quantity": { "$gte": 25 } }; // Sort the documents in order of descending quantity before // deleting the first one. const options = { "sort": { "quantity": -1 } } return itemsCollection.findOneAndDelete(query, options) .then(deletedDocument => { if(deletedDocument) { console.log(`Successfully deleted document that had the form: ${deletedDocument}.`) } else { console.log("No document matches the provided query.") } return deletedDocument }) .catch(err => console.error(`Failed to find and delete document: ${err}`))
参数
findOneAndDelete( query: object, options?: object ): Promise<object | null>
Parameter | 类型 | 说明 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
query | object | |||||||||||
options | object | 指定其他配置选项的对象。 | ||||||||||
options.sort | boolean | 可选。 指定查询排序顺序。您可以指定一个或多个字段以进行排序,其中每个字段的值指示 MongoDB 应按升序 ( 例子以下排序文档指定文档应先按
| ||||||||||
options.projection | boolean | 指定 MongoDB 应在匹配文档中包含或省略哪些字段的文档。 要返回匹配文档中的所有字段,请忽略此参数或指定空投影文档 ( 要返回特定字段和文档的
要保留特定字段,请在投影文档中指定值为
注意您可以指定要包含的字段或要排除的字段,但不能同时指定两者。例如,以下投影无效,因为它同时包含
该规则的例外是
| ||||||||||
options.session | ClientSession | 可选。 一个会话对象,表示操作发生的事务上下文。要了解详情,请参阅事务。 |
返回值
collection.findOneAndDelete()
方法返回 Promise 解析为查询删除的单个文档。如果没有与指定查询匹配的文档,则该 Promise 解析为null
。
Promise<object | null>
collection.insertOne()
将单个文档插入到集合中,并返回插入的文档的 _id
。
const newItem = { "name": "Plastic Bricks", "quantity": 10, "category": "toys", "reviews": [{ "username": "legolover", "comment": "These are awesome!" }] }; itemsCollection.insertOne(newItem) .then(result => console.log(`Successfully inserted item with _id: ${result.insertedId}`)) .catch(err => console.error(`Failed to insert item: ${err}`))
参数
insertOne(document: object): Promise<object>
Parameter | 类型 | 说明 |
---|---|---|
document | object | 要插入到集合中的文档。 |
返回值
collection.insertOne()
方法返回一个 Promise,它解析为描述插入操作的文档。
Promise<object>
值 | 类型 | 说明 |
---|---|---|
result.insertedId | string | 插入操作添加到集合中的文档的 _id 值。 |
collection.insertMany()
将一个或多个文档插入到集合中,并返回一个列表,其中包含每个插入的文档的 _id
值。
const doc1 = { "name": "basketball", "category": "sports", "quantity": 20, "reviews": [] }; const doc2 = { "name": "football", "category": "sports", "quantity": 30, "reviews": [] }; return itemsCollection.insertMany([doc1, doc2]) .then(result => { console.log(`Successfully inserted ${result.insertedIds.length} items!`); return result }) .catch(err => console.error(`Failed to insert documents: ${err}`))
参数
insertMany( document: object, options?: { ordered?: boolean }, ): Promise<object>
Parameter | 类型 | 说明 |
---|---|---|
documents | object | 要插入到集合中的文档的数组。 |
options | object | 指定其他配置选项的对象。 |
options.ordered | boolean | 可选。 一个布尔值,指定mongod实例应该执行有序插入还是无序插入。 默认为 true 。 |
返回值
collection.insertMany()
方法返回一个 Promise,它解析为描述插入操作的文档。
Promise<object>
值 | 类型 | 说明 |
---|---|---|
result.insertedIds: Array<ObjectID> | string | 一个数组,其中包含插入操作添加到集合中的所有文档的 _id 值,按照将文档传递给该方法的顺序排列。 |
collection.updateOne()
更新集合中的单个文档并返回有关该操作的元数据。
const query = { "name": "football" }; const update = { "$push": { "reviews": { "username": "tombradyfan", "comment": "I love football!!!" } } }; const options = { "upsert": false }; itemsCollection.updateOne(query, update, options) .then(result => { const { matchedCount, modifiedCount } = result; if(matchedCount && modifiedCount) { console.log(`Successfully added a new review.`) } }) .catch(err => console.error(`Failed to add review: ${err}`))
参数
updateOne( query: object, update: object, options?: object ): Promise<object>
Parameter | 类型 | 说明 |
---|---|---|
query | object | |
update | object | 一个更新文档,其中指定要使用MongoDB更新操作符执行的修改。 |
options | object | 指定其他配置选项的对象。 |
options.upsert | boolean | 可选。默认值: 一个布尔值,如果为 |
options.session | ClientSession | 可选。 一个会话对象,表示操作发生的事务上下文。要了解详情,请参阅事务。 |
返回值
collection.updateOne()
方法返回一个 Promise,该 Promise 会解析为描述更新操作的文档。
Promise<object>
值 | 类型 | 说明 |
---|---|---|
result.matchedCount | number | 集合中与所提供的查询匹配的文档数。 |
result.modifiedCount | number | 更新操作所修改的文档数量。 |
result.upsertedId | string | 更新或插入操作插入的文档的 _id 值。只有在已启用 upsert 选项并且更新查询与任何文档都不匹配时,才会出现该值。 |
collection.updateMany()
更新集合中的一个或多个文档,并返回有关该操作的元数据。
const query = {}; const update = { "$mul": { "quantity": 10 } }; const options = { "upsert": false } return itemsCollection.updateMany(query, update, options) .then(result => { const { matchedCount, modifiedCount } = result; console.log(`Successfully matched ${matchedCount} and modified ${modifiedCount} items.`) return result }) .catch(err => console.error(`Failed to update items: ${err}`))
参数
updateMany( query: object, update: object, options?: object ): Promise<object>
Parameter | 类型 | 说明 |
---|---|---|
query | object | |
update | object | 一个更新文档,其中指定要使用MongoDB更新操作符执行的修改。 |
options | object | 指定其他配置选项的对象。 |
options.upsert | boolean | 可选。默认值: 一个布尔值,如果为 |
options.session | ClientSession | 可选。 一个会话对象,表示操作发生的事务上下文。要了解详情,请参阅事务。 |
返回值
collection.updateMany()
方法返回一个 Promise,该 Promise 会解析为描述更新操作的文档。
Promise<object>
值 | 类型 | 说明 |
---|---|---|
result.matchedCount | number | 集合中与所提供的查询匹配的文档数。 |
result.modifiedCount | number | 更新操作所修改的文档数量。 |
result.upsertedId | string | 更新或插入操作插入的文档的 _id 值。只有在已启用 upsert 选项并且更新查询与任何文档都不匹配时,才会出现该值。 |
collection.deleteOne()
从集合中删除单个文档。
const query = { "name": "lego" }; itemsCollection.deleteOne(query) .then(result => console.log(`Deleted ${result.deletedCount} item.`)) .catch(err => console.error(`Delete failed with error: ${err}`))
参数
deleteOne( query: object, options?: object ): Promise<object>
返回值
collection.deleteOne()
方法返回一个 Promise,该 Promise 会解析为描述删除操作的文档。
Promise<object>
值 | 类型 | 说明 |
---|---|---|
result.deletedCount | number | 集合中通过删除操作删除的文档数。 |
collection.deleteMany()
从集合中删除一个或多个文档。
const query = { "reviews": { "$size": 0 } }; itemsCollection.deleteMany(query) .then(result => console.log(`Deleted ${result.deletedCount} item(s).`)) .catch(err => console.error(`Delete failed with error: ${err}`))
参数
deleteMany( query: object, options?: object ): Promise<object>
返回值
collection.deleteMany()
方法返回一个 Promise,该 Promise 会解析为描述删除操作的文档。
Promise<object>
值 | 类型 | 说明 |
---|---|---|
result.deletedCount | number | 集合中通过删除操作删除的文档数。 |
collection.aggregate()
执行聚合管道,并返回一个用于访问管道输出文档的游标。
const pipeline = [ { "$group": { "_id": "$customerId", "numPurchases": { "$sum": 1 }, "numItemsPurchased": { "$sum": { "$size": "$items" } } } }, { "$addFields": { "averageNumItemsPurchased": { "$divide": ["$numItemsPurchased", "$numPurchases"] } } } ] return purchasesCollection.aggregate(pipeline).toArray() .then(customers => { console.log(`Successfully grouped purchases for ${customers.length} customers.`) for(const customer of customers) { console.log(`customer: ${customer._id}`) console.log(`num purchases: ${customer.numPurchases}`) console.log(`total items purchased: ${customer.numItemsPurchased}`) console.log(`average items per purchase: ${customer.averageNumItemsPurchased}`) } return customers }) .catch(err => console.error(`Failed to group purchases by customer: ${err}`))
参数
aggregate( pipeline: object[], options?: object ): Cursor
Parameter | 类型 | 说明 |
---|---|---|
pipeline | object[] | 一个或多个聚合管道阶段的数组。 |
options | object | 指定其他配置选项的对象。 |
options.session | ClientSession | 可选。 一个会话对象,表示操作发生的事务上下文。要了解详情,请参阅事务。 |
返回值
collection.aggregate()
方法返回一个游标对象,它指向聚合管道的最后阶段输出的任何文档。您可以使用以下方法处理和访问聚合结果集中的文档:
方法 | 说明 | ||
---|---|---|---|
cursor.next() | |||
cursor.toArray() | 迭代游标直到耗尽,并返回一个 Promise,它解析为包含所有迭代的文档的数组。 例子
| ||
cursor.skip(amount) | 指定要从聚合结果集中省略的匹配文档的数量。MongoDB 会按排序顺序从结果集中省略文档,直到跳过指定的数字。 注意在使用 |
注意
您无法从函数中返回游标。相反,请使用 cursor.next()
或 cursor.toArray()
计算游标并返回结果。
collection.count()
返回集合或视图中与给定查询匹配的文档的数量。
return itemsCollection.count({ "reviews.0": { "$exists": true } }) .then(numDocs => console.log(`${numDocs} items have a review.`)) .catch(err => console.error("Failed to count documents: ", err))
参数
count( query?: object, options?: object ): Promise<number>
返回值
collection.count()
方法返回一个 Promise,它解析为集合中与查询匹配的文档的整数个数。
Promise<number>
值 | 说明 |
---|---|
Count Result numDocs: <integer> | 集合中与所提供的查询匹配的文档数。 |
collection.distinct()
查找与给定查询筛选器匹配的文档,并返回所有匹配文档中特定字段的不同值的列表。
1 const taskCollection = context.services.get("mongodb-atlas") 2 .db("tracker").collection("tasks"); 3 4 return taskCollection.distinct("status", {}) 5 .then(results => { 6 console.log(JSON.stringify(results)); 7 console.log(results.length); 8 }) 9 .catch(err => console.error(err))
参数
distinct( field: string, query: object, options?: object ): Promise<any[]>
返回值
collection.distinct()
方法会返回 Promise,该 Promise 解析为由不同值组成的数组。
Promise<any[]>
collection.bulkWrite()
使用单个调用对集合运行多个插入、更新和删除操作。在 bulkWrite()
函数中,您可以指定一个或多个以下写入操作:
insertOne
updateOne
updateMany
deleteOne
deleteMany
replaceOne
注意
只能对单个集合执行批量写入。
exports = async function(arg){ const doc1 = { "name": "velvet elvis", "quantity": 20, "reviews": [] }; const doc2 = { "name": "mock turtleneck", "quantity": 30, "reviews": [] }; var collection = context.services.get("mongodb-atlas") .db("store") .collection("purchases"); return await collection.bulkWrite( [{ insertOne: doc1}, { insertOne: doc2}], {ordered:true}); };
参数
bulkWrite( operations: object[], options?: object ): Promise<null>
Parameter | 类型 | 说明 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
operations | object[] | 要执行的 bulkWrite 操作的数组。支持的操作示例如下:
| |||||||||||
options | object | 指定其他配置选项的对象。 | |||||||||||
options.ordered | boolean | 可选。默认值: 如果为 如果为 注意无序操作在理论上速度更快,因为 MongoDB 可并行执行此类操作,但只应在写入操作不依赖顺序时使用该操作。 | |||||||||||
options.bypassDocumentValidation | boolean | 可选。默认值: 如果为 | |||||||||||
options.session | ClientSession | 可选。 一个会话对象,表示操作发生的事务上下文。要了解详情,请参阅事务。 |
返回值
collection.bulkWrite()
函数返回一个 Promise 解析为null
。
Promise<null>