Rename a Field In MongoDB Documents
Today in this article, we shall learn MongoDB – how to rename a field in Documents in MongoDB.
Updated November 2026: current updateMany syntax, safety notes on overwrites and large collections, a Mongoose section and an FAQ.
We will perform Rename a field/property for all the documents in the database and we will also see Rename specific field/property conditionally
We will cover below aspects below,
I have below Mongo Collection where my fields are defined as below.
I have a field name called “EmpID” which I want to rename to “EmpNumber“
Let’s get started step by step details on how to achieve rename.
Please open the command prompt or PowerShell and log in to your database using a connection string.
We will first login to MongoDB and then switch to using the required database and the collection
use <DBName>
Command Pattern
{$rename: { <field1>: <newName1>, <field2>: <newName2>, ... } }
You can specify one or multiple fields for the renaming support.
Rename a field for all the documents in the database
Command:
db.employee.update({}, { $rename: { "EmpID": "EmpNumber" } },false, true );
OR
db.employee.updateMany({}, { $rename: { "EmpID": "EmpNumber" } },false, true );
Example
db.employee.updateMany({}, { $rename: { “EmpID”: “EmpNumber” } });
WriteResult({ “nMatched” : 4, “nUpserted” : 0, “nModified” : 4 })
Rename fields for the matching criteria in the database
We can rename fields based on some filter criteria. Example – Below we are renaming the fields when “Name” fields match with a value i.e “John“.
Example
db.employee.updateMany({ “Name”: “John” }, { $rename: { “EmpNumber”: “EmpID” } })
WriteResult({ “nMatched” : 1, “nUpserted” : 0, “nModified” : 1 })
Rename specific fields for hierarchal criteria in the database
If you have nested objects defined in the schema then one can use the below convention to perform rename.
Example
db.employee.update({}, {$rename:{"Employee.EmpID":"Employee.EmpNumber"}}, false, true);
OR
db.employee.updateMany({}, {$rename:{"Employee.EmpID":"Employee.EmpNumber"}}, false, true);
References:
That’s all! Happy coding!
Does this help you fix your issue?
Do you have any better solutions or suggestions? Please sound off your comments below.
Please bookmark this page and share it with your friends. Please Subscribe to the blog to receive notifications on freshly published (2026) best practices and guidelines for software design and development.
What happens when the field is missing, the new name exists, or the collection is large?
$rename skips documents that lack the old field, silently overwrites any existing field with the new name, and is not one all-or-nothing operation across documents. Filter carefully and verify the result before you trust a migration.
Missing source field: a document without the old field is left alone and no error is raised. Compare modifiedCount with matchedCount in the result to see how many documents actually changed. A big gap usually means your filter was too broad.
Existing target field: if a document already has a field with the new name, $rename deletes it and replaces it with the old field’s value. That data is gone. To guard against it, filter on the old field with $exists: true and the new field with $exists: false. Documents that have both fields won’t match, so query for them separately and decide what to keep.
Atomicity: each document is updated atomically, but the updateMany call as a whole is not one transaction. If it stops halfway, you’ll have a mix of old and new names. Re-running is safe, because renamed documents no longer match the filter.
Note: Think of a clerk relabeling folders in a filing cabinet one at a time. Each folder is either relabeled or not, but if the clerk is interrupted, the cabinet holds both labels until the clerk resumes.
On a large collection, follow these steps:
- Back up first: take a backup or snapshot before you start, so you have a way back that doesn’t depend on the rename itself.
- Filter with $exists: touch only documents that still need the change.
- Consider a temporary index: an index on the old field, used with a hint, can speed up finding those documents. Drop it afterwards, since it adds write cost while it exists.
To verify, count documents that still have the old field. The answer should be 0. To roll back, run the inverse rename (new name to old name), as long as nothing else has started writing the new name that you want to keep.
For zero-downtime rollouts, make the application read both names while the migration runs, then remove the fallback once the count hits 0. If the value also needs transforming, $rename can’t do it. Use an aggregation-pipeline update with $set and $unset instead.
Frequently asked questions
Can I rename several fields in one MongoDB update?
Yes. List multiple old-to-new pairs inside one $rename object, for example { $rename: { "EmpID": "EmpNumber", "Name": "EmpName" } }. Each pair is applied in the same update to every matched document. The new name must differ from the old one, and any existing field that already uses a target name is overwritten.
How do I rename a field inside an array of objects in MongoDB?
Plain $rename cannot reach fields inside array elements. Use an aggregation-pipeline update that rebuilds the array with $map and $mergeObjects, setting the new key and removing the old one in each element. Test the pipeline on a copy of the data first, because a mistake rewrites the whole array.
How do I undo a MongoDB field rename?
Run the inverse $rename, swapping the old and new names. Add a filter such as { "EmpNumber": { $exists: true } } so you only touch documents that have the field you are renaming back. Take a backup before the first rename, because a rename that overwrote an existing target field cannot be reversed this way. The overwritten value is gone.
Why does the old field still show up after I changed my Mongoose schema?
A schema change only affects how Mongoose writes and reads documents from then on. Existing documents keep their stored field names until you migrate them with $rename. Run that migration through the native collection (mongoose.connection.db.collection(...).updateMany(...)) or with strict: false, so Mongoose does not strip the operation because the old field is no longer in the schema.