Update documents

ArangoDB's official AQL docs for UPDATE can be found here

tip

We are going to updating documents to cover the update of create.

To avoid polluting the travel dataset we created a scratch collection here
We created a few documents in the scratch collection using insert and AQL here
We will be using the ArangoDB Query Interface to run the queries, see instructions to get to the interface here

Setup

Lets create a document first which we can use to learn about all the supported UPDATE operations update,replace,repset,upsert:
```
insert {'_key':'test-update','field1': 'foo','field2': 'bar', 'field3':'baz'} into scratch return NEW
```
Now that the document is added we can demonstrate all the operations on the test document

Update using a key

You can update a document by directly specifying a key and the fields to update:

update {_key: 'test-update'} WITH {'field1': "foo-updated", 'field4': 'new-field'} IN scratch RETURN NEW

We updated the value of field1 and simultaneously updated the document with a new field field4. You should see the following result:

[
    {
        "_key": "test-update",
        "_id": "scratch/test-update",
        "_rev": "_gdrxqkm--_",
        "field1": "foo-updated",
        "field2": "bar",
        "field3": "baz",
        "field4": "new-field"
    }
]

The following AQL is a short form version of the update with different fields, but yields identical results

update {_key: 'test-update' 'field2': "bar-updated", 'field5': 'new-field'} IN scratch RETURN NEW

You should see the following results:

[
    {
        "_key": "test-update",
        "_id": "scratch/test-update",
        "_rev": "_gdr1Bzq--A",
        "field1": "foo-updated",
        "field2": "bar-updated",
        "field3": "baz",
        "filed4": "new-field",
        "field5": "new-field"
    }
]

info

Update operations require a key
As expected UPDATE does not overwrite fields unless explicitly requested

Upsert using a key

Upserts are used to insert-or-update, so a document will be inserted if one doesnt exist otherwise it will be updated.

upsert {_key: 'test-upsert'}
insert {_key: 'test-upsert','field1': "foo", 'field2': 'bar','field3': 'baz'} 
update {'field1': 'foo-updated','field4': 'new-field'} IN scratch 
return [OLD, NEW]

You should see the following result, null as the old document and the full new document, indicating the document was inserted

[
    [
        null,
        {
        "_key": "test-upsert",
        "_id": "scratch/test-upsert",
        "_rev": "_gdslqDa---",
        "field1": "foo",
        "field2": "bar",
        "field3": "baz"
        }
    ]
]

caution

If you do not specify the _key as a part of the upsert or specified a different _key you will get unintended results (ArangoDB will generate a new key)

Running the same AQL query multiple times you should see the following results:

Run #2: Original document, plus field1 is updated and field2 is added

[
    [
        {
        "_key": "test-upsert",
        "_id": "scratch/test-upsert",
        "_rev": "_gdslqDa---",
        "field1": "foo",
        "field2": "bar",
        "field3": "baz"
        },
        {
        "_key": "test-upsert",
        "_id": "scratch/test-upsert",
        "_rev": "_gdslt_C---",
        "field1": "foo-updated",
        "field2": "bar",
        "field3": "baz",
        "field4": "new-field"
        }
    ]
]

Run 3 or more: Original document, plus field1 is updated and field2 is updated (No visible changes to the content)

[
    [
        {
        "_key": "test-upsert",
        "_id": "scratch/test-upsert",
        "_rev": "_gdslt_C---",
        "field1": "foo-updated",
        "field2": "bar",
        "field3": "baz",
        "field4": "new-field"
        },
        {
        "_key": "test-upsert",
        "_id": "scratch/test-upsert",
        "_rev": "_gdsl3Pe--_",
        "field1": "foo-updated",
        "field2": "bar",
        "field3": "baz",
        "field4": "new-field"
        }
    ]
]

Upsert without using a key

danger

Upsert operations can be run without specifying a _key in the upsertExpression, but the behavior is undefined if more than one document matches the upsert operation

Per the official documentation here:

In case at least one document in collection matches the searchExpression, it will be updated using the updateExpression. When more than one document in the collection matches the searchExpression, it is undefined which of the matching documents will be updated. It is therefore often sensible to make sure by other means (such as unique indexes, application logic etc.) that at most one document matches searchExpression.

Help us improve

Anything unclear or buggy in this tutorial? Provide Feedback

Update documents

Setup​

Update using a key​

Upsert using a key​

Upsert without using a key​

Setup

Update using a key

Upsert using a key

Upsert without using a key