仅当 upsert作导致插入新文档时，该 $setOnInsert 运算符才用于设置字段值。 如果文档已存在且正在更新，则 $setOnInsert 运算符不起作用。 此运算符特别适用于设置仅在创建新文档时应应用的默认值或初始化数据。
Syntax
{
$setOnInsert: {
<field1>: <value1>,
<field2>: <value2>,
...
}
}
参数
| 参数 | Description |
|---|---|
field |
仅在插入时设置的字段的名称。 可以是顶级字段，也可以对嵌套字段使用点表示法。 |
value |
仅在插入新文档时分配给字段的值。 可以是任何有效的 BSON 类型。 |
例子
请考虑商店集合中的这个示例文档。
{
"_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4",
"name": "First Up Consultants | Beverage Shop - Satterfieldmouth",
"location": {
"lat": -89.2384,
"lon": -46.4012
},
"staff": {
"totalStaff": {
"fullTime": 8,
"partTime": 20
}
},
"sales": {
"totalSales": 75670,
"salesByCategory": [
{
"categoryName": "Wine Accessories",
"totalSales": 34440
},
{
"categoryName": "Bitters",
"totalSales": 39496
},
{
"categoryName": "Rum",
"totalSales": 1734
}
]
},
"promotionEvents": [
{
"eventName": "Unbeatable Bargain Bash",
"promotionalDates": {
"startDate": {
"Year": 2024,
"Month": 6,
"Day": 23
},
"endDate": {
"Year": 2024,
"Month": 7,
"Day": 2
}
},
"discounts": [
{
"categoryName": "Whiskey",
"discountPercentage": 7
},
{
"categoryName": "Bitters",
"discountPercentage": 15
},
{
"categoryName": "Brandy",
"discountPercentage": 8
},
{
"categoryName": "Sports Drinks",
"discountPercentage": 22
},
{
"categoryName": "Vodka",
"discountPercentage": 19
}
]
},
{
"eventName": "Steal of a Deal Days",
"promotionalDates": {
"startDate": {
"Year": 2024,
"Month": 9,
"Day": 21
},
"endDate": {
"Year": 2024,
"Month": 9,
"Day": 29
}
},
"discounts": [
{
"categoryName": "Organic Wine",
"discountPercentage": 19
},
{
"categoryName": "White Wine",
"discountPercentage": 20
},
{
"categoryName": "Sparkling Wine",
"discountPercentage": 19
},
{
"categoryName": "Whiskey",
"discountPercentage": 17
},
{
"categoryName": "Vodka",
"discountPercentage": 23
}
]
}
]
}
示例 1：基本$setOnInsert用法
若要创建或更新存储记录，但在创建新存储时仅设置某些初始化字段。
db.stores.updateOne(
{ "_id": "new-store-001" },
{
$set: {
"name": "Trey Research Electronics - Downtown",
"sales.totalSales": 0
},
$setOnInsert: {
"createdDate": new Date(),
"status": "new",
"staff.totalStaff.fullTime": 0,
"staff.totalStaff.partTime": 0,
"version": 1
}
},
{ upsert: true }
)
此作返回以下结果。
{
acknowledged: true,
insertedId: 'new-store-001',
matchedCount: 0,
modifiedCount: Long("0"),
upsertedCount: 1
}
_id: "new-store-001"由于文档不存在，此作将创建以下新文档：
{
"_id": "new-store-001",
"name": "Trey Research Electronics - Downtown",
"sales": {
"totalSales": 0
},
"createdDate": ISODate("2025-06-05T10:30:00.000Z"),
"status": "new",
"staff": {
"totalStaff": {
"fullTime": 0,
"partTime": 0
}
},
"version": 1
}
示例 2：使用现有文档$setOnInsert
现在，让我们尝试使用不同的值重新插入同一文档：
db.stores.updateOne(
{ "_id": "new-store-001" },
{
$set: {
"name": "Trey Research Electronics - Downtown Branch",
"sales.totalSales": 5000
},
$setOnInsert: {
"createdDate": new Date(),
"status": "updated",
"staff.totalStaff.fullTime": 10,
"staff.totalStaff.partTime": 5,
"version": 2
}
},
{ upsert: true }
)
由于文档已存在，因此只会 $set 应用作，并 $setOnInsert 将被忽略：
{
"_id": "new-store-001",
"name": "Trey Research Electronics - Downtown Branch",
"sales": {
"totalSales": 5000
},
"createdDate": ISODate("2025-06-05T10:30:00.000Z"),
"status": "new",
"staff": {
"totalStaff": {
"fullTime": 0,
"partTime": 0
}
},
"version": 1
}
示例 3：包含嵌套对象的复杂$setOnInsert
可用于 $setOnInsert 初始化复杂的嵌套结构：
db.stores.updateOne(
{ "name": "Adatum Gaming Paradise - Mall Location" },
{
$set: {
"location.lat": 35.6762,
"location.lon": 139.6503
},
$setOnInsert: {
"_id": "gaming-store-mall-001",
"createdDate": new Date(),
"status": "active",
"staff": {
"totalStaff": {
"fullTime": 8,
"partTime": 12
},
"manager": "Alex Johnson",
"departments": ["gaming", "accessories", "repairs"]
},
"sales": {
"totalSales": 0,
"salesByCategory": []
},
"operatingHours": {
"weekdays": "10:00-22:00",
"weekends": "09:00-23:00"
},
"metadata": {
"version": 1,
"source": "store-management-system"
}
}
},
{ upsert: true }
)
示例 4：对数组使用$setOnInsert
可以初始化数组和复杂数据结构：
db.stores.updateOne(
{ "address.city": "New Tech City" },
{
$set: {
"name": "Future Electronics Hub",
"sales.totalSales": 25000
},
$setOnInsert: {
"_id": "future-electronics-001",
"establishedDate": new Date(),
"categories": ["electronics", "gadgets", "smart-home"],
"promotionEvents": [],
"ratings": {
average: 0,
count: 0,
reviews: []
},
"inventory": {
lastUpdated: new Date(),
totalItems: 0,
lowStockAlerts: []
}
}
},
{ upsert: true }
)
重要
运算符 $setOnInsert 仅在 upsert作期间生效（{ upsert: true }）。
如果文档存在， $setOnInsert 则完全忽略字段。
$setOnInsert 通常用于 $set 处理单个作中的更新和插入方案。
可以与其他更新运算符（如$setOnInsert等$inc）结合使用$push。
运算符 $setOnInsert 非常适合用于设置创建时间戳、默认值和初始化数据。
相关内容
- 查看用于 从 MongoDB 迁移到 Azure DocumentDB 的选项。
- 详细了解 与 MongoDB 的功能兼容性。