|
| 1 | +--- |
| 2 | +title: Start using AQL |
| 3 | +menuTitle: Start using AQL |
| 4 | +weight: 52 |
| 5 | +description: >- |
| 6 | + Learn how to run your first queries written in ArangoDB's Query Language |
| 7 | + and how to go from there, using a Game of Thrones dataset |
| 8 | +--- |
| 9 | +This is an introduction to ArangoDB's query language AQL, built around a small |
| 10 | +dataset of characters from the novel and fantasy drama television series |
| 11 | +Game of Thrones (as of season 1). It includes character traits in two languages, |
| 12 | +some family relations, and last but not least a small set of filming locations, |
| 13 | +which makes for an interesting mix of data to work with. |
| 14 | + |
| 15 | +There is no need to import the data before you start. It is provided as part |
| 16 | +of the AQL queries in this tutorial. You can interact with ArangoDB using its |
| 17 | +built-in web interface to manage collections and execute the queries with ease, |
| 18 | +but you may also use a different interface. |
| 19 | + |
| 20 | +## How to run AQL queries |
| 21 | + |
| 22 | +{{< tabs "interfaces" >}} |
| 23 | + |
| 24 | +{{< tab "Web interface" >}} |
| 25 | +ArangoDB's web interface has a **Queries** section for |
| 26 | +[executing AQL queries](../../aql/how-to-invoke-aql/with-the-web-interface.md). |
| 27 | + |
| 28 | +1. If necessary, [switch to the database](../../concepts/data-structure/databases.md#set-the-database-context) |
| 29 | + that you want to run queries in. |
| 30 | +2. Click **QUERIES** in the main navigation. |
| 31 | +3. Enter an AQL query in the code editor, e.g. `RETURN CONCAT("Hello, ", @name)`. |
| 32 | +4. Specify any needed bind parameters in the panel on the right-hand side, |
| 33 | + e.g. set `name` to a value of `AQL`. |
| 34 | +5. Click the **Execute** button or hit `Ctrl`/`Cmd` + `Return`. |
| 35 | +{{< /tab >}} |
| 36 | + |
| 37 | +{{< tab "arangosh" >}} |
| 38 | +You can run AQL queries from the ArangoDB Shell ([arangosh](../../components/tools/arangodb-shell/_index.md)) |
| 39 | +with the [`db._query()`](../../aql/how-to-invoke-aql/with-arangosh.md#with-db_query) and |
| 40 | +[`db._createStatement()`](../../aql/how-to-invoke-aql/with-arangosh.md#with-db_createstatement-arangostatement) |
| 41 | +methods of the [`db` object](../../develop/javascript-api/@arangodb/db-object.md). |
| 42 | + |
| 43 | +```js |
| 44 | +--- |
| 45 | +name: arangosh_execute_query_bindvars |
| 46 | +description: '' |
| 47 | +--- |
| 48 | +db._query(`RETURN CONCAT("Hello, ", @name)`, { name: "AQL" }).toArray(); |
| 49 | +// -- or -- |
| 50 | +var name = "AQL"; |
| 51 | +db._query(aql`RETURN CONCAT("Hello, ", ${name})`).toArray(); |
| 52 | +``` |
| 53 | +See [`db._query()`](../../develop/javascript-api/@arangodb/db-object.md#db_queryquerystring--bindvars--mainoptions--suboptions) |
| 54 | +in the _JavaScript API_ for details. |
| 55 | + |
| 56 | +If you use Foxx, see [how to write database queries](../../develop/foxx-microservices/getting-started.md#writing-database-queries) |
| 57 | +for examples including tagged template strings. |
| 58 | +{{< /tab >}} |
| 59 | + |
| 60 | +{{< tab "cURL" >}} |
| 61 | +You can use a tool like [cURL](https://curl.se/) to run AQL queries from a |
| 62 | +command-line, directly using the HTTP REST API of ArangoDB. |
| 63 | + |
| 64 | +The response bodies are generally compact JSON (without any line breaks and |
| 65 | +indentation). You can format them with the [jq](https://jqlang.github.io/jq/) |
| 66 | +tool for better readability if you have it installed: |
| 67 | + |
| 68 | +```sh |
| 69 | +curl -d '{"query":"RETURN CONCAT(\"Hello, \", @name)","bindVars":{"name":"AQL"}}' http://localhost:8529/_api/cursor | jq |
| 70 | +``` |
| 71 | + |
| 72 | +See the [`POST /_db/{database-name}/_api/cursor`](../../develop/http-api/queries/aql-queries.md#create-a-cursor) |
| 73 | +endpoint in the _HTTP API_ for details. |
| 74 | +{{< /tab >}} |
| 75 | + |
| 76 | +{{< tab "JavaScript" >}} |
| 77 | +```js |
| 78 | +import { Database, aql } from "arangojs"; |
| 79 | +const db = new Database(); |
| 80 | + |
| 81 | +const name = "AQL"; |
| 82 | +const cursor = await db.query(aql`RETURN CONCAT("Hello, ", ${name})`); |
| 83 | +const result = cursor.all(); |
| 84 | +console.log(result); |
| 85 | +``` |
| 86 | + |
| 87 | +See [`Database.query()`](https://arangodb.github.io/arangojs/latest/classes/databases.Database.html#query) |
| 88 | +in the _arangojs_ documentation for details. |
| 89 | +{{< /tab >}} |
| 90 | + |
| 91 | +{{< tab "Go" >}} |
| 92 | +```go |
| 93 | +ctx := context.Background() |
| 94 | +query := `RETURN CONCAT("Hello, ", @name)` |
| 95 | +options := arangodb.QueryOptions{ |
| 96 | + BindVars: map[string]interface{}{ |
| 97 | + "name": "AQL", |
| 98 | + }, |
| 99 | +} |
| 100 | +cursor, err := db.Query(ctx, query, &options) |
| 101 | +if err != nil { |
| 102 | + log.Fatalf("Failed to run query:\n%v\n", err) |
| 103 | +} else { |
| 104 | + defer cursor.Close() |
| 105 | + var str string |
| 106 | + for cursor.HasMore() { |
| 107 | + _, err := cursor.ReadDocument(ctx, &str) |
| 108 | + if err != nil { |
| 109 | + log.Fatalf("Failed to read cursor:\n%v\n", err) |
| 110 | + } else { |
| 111 | + fmt.Println(str) |
| 112 | + } |
| 113 | + } |
| 114 | +} |
| 115 | +``` |
| 116 | + |
| 117 | +See [`DatabaseQuery.Query()`](https://pkg.go.dev/github.com/arangodb/go-driver/v2/arangodb#DatabaseQuery) |
| 118 | +in the _go-driver_ v2 documentation for details. |
| 119 | +{{< /tab >}} |
| 120 | + |
| 121 | +{{< tab "Java" >}} |
| 122 | +```java |
| 123 | +String query = "RETURN CONCAT(\"Hello, \", @name)"; |
| 124 | +Map<String, ? super Object> bindVars = Collections.singletonMap("name", "AQL"); |
| 125 | +ArangoCursor<String> cursor = db.query(query, String.class, bindVars); |
| 126 | +cursor.forEach(result -> System.out.println(result)); |
| 127 | +``` |
| 128 | + |
| 129 | +See [`ArangoDatabase.query()`](https://www.javadoc.io/doc/com.arangodb/arangodb-java-driver/latest/com/arangodb/ArangoDatabase.html#query%28java.lang.String,java.lang.Class,java.util.Map%29) |
| 130 | +in the _arangodb-java-driver_ documentation for details. |
| 131 | +{{< /tab >}} |
| 132 | + |
| 133 | +{{< tab "Python" >}} |
| 134 | +```py |
| 135 | +query = "RETURN CONCAT('Hello, ', @name)" |
| 136 | +bind_vars = { "name": "AQL" } |
| 137 | +cursor = db.aql.execute(query, bind_vars=bind_vars) |
| 138 | +for result in cursor: |
| 139 | + print(result) |
| 140 | +``` |
| 141 | + |
| 142 | +See [`AQL.execute()`](https://docs.python-arango.com/en/main/specs.html#arango.aql.AQL.execute) |
| 143 | +in the _python-arango_ documentation for details. |
| 144 | +{{< /tab >}} |
| 145 | + |
| 146 | +{{< /tabs >}} |
| 147 | + |
| 148 | +## Learn the query language |
| 149 | + |
| 150 | +The following pages guide you through important query constructs for storing |
| 151 | +and retrieving data, covering basic as well as some advanced features. |
| 152 | + |
| 153 | +Afterwards, you can read the [AQL documentation](../../aql/_index.md) for the |
| 154 | +full language reference and query examples. |
| 155 | + |
| 156 | +{{< comment >}}TODO: Advanced data manipulation: attributes, projections, calculations... Aggregation: Grouping techniques{{< /comment >}} |
0 commit comments