MongoDB Field Update Operator - $rename

Description

The $rename operator is used to updates the name of a field. It is required to mention the new field name is different from the existing field name.

Syntax:

{$rename: { <old_name1>: <new_name1>, <old_name2>: <new_name2>, ... } }

Parameters:

Our database name is 'myinfo' and our collection name is "employee". Here, is the collection bellow.

Sample collection "employee"

{
        "_id" : 2,
        "emp_id" : 1232,
        "pinfo" : {
                "empfname" : "Robart",
                "emplname" : "Bolt"
        },
        "phno" : "123-123-1235",
        "emale" : "[email protected]",
        "offinfo" : [
                "administration",
                "MD"
        ]
}
}

Example of field update operator - $rename

If we want to change the field name offinfo to service_details and emale to email the following mongodb statement can be used:

> db.employee.update( { emp_id: 1232 }, { $rename: { 'offinfo': 'service_details', 'emale': 'email' } } );

To see the updated output -

> db.employee.find().pretty();

N.B. find() method displays the documents in a non structured format but to display the results in a formatted way, the pretty() method can be used.

Output of the command:

{
        "_id" : 2,
        "email" : "[email protected]",
        "emp_id" : 1232,
        "phno" : "123-123-1235",
        "pinfo" : {
                "empfname" : "Robart",
                "emplname" : "Bolt"
        },
        "service_details" : [
                "administration",
                "MD"
        ]
}

Example of $rename to rename a sub-document

If we want to rename the sub-document pinfo, following mongodb queries can be used -

> db.employee.update( { emp_id: 1232 }, { $rename: { 'pinfo': 'personal'} } );

To see the updated output -

> db.employee.find().pretty();

N.B. find() method displays the documents in a non structured format but to display the results in a formatted way, the pretty() method can be used.

Output of the command:

{
        "_id" : 2,
        "email" : "[email protected]",
        "emp_id" : 1232,
        "personal" : {
                "empfname" : "Robart",
                "emplname" : "Bolt"
        },
        "phno" : "123-123-1235",
        "service_details" : [
                "administration",
                "MD"
        ]
}

Example of $rename operator to rename a field in a sub-document

If we want to rename empfname field with fname in sub-document personal, the following mongodb command can be used -

> db.employee.update( { emp_id: 1232 }, { $rename: { "personal.empfname": "personal.fname"} } );

Here in the above example, to rename the field empfname within the sub-document personal, the $rename operator have been used with the dot notation to ensure the field remains in the sub-document.

To see the updated output -

> db.employee.find().pretty();

N.B. find() method displays the documents in a non structured format but to display the results in a formatted way, the pretty() method can be used.

Output of the command:

{
        "_id" : 2,
        "email" : "[email protected]",
        "emp_id" : 1232,
        "personal" : {
                "emplname" : "Bolt",
                "fname" : "Robart"
        },
        "phno" : "123-123-1235",
        "service_details" : [
                "administration",
                "MD"
        ]
}

Example of $rename operator to rename a field and move it to another sub-document

If we want to rename the field emplname to last_name of sub-document personal and move it from personal sub-document the following mongodb command can be used -

> db.employee.update( { emp_id: 1232 }, { $rename: { "personal.emplname": "pinfo.last_name"} } );

Here in the above example, to rename the field emplname within the sub-document personal, the $rename operator have been used with the dot notation to ensure the field remains in the sub-document and this operation renames the sub-document field emplname to last_name and moves it to the sub-document pinfo.

If no sub-document name is included with the new field name, the field becomes a regular document field.

To see the updated output -

> db.employee.find().pretty();

N.B. find() method displays the documents in a non structured format but to display the results in a formatted way, the pretty() method can be used.

Output of the command:

{
        "_id" : 2,
        "email" : "[email protected]",
        "emp_id" : 1232,
        "personal" : {
                "fname" : "Robart"
        },
        "phno" : "123-123-1235",
        "pinfo" : {
                "last_name" : "Bolt"
        },
        "service_details" : [
                "administration",
                "MD"
        ]
}

Example:

At the time of renaming a field, If the field does not exist in the document , the rename operation will do nothing.

Here is the example -

> db.employee.update( { emp_id: 1232 }, { $rename: { "city": "town"} } );

Here in the above example, we want to rename the field city to town, but the city field does not exist in the document, so this operation will do nothing. Thus, if we want to rename multiple fields, and if all those field does not exist in the document, the operation will do nothing.

Previous: $inc
Next: $set