Update

Update( ref, param_object )
Update( ref, param_object )
Update( ref, param_object )
Update( ref, param_object )
q.update( ref param_object )
Update( ref, param_object )

Description

The Update operation only modifies the specified fields in the documents pointed to by ref. Updates are partial, and only modify values that are specified in the param_object. Changes to scalar values and arrays are entirely replaced by the new data. Modifications to objects are merged. Setting a value to null completely removes the value. Fields in the document not specified in the param_object are not modified.

For performance, the documents describing AccessProviders, Databases, Collections, Functions, Indexes, Keys, Roles, and Tokens use an object cache. When you use Update 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 identifying the document that should be modified.

param_object

Object

An Object containing the document data to update, as well as optional new credentials and delegates. 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.

credentials

Object

The document’s credentials to be modified.

delegates

Object

The document’s delegates to be modified.

ttl

Timestamp

Optional - A timestamp indicating the document’s time-to-live, which is when the document should be removed. When a document is removed, the document’s existence ceases (as if it never existed); temporal queries cannot recover the document.

Removal is handled by a background task, so once a document (including collections, databases, indexes, keys, roles, and tokens) "expires" due to the setting in the ttl field, it could be some time (hours or days) before the removal occurs. There is no guarantee that removal occurs.

As of version 3.0.0, the ttl field is honored on read — an expired but not yet removed document behaves as if removal is complete. But, until removal is completed by background task processing, you can continue to access the history of the document, provided you have its reference, using the Events function.

Returns

An object containing the metadata about the update 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. All other fields in the document remain unchanged.

try
{
    Value result = await client.Query(
        Update(
            Ref(Collection("spells"), "181388642581742080"),
            Obj("data", Obj("name", "Mountain's Thunder", "cost", Null()))
        )
    );
    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(1603756871700000),data: ObjectV(name: StringV(Mountain's Thunder),element: StringV(air)))
result, err := client.Query(
	f.Update(
		f.Ref(f.Collection("spells"), "181388642581742080"),
		f.Obj{
			"data": f.Obj{"name": "Mountain's Thunder", "cost": nil}}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:map[element:air name:Mountain's Thunder] ref:{181388642581742080 0xc000146180 0xc000146180 <nil>} ts:1603747313810000]
System.out.println(
    client.query(
        Update(
            Ref(Collection("spells"), Value("181388642581742080")),
            Obj(
                "data", Obj(
                    "name", Value("Mountain's Thunder"),
                    "cost", Null()
                )
            )
        )
    ).get());
{ref: ref(id = "181388642581742080", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1593467851740000, data: {name: "Mountain's Thunder", element: "air"}}
client.query(
  q.Update(
    q.Ref(q.Collection('spells'), '181388642581742080'),
    {
      data: {
        name: 'Mountain\'s Thunder',
        cost: null,
      },
    },
  )
)
.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: 1592112267090000,
  data: { name: "Mountain's Thunder", element: 'air' }
}
result = client.query(
  q.update(
    q.ref(q.collection("spells"), "181388642581742080"),
    {
      "data": {
        "name": "Mountain's Thunder",
        "cost": None
      }
    }
  )
)
print(result)
{'ref': Ref(id=181388642581742080, collection=Ref(id=spells, collection=Ref(id=collections))), 'ts': 1592870397530000, 'data': {'name': "Mountain's Thunder", 'element': 'air'}}
Update(
  Ref(Collection('spells'), '181388642581742080'),
  {
    data: {
      name: 'Mountain\'s Thunder',
      cost: null,
    },
  },
)
{
  ref: Ref(Collection("spells"), "181388642581742080"),
  ts: 1624310557810000,
  data: { name: "Mountain's Thunder", element: 'air' }
}
Query metrics:

  •    bytesIn:  150

  •   bytesOut:  213

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:   99

  • writeBytes:  117

  •  queryTime: 46ms

  •    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!