本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# \$1setOnInsert
<a name="setOnInsert"></a>

如果要插入文档，Amazon DocumentDB 中的`$setOnInsert`运算符用于设置字段的值，但是如果要更新文档，则该运算符无效。

**参数**
+ `field`：要设置的字段。
+ `value`：要分配给该字段的值。

## 示例（MongoDB 外壳）
<a name="setOnInsert-examples"></a>

以下示例演示了`$setOnInsert`运算符在 Amazon DocumentDB 中的用法。如果文档尚不存在，则它会创建一个新文档，但是如果正在更新该文档，则不起作用。

**创建示例文档**

```
db.users.insertOne({
  _id: 1,
  name: "John Doe",
  age: 30
})
```

**查询示例 1-更新现有文档**

```
db.users.update(
  { _id: 1 },
  {
    $set: { age: 31 },
    $setOnInsert: { createdAt: new Date() }
  },
  { upsert: true }
)
```

**输出 1**

```
{
  _id: 1,
  name: "John Doe",
  age: 31
}
```

输出显示文档已更新，但由于文档已经存在，因此**未添加**该`createdAt`字段。该`$setOnInsert`运算符仅在插入新文档时适用。

**查询示例 2-插入新文档（upsert）**

```
db.users.update(
  { _id: 2 },
  {
    $set: { name: "Jane Smith", age: 25 },
    $setOnInsert: { createdAt: new Date() }
  },
  { upsert: true }
)
```

**输出 2**

```
{
  _id: 2,
  name: "Jane Smith", 
  age: 25,
  createdAt: ISODate("2025-10-31T09:57:52.459Z")
}
}
```

## 代码示例
<a name="setOnInsert-code"></a>

要查看使用该`$setOnInsert`命令的代码示例，请选择要使用的语言的选项卡：

------
#### [ Node.js ]

```
const { MongoClient } = require('mongodb');

async function updateWithSetOnInsert() {
  const client = await MongoClient.connect('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
  const db = client.db('test');
  const users = db.collection('users');

  await users.updateOne(
    { _id: 1 },
    {
      $set: { age: 31 },
      $setOnInsert: { createdAt: new Date() }
    },
    { upsert: true }
  );

  const updatedUser = await users.findOne({ _id: 1 });
  console.log(updatedUser);

  await client.close();
}

updateWithSetOnInsert();
```

------
#### [ Python ]

```
from pymongo import MongoClient

def update_with_set_on_insert():
    client = MongoClient('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
    db = client['test']
    users = db['users']

    result = users.update_one(
        {'_id': 1},
        {
            '$set': {'age': 31},
            '$setOnInsert': {'createdAt': datetime.datetime.now()}
        },
        upsert=True
    )

    updated_user = users.find_one({'_id': 1})
    print(updated_user)

    client.close()

update_with_set_on_insert()
```

------