AQL Data Queries

AQL stands for ArangoDB Query Language.

The two main categories of AQL queries:

1) Those that retrieve (Access) data from documents (i.e., read operations)
2) Those that modify data in documents (i.e., create, update, replace, or delete operations). 

Data Access (retrieve) Queries:

When using AQL to fetch data from a database, a RETURN statement is always required, which can be used to return a static value like a string. The query result will always be an array of elements, even if only a single element was returned. The DOCUMENT() function can be used to retrieve a single document based on its document identifier.

Example 1:

Return String

RETURN "Hello codemummy using ArangoDB!"

output:
The above AQL query returns a string value, "Hello codemummy using ArangoDB!", as the query result. Since no document or collection is specified, this is a static value that will be returned every time the query is executed.

Example 2:

Return Document from the collection:

RETURN DOCUMENT("codemummy/669435")

output:
The above AQL query returns the document with the specified document ID, "codemummy/669435", using the DOCUMENT() function. The entire document, including all of its attributes and values, will be returned as the query result.

In AQL, the RETURN statement is typically used together with a FOR loop to iterate over the documents in a collection. 

Example 3:

Return  all Documents from a collection

FOR doc IN codemummy
  RETURN doc

output:

The above AQL query iterates over all the documents in the "codemummy" collection and returns all documents in the collection.

With AQL, it is simple to create a projection 

Example 4:

Return the required parameters of all Documents from a collection.

FOR doc IN codemummy
  RETURN { name: doc.name, key: doc }

output:

The above AQL query iterates over the documents in the "codemummy" collection and returns a new object for each document. The object contains two attributes: "name", which is set to the value of the "name" attribute of the current document, and "key", which contains the entire current document as its value. The resulting objects are returned as the query result.

Operations: FILTER, SORT, and LIMIT :

By including operations like FILTER, SORT, and LIMIT inside the loop body, it is possible to refine and arrange the result set of the query. These operations can be used to restrict the data, sort it in a specific order, and limit the number of results returned by the query.

Example 5:

 FILTER: Gives out documents that meet certain criteria:

FOR doc IN codemummy
  FILTER doc.status == "open"
  RETURN doc

output:

The above AQL query iterates over the documents in the "codemummy" collection and filters out only those documents that have a value of "open" for the "status" attribute. The filtered documents are then returned as the query result.

Example 6:

 SORT: Gives out sorted documents.

FOR doc IN codemummy
  SORT doc.name
  return doc

output:
The above AQL query iterates over the documents in the "codemummy" collection, sorts them in ascending order based on the "name" attribute of each document, and returns the sorted documents as the query result.

Example 7:

LIMIT: used to restrict the number of documents returned by a query.

FOR doc IN codemummy
  LIMIT 10
  return doc

output:
The above AQL query iterates over the documents in the "codemummy" collection and returns the first 10 documents that it encounters. The LIMIT operation is set to count 10, which restricts the result set to only 10 documents. The resulting documents are returned as the query result.

In Limit, the OFFSET clause can be used in the query. The OFFSET clause allows you to skip a certain number of documents and retrieve the subsequent documents.

Example 8:

FOR doc IN codemummy
  LIMIT 20, 10
  RETURN doc

output:
In this query, the number 20 represents the offset or the number of documents to skip, and 10 represents the count of documents to return. It will retrieve 10 documents from the "codemummy" collection, starting from the 21st document (skipping the first 20 documents).

Example 9:

FILTER, SORT, and LIMIT used together:

FOR doc IN codemummy
  FILTER doc.status == "open"
  SORT doc.name
  LIMIT 10
  RETURN doc

output:
The above AQL query iterates over the documents in the "codemummy" collection, filters out only those documents that have a value of "open" for the "status" attribute, sorts the filtered documents in ascending order based on the "name" attribute of each document, limits the result set to the first 10 documents, and returns the resulting documents as the query result.

The order of operations in an AQL query can have a significant impact on the resulting output, and it is not necessary for them to occur in a fixed order

Data Modification Queries:

Data modification queries in AQL are used to create, update, replace, and delete documents in ArangoDB. These queries are executed using the following AQL operations:

INSERT: Inserts a new document into a collection.

UPDATE: Updates the attributes of one or more documents that match a specified condition.

REPLACE: Replaces the attributes of a document that matches a specified condition with new values.

REMOVE: Removes one or more documents that match a specified condition.

UPSERT:  stands for "update or insert.", allows to update a document if it exists or insert a new document if it does not exist in a single query.

These data modification queries can be used to modify the documents stored in a collection, allowing you to add, update, or remove data as needed.

Insert:

To insert a document, the INSERT operation is used, and a key for the new document can be specified, but it is not mandatory  (ArangoDB creates automatically).

Example 10:

insert without a "_key"

INSERT {
  firstName: "vrushabh",
  SecondName: "shet",
  profession: "developer"
} INTO codemummy

output:
This AQL query will insert a new document into the "codemummy" collection with the attributes "firstName", "SecondName", and "profession" set to "vrushabh", "shet", and "developer", respectively.




The "_key" attribute will be auto-generated by ArangoDB unless it is specified in the query. The query will not return any output unless a "RETURN" keyword is used. But the record will be inserted. It is important to note that the collection must already exist as AQL queries cannot create new collections.

Example 11:

insert with a "_key"

INSERT {
  _key:"code",
  role: "Software Developer",
  language: "java",
  experience: "3+"
} INTO codemummy

output:
The above AQL query inserts a new document into the "codemummy" collection with a custom key value "_key: code" and three attributes - "role", "language", and "experience". The values for these attributes are "Software Developer", "java", and "3+" respectively. 

In modification queries, the RETURN keyword is optional, but in data access queries, it is mandatory. ArangoDB does not have a fixed schema for documents, meaning that the attributes or fields of documents can have varying structures or formats. (like the above two examples have different attributes for the same collection)

Update:

The UPDATE operation in AQL is used to add or modify attributes of an existing document in a collection

Example 12:

UPDATE "code" WITH {
  status: "active",
  location: "Bangalore",
  language: "c++"
} IN codemummy

output:
This AQL query will update the document in the "codemummy" collection with the key "_key" set to "code" and set its "status" field to "active", "location" field to "Bangalore", and "language" field to "c++" and keep the already existing attributes the same.

Replace:

In ArangoDB's AQL, the REPLACE operation is used to replace all attributes of an existing document (except for the attributes that cannot be changed, such as _key). It requires specifying the key of the document to be replaced and the new attribute values

Example 13:

REPLACE {
  _key: "code",
  sport: "football",
  player: "Cristiano Ronaldo",
  nation: "Portugal"
}IN codemummy

output:
This AQL query will replace the document in the "codemummy" collection with the key "_key" set to "code" and set its "sport" field to "football", "player" field to "Cristiano Ronaldo", and "nation" field to "Portugal". 

 REPLACE operation overwrites the existing document with the new document, so any existing fields that are not included in the new document will be deleted.

Remove:

REMOVE is the command in AQL to delete a document or a set of documents from a collection in ArangoDB.

Example 14:

REMOVE "code" IN codemummy

output:

This will delete the document with the key "code" from the "codemummy" collection.