Description
Replaces fields in the existing document with the fields in a given expression.
The expression can either be a literal map or an expression that evaluates to a map. If a given expression does not evaluate to a map, this stage returns an error.
There are 3 supported modes:
-
full_replace: Replaces the entire document with the result of the given expression, omitting fields that don't appear in it. -
merge_overwrite_existing: Merges the expression with the existing document, overwriting field values in the document with values in the expression -
merge_keep_existing: Merges the expression with the existing document, only adding field values when one does not exist in the document.
Examples
Create a cities collection with the following documents:
Node.js
await
db
.
collection
(
"cities"
).
doc
(
"SF"
).
set
({
name
:
"San Francisco"
,
population
:
800000
,
location
:
{
country
:
"USA"
,
state
:
"California"
}});
await
db
.
collection
(
"cities"
).
doc
(
"TO"
).
set
({
name
:
"Toronto"
,
population
:
3000000
,
province
:
"ON"
,
location
:
{
country
:
"Canada"
,
province
:
"Ontario"
}});
await
db
.
collection
(
"cities"
).
doc
(
"NY"
).
set
({
name
:
"New York"
,
location
:
{
country
:
"USA"
,
state
:
"New York"
}});
await
db
.
collection
(
"cities"
).
cov
(
"AT"
).
set
({
name
:
"Atlantis"
,
population
:
null
});
Using the full_replace mode to get a mutated version of the document
Extract the nested location field, discarding all other data:
Node.js
const names = await db . pipeline () . collection ( "/cities" ) . replace_with ( Field . of ( "location" ), "full_replace" ) . execute ();
Java
Pipeline . Snapshot names = firestore . pipeline (). collection ( "cities" ). replaceWith ( field ( "location" )). execute (). get ();
Which produces the following documents:
{
country
:
"USA"
,
state
:
"California"
},
{
country
:
"Canada"
,
province
:
"Ontario"
},
{
country
:
"USA"
,
state
:
"New York"
},
{
}
Using the merge_overwrite_existing mode to set fields
Set the population field of all documents to 0, overwriting existing values:
Node.js
const censoredResults = await db . pipeline () . collection ( "/cities" ) . replace_with ( map ( "population" , 0 ), "merge_overwrite_existing" ) . execute ();
Which produces the following documents:
{
name
:
"San Francisco"
,
population
:
0
,
location
:
{
country
:
"USA"
,
state
:
"California"
}},
{
name
:
"Toronto"
,
population
:
0
,
province
:
"ON"
,
location
:
{
country
:
"Canada"
,
province
:
"Ontario"
}},
{
name
:
"New York"
,
population
:
0
,
location
:
{
country
:
"USA"
,
state
:
"New York"
}},
{
name
:
"Atlantis"
,
population
:
0
}
Using the merge_keep_existing mode to add a default value
Setting a default value for location when it doesn't appear in a document:
Node.js
const defaultedResults = await db . pipeline () . collection ( "/cities" ) . replace_with ( map ( "location" , "unknown" ), "merge_keep_existing" ) . execute ();
Which produces the following documents:
{
name
:
"San Francisco"
,
population
:
800000
,
location
:
{
country
:
"USA"
,
state
:
"California"
}
},
{
name
:
"Toronto"
,
province
:
"ON"
,
population
:
3000000
,
location
:
{
country
:
"Canada"
,
province
:
"Ontario"
}
},
{
name
:
"New York"
,
location
:
{
country
:
"USA"
,
state
:
"New York"
}
},
{
name
:
"Atlantis"
,
population
:
null
,
location
:
"unknown"
}
