replaceOne() în MongoDB & NoSQL

db.colectie.replaceOne(filtru, documentNou, { upsert, collation, hint })

Ce face replaceOne()

replaceOne() păstrează doar _id-ul documentului găsit și înlocuiește tot restul cu documentul dat. Spre deosebire de updateOne cu $set, nu modifică doar unele câmpuri: orice câmp care lipsește din documentul nou este șters.

Documentul de înlocuire nu poate conține operatori ($set, $inc). Este util când aplicația are deja obiectul complet, actualizat, și vrei să-l salvezi așa cum este. Cu upsert: true, documentul este creat dacă nu există.

Parametri

Parametru	Descriere
filtru	Ce document se înlocuiește (primul găsit).
documentNou	Documentul complet, fără operatori de actualizare.
upsert	Creează documentul dacă nu există.

Ce returnează

Un rezultat cu matchedCount, modifiedCount și upsertedCount.

Exemple

Exemplele de pe această pagină pornesc de la datele de mai jos. Rulează mai întâi acest cod, apoi exemplul.

use magazin
db.comenzi.insertMany([
  { _id: 1, client: 'Ana', oras: 'Iași', total: 120, status: 'livrata', produse: ['caiet', 'pix'] },
  { _id: 2, client: 'Dan', oras: 'Cluj', total: 85, status: 'noua', produse: ['carte'] },
  { _id: 3, client: 'Ioana', oras: 'Iași', total: 240, status: 'livrata', produse: ['rucsac', 'caiet', 'pix'] },
  { _id: 4, client: 'Mihai', oras: 'Brașov', total: 60, status: 'anulata', produse: [] }
])

Exemplul 1: Salvarea unei comenzi modificate în aplicație

Documentul 2 este înlocuit în întregime.

db.comenzi.replaceOne({ _id: 2 }, { client: 'Dan', oras: 'Cluj', total: 95, status: 'platita' })

Ieșire în mongosh

{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}

Exemplul 2: Câmpul produse a dispărut

După exemplul 1, documentul nu mai are produse, pentru că nu era în documentul nou.

db.comenzi.findOne({ _id: 2 })

Ieșire în mongosh

{ _id: 2, client: 'Dan', oras: 'Cluj', total: 95, status: 'platita' }

Exemplul 3: Operatorii nu sunt permiși

Pentru modificări parțiale folosește updateOne.

db.comenzi.replaceOne({ _id: 2 }, { $set: { total: 100 } })

Ieșire în mongosh

MongoInvalidArgumentError: Replacement document must not contain atomic operators

Greșeli frecvente

• Cea mai frecventă greșeală: folosești replaceOne cu un obiect parțial și pierzi câmpurile pe care nu le-ai trimis.
• _id-ul nu se poate schimba; dacă documentul nou are alt _id, primești eroare.

Comenzi înrudite

• upsert: true și $setOnInsert: Cu upsert: true, updateOne actualizează documentul găsit sau, dacă nu există, îl creează; $setOnInsert scrie câmpuri doar la creare.
• findOneAndUpdate(): Actualizează un document și îl întoarce, atomic, într-un singur pas; există și findOneAndDelete și findOneAndReplace.
• $rename: Operatorul $rename schimbă numele unui câmp în documente, inclusiv mutarea lui dintr-un subdocument la nivelul principal.