$rename¶
-
$rename
¶ New in version 1.7.2.
Syntax:
{$rename: { <old name1>: <new name1>, <old name2>: <new name2>, ... } }
The
$rename
operator updates the name of a field. The new field name must differ from the existing field name.Consider the following example:
This operation renames the field
nickname
toalias
, and the fieldcell
tomobile
.If the document already has a field with the new field name, the
$rename
operator removes that field and renames the field with the old field name to the new field name.The
$rename
operator will expand arrays and sub-documents to find a match for field names. When renaming a field in a sub-document to another sub-document or to a regular field, the sub-document itself remains.Consider the following examples involving the sub-document of the following document:
To rename a sub-document, call the
$rename
operator with the name of the sub-document as you would any other field:This operation renames the sub-document
nmae
toname
:To rename a field within a sub-document, call the
$rename
operator using the dot notation to refer to the field. Include the name of the sub-document in the new field name to ensure the field remains in the sub-document:This operation renames the sub-document field
first
tofname
:To rename a field within a sub-document and move it to another sub-document, call the
$rename
operator using the dot notation to refer to the field. Include the name of the new sub-document in thenew name
:This operation renames the sub-document field
last
tolname
and moves it to the sub-documentcontact
:If the new field name does not include a sub-document name, the field moves out of the subdocument and becomes a regular document field.
Consider the following behavior when the specified old field name does not exist:
When renaming a single field and the existing field name refers to a non-existing field, the
$rename
operator does nothing, as in the following:This operation does nothing because there is no field named
wife
.When renaming multiple fields and all of the old field names refer to non-existing fields, the
$rename
operator does nothing, as in the following:This operation does nothing because there are no fields named
wife
,vice
, andoffice
.When renaming multiple fields and some but not all old field names refer to non-existing fields, the
$rename
operator performs the following operations:Changed in version 2.2.
- Renames the fields that exist to the specified new field names.
- Ignores the non-existing fields.
Consider the following query that renames both an existing field
mobile
and a non-existing fieldwife
. The field namedwife
does not exist and$rename
sets the field to a name that already existsalias
.This operation renames the
mobile
field tocell
, and has no other impact action occurs.Note
Before version 2.2, when renaming multiple fields and only some (but not all) old field names refer to non-existing fields:
- For the fields with the old names that do exist, the
$rename
operator renames these fields to the specified new field names. - For the fields with the old names that do not exist:
Consider the following operation that renames both the field
mobile
, which exists, and the fieldwife
, which does not exist. The operation tries to set the field namedwife
toalias
, which is the name of an existing field:Before 2.2, the operation renames the field
mobile
tocell
and drops thealias
field even though the fieldwife
does not exist: