Start using AQL

Learn how to run your first queries written in ArangoDB’s Query Language and how to go from there, using a Game of Thrones dataset

This is an introduction to ArangoDB’s query language AQL, built around a small dataset of characters from the novel and fantasy drama television series Game of Thrones (as of season 1). It includes character traits in two languages, some family relations, and last but not least a small set of filming locations, which makes for an interesting mix of data to work with.

There is no need to import the data before you start. It is provided as part of the AQL queries in this tutorial. You can interact with ArangoDB using its built-in web interface to manage collections and execute the queries with ease, but you may also use a different interface.

How to run AQL queries

ArangoDB’s web interface has a Queries section for executing AQL queries.

  1. If necessary, switch to the database that you want to run queries in.
  2. Click Queries in the main navigation.
  3. Enter an AQL query in the code editor, e.g. RETURN CONCAT("Hello, ", @name).
  4. Specify any needed bind parameters in the panel on the right-hand side on the Bind Variables tab, e.g. set name to a value of AQL.
  5. Optionally set query options on the Options tab.
  6. Click the Execute button or hit Ctrl/Cmd + Return.

You can run AQL queries from the ArangoDB Shell (arangosh) with the db._query() and db._createStatement() methods of the db object.

db._query(`RETURN CONCAT("Hello, ", @name)`, { name: "AQL" }).toArray();
// -- or --
var name = "AQL";
db._query(aql`RETURN CONCAT("Hello, ", ${name})`).toArray();
Show output

See db._query() in the JavaScript API for details.

If you use Foxx, see how to write database queries for examples including tagged template strings.

You can use a tool like cURL  to run AQL queries from a command-line, directly using the HTTP REST API of ArangoDB.

The response bodies are generally compact JSON (without any line breaks and indentation). You can format them with the jq  tool for better readability if you have it installed:

curl -d '{"query":"RETURN CONCAT(\"Hello, \", @name)","bindVars":{"name":"AQL"}}' http://localhost:8529/_api/cursor | jq

See the POST /_db/{database-name}/_api/cursor endpoint in the HTTP API for details.

import { Database, aql } from "arangojs";
const db = new Database();

const name = "AQL";
const cursor = await db.query(aql`RETURN CONCAT("Hello, ", ${name})`);
const result = cursor.all();
console.log(result);

See Database.query()  in the arangojs documentation for details.

ctx := context.Background()
query := `RETURN CONCAT("Hello, ", @name)`
options := arangodb.QueryOptions{
    BindVars: map[string]interface{}{
        "name": "AQL",
    },
}
cursor, err := db.Query(ctx, query, &options)
if err != nil {
    log.Fatalf("Failed to run query:\n%v\n", err)
} else {
    defer cursor.Close()
    var str string
    for cursor.HasMore() {
        meta, err := cursor.ReadDocument(ctx, &str)
        _ = meta // No document metadata with this query, it only returns a string
        if err != nil {
            log.Fatalf("Failed to read cursor:\n%v\n", err)
        } else {
            fmt.Println(str)
        }
    }
}

See DatabaseQuery.Query()  in the go-driver v2 documentation for details.

String query = "RETURN CONCAT(\"Hello, \", @name)";
Map<String, Object> bindVars = Map.of("name", "AQL");
ArangoCursor<Object> cursor = db.query(query, Object.class, bindVars);
cursor.forEach(result -> System.out.println(result));

See ArangoDatabase.query()  in the arangodb-java-driver documentation for details.

query = "RETURN CONCAT('Hello, ', @name)"
bind_vars = { "name": "AQL" }
cursor = db.aql.execute(query, bind_vars=bind_vars)
for result in cursor:
  print(result)

See AQL.execute()  in the python-arango documentation for details.

Learn the query language

The following pages guide you through important query constructs for storing and retrieving data, covering basic as well as some advanced features.

Afterwards, you can read the AQL documentation for the full language reference and query examples.

On this page