Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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

L'`$setOnInsert`opérateur dans Amazon DocumentDB est utilisé pour définir la valeur d'un champ si un document est inséré, mais cela n'a aucun effet si le document est mis à jour.

**Paramètres**
+ `field`: Le champ à définir.
+ `value`: valeur à attribuer au champ.

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

L'exemple suivant illustre l'utilisation de l'`$setOnInsert`opérateur dans Amazon DocumentDB. Cela crée un nouveau document s'il n'existe pas déjà, mais cela n'a aucun effet si le document est mis à jour.

**Création d'exemples de documents**

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

**Exemple de requête 1 - Mettre à jour un document existant**

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

**Sortie 1**

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

La sortie indique que le document a été mis à jour, mais le `createdAt` champ **n'a PAS été ajouté** car le document existait déjà. L'`$setOnInsert`opérateur ne s'applique que lors de l'insertion de nouveaux documents.

**Exemple de requête 2 - Insérer un nouveau document (upsert)**

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

**Produit 2**

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

## Exemples de code
<a name="setOnInsert-code"></a>

Pour afficher un exemple de code relatif à l'utilisation de la `$setOnInsert` commande, choisissez l'onglet correspondant à la langue que vous souhaitez utiliser :

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

------