mirror of https://gitee.com/bigwinds/arangodb
105 lines
4.2 KiB
Plaintext
105 lines
4.2 KiB
Plaintext
!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.
|