mirror of https://gitee.com/bigwinds/arangodb
97 lines
3.9 KiB
Plaintext
97 lines
3.9 KiB
Plaintext
!CHAPTER Data modification queries
|
|
|
|
As of ArangoDB version 2.2, 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
|
|
|
|
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
|
|
|
|
To return documents from a data-modification query, the `INSERT`, `REMOVE`,
|
|
`UPDATE` or `REPLACE` statement must be immediately followed by a `LET`
|
|
statement that assigns either the pseudo-value `NEW` or `OLD` to a user-defined
|
|
variable. The `LET` statement must be followed by a `RETURN` statement that
|
|
returns the variable introduced by `LET`:
|
|
|
|
FOR i IN 1..100
|
|
INSERT { value: i } IN test LET inserted = NEW RETURN inserted
|
|
|
|
FOR u IN users
|
|
FILTER u.status == 'deleted'
|
|
REMOVE u IN users LET removed = OLD RETURN removed
|
|
|
|
FOR u IN users
|
|
FILTER u.status == 'not active'
|
|
UPDATE u WITH { status: 'inactive' } IN users LET updated = NEW RETURN updated
|
|
|
|
`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` and `REPLACE` 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/README.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
|
|
with one query.
|
|
|
|
|
|
!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* 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.
|