本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

如果正在插入文件，Amazon DocumentDB 中的`$setOnInsert`運算子會用來設定欄位的值，但如果正在更新文件，則不會有任何影響。

**參數**
+ `field`：要設定的欄位。
+ `value`：要指派給欄位的值。

## 範例 (MongoDB Shell)
<a name="setOnInsert-examples"></a>

下列範例示範 Amazon DocumentDB 中`$setOnInsert`運算子的使用情況。如果文件尚未存在，它會建立新的文件，但如果文件正在更新，則不會有任何影響。

**建立範例文件**

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

------