!CHAPTER Data modification queries

AQL supports the following data-modification operations:

- **INSERT**: insert new documents into a collection
- **UPDATE**: partially update existing documents in a collection
- **REPLACE**: completely replace existing documents in a collection
- **REMOVE**: remove existing documents from a collection
- **UPSERT**: conditionally insert or update documents in a collection


Data-modification operations are normally combined with *FOR* loops to
iterate over a given list of documents. They can optionally be combined with
*FILTER* statements and the like.

Let's start with an example that modifies existing documents in a collection
*users* that match some condition:

    FOR u IN users
      FILTER u.status == 'not active'
      UPDATE u WITH { status: 'inactive' } IN users

Note that there is no need to combine a data-modification query with other
AQL operations such as *FOR* and *FILTER*. For example, the following 
stripped-down *update* query will work, too. It will *update* one document
(with key *foo*) in collection *users*:

    UPDATE "foo" WITH { status: 'inactive' } IN users

Now, let's copy the contents of the collection *users* into the collection
*backup*:

    FOR u IN users
      INSERT u IN backup

As a final example, let's find some documents in collection *users* and
remove them from collection *backup*. The link between the documents in both
collections is established via the documents' keys:

    FOR u IN users
      FILTER u.status == 'deleted'
      REMOVE u IN backup


!SUBSECTION Returning documents

Data-modification queries can optionally return documents. In order to reference
the inserted, removed or modified documents in a `RETURN` statement, data-modification 
statements introduce the `OLD` and/or `NEW` pseudo-values:

    FOR i IN 1..100
      INSERT { value: i } IN test 
      RETURN NEW

    FOR u IN users
      FILTER u.status == 'deleted'
      REMOVE u IN users 
      RETURN OLD

    FOR u IN users
      FILTER u.status == 'not active'
      UPDATE u WITH { status: 'inactive' } IN users 
      RETURN NEW

`NEW` refers to the inserted or modified document revision, and `OLD` refers
to the document revision before update or removal. `INSERT` statements can 
only refer to the `NEW` pseudo-value, and `REMOVE` operations only to `OLD`. 
`UPDATE`, `REPLACE` and `UPSERT` can refer to either.

In all cases the full documents will be returned with all their attributes,
including the potentially auto-generated attributes such as `_id`, `_key`, or `_rev`
and the attributes not specified in the update expression of a partial update.


!SUBSECTION Restrictions

The name of the modified collection (*users* and *backup* in the above cases) 
must be known to the AQL executor at query-compile time and cannot change at 
runtime. Using a bind parameter to specify the [collection name](../Glossary/index.html#collection_name) is allowed.

Data-modification queries are restricted to modifying data in a single 
collection per query. That means a data-modification query cannot modify 
data in multiple collections with a single query. It is still possible (and
was shown above) to read from one or many collections and modify data in another
within the same query.

Only a single data-modification operation can be used per AQL query. Data-modification
queries cannot be used inside subqueries. Data-modification operations can optionally
be followed by `LET` operations and a single `RETURN` operation to return data. If
expressions are used within these operations, they cannot contain subqueries or 
access data in collections using AQL functions.


!SUBSECTION Transactional Execution
  
On a single server, data-modification operations are executed transactionally.
If a data-modification operation fails, any changes made by it will be rolled 
back automatically as if they never happened.

In a cluster, AQL data-modification queries are currently not executed transactionally.
Additionally, *update*, *replace*, *upsert* and *remove* AQL queries currently 
require the *_key* attribute to be specified for all documents that should be 
modified or removed, even if a shared key attribute other than *_key* was chosen 
for the collection. This restriction may be overcome in a future release of ArangoDB.