FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

Fauna accounts created after August 21, 2024 must use FQL v10. These accounts will not be able to run FQL v4 queries or access the v4 Dashboard.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

Replace

This reference topic applies to FQL v4. Go to this page for the latest FQL v10 reference topics.

 
Replace( ref, param_object )
replace( ref, param_object )
Replace( ref, param_object )
Replace( ref, param_object )
Replace( ref, param_object )
Replace( ref, param_object )

Description

The replace operation substitutes the user data pointed to by the reference with the data contained in the param_object. Values not specified in the param_object are removed.

For performance, the documents describing AccessProviders, Databases, Collections, Functions, Indexes, Keys, Roles, and Tokens use an object cache. When you use Replace to modify any of these Fauna schema documents, the modification is not guaranteed to be visible immediately.

This does not apply to non-schema documents, such as those in a user-created collection. Non-schema documents are always modified or removed in a strongly consistent manner.

Parameters

Parameter Type Definition and Requirements

ref

Reference

A Reference to the document that should be modified.

param_object

Object

An Object that containing the document’s user data to be modified. See the following section for details.

param_object

Field Name Field Type Definition and Requirements

data

Object

The document’s user data to be modified.

Returns

An Object containing the metadata about the replace operations:

Field Name Field Type Definition and Requirements

ref

Reference

The Reference that identifies the document that was updated.

data

Object

A copy of the new document data.

ts

Long

The timestamp, with microsecond resolution, of the document update.

Examples

The following query updates the document by changing the name field to the value "Mountains’s Thunder", and removing the "cost" field from the document:

client.query(
  q.Replace(
    q.Ref(q.Collection('spells'), '181388642581742080'),
    {
      data: {
        name: 'Mountain\'s Thunder',
        element: ['air', 'earth'],
      },
    },
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: Ref(Collection("spells"), "181388642581742080"),
  ts: 1592112569500000,
  data: { name: "Mountain's Thunder", element: [ 'air', 'earth' ] }
}
result = client.query(
  q.replace(
    q.ref(q.collection("spells"), "181388642581742080"),
    {
      "data": {
        "name": "Mountain's Thunder",
        "element": ["air", "earth"]
      }
    }
  )
)
print(result)
{'ref': Ref(id=181388642581742080, collection=Ref(id=spells, collection=Ref(id=collections))), 'ts': 1592874029090000, 'data': {'name': "Mountain's Thunder", 'element': ['air', 'earth']}}
result, err := client.Query(
	f.Replace(
		f.Ref(f.Collection("spells"), "181388642581742080"),
		f.Obj{
			"data": f.Obj{
				"name": "Mountain's Thunder",
				"element": f.Arr{"air", "earth"}}}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:map[element:[air earth] name:Mountain's Thunder] ref:{181388642581742080 0xc000174180 0xc000174180 <nil>} ts:1603747275630000]
try
{
    Value result = await client.Query(
        Replace(
            Ref(Collection("spells"), "181388642581742080"),
            Obj(
                "data", Obj(
                    "name", "Mountain's Thunder",
                    "element", Arr("air", "earth")
                )
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(ref: RefV(id = "181388642581742080", collection = RefV(id = "spells", collection = RefV(id = "collections"))),ts: LongV(1603756703860000),data: ObjectV(name: StringV(Mountain's Thunder),element: Arr(StringV(air), StringV(earth))))
System.out.println(
    client.query(
        Replace(
            Ref(Collection("spells"), Value("181388642581742080")),
            Obj(
                "data", Obj(
                    "name", Value("Mountain's Thunder"),
                    "element", Arr(Value("air"), Value("earth"))
                )
            )
        )
    ).get());
{ref: ref(id = "181388642581742080", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1593467209080000, data: {name: "Mountain's Thunder", element: ["air", "earth"]}}
Replace(
  Ref(Collection('spells'), '181388642581742080'),
  {
    data: {
      name: 'Mountain\'s Thunder',
      element: ['air', 'earth'],
    },
  },
)
{
  ref: Ref(Collection("spells"), "181388642581742080"),
  ts: 1624310504150000,
  data: { name: "Mountain's Thunder", element: [ 'air', 'earth' ] }
}
Query metrics:

  •    bytesIn:  165

  •   bytesOut:  223

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:   99

  • writeBytes:  560

  •  queryTime: 20ms

  •    retries:    0

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!