ArangoDB AQL Tools

A Visual Studio Code extension for ArangoDB Query Language (AQL): formatting, syntax highlighting, an ArangoDB explorer, a query runner and autocomplete against your own ArangoDB instances.

Features

Formatting

Trigger with Shift+Alt+F (or your configured format shortcut) on any .aql file.

• Puts each clause keyword on its own line (FOR, FILTER, LET, SORT, LIMIT, COLLECT, RETURN, INSERT, UPDATE, REPLACE, REMOVE, UPSERT, SEARCH, WINDOW, etc.)
• Auto-indents FOR loop bodies, including nested loops
• Handles subqueries in parentheses with proper scope and indentation
• Lays out expressions to the print width: an array, object, argument list, AND / OR chain or ? : conditional stays on one line when it fits, and otherwise breaks all at once, one item per line, with the operator leading (OR breaks before AND). Continuation lines are indented one step, never aligned
• Keeps a call on its line when only its last argument (an object, array or subquery) needs to break: MERGE(doc, { … })
• Keeps an object broken when you put a line break right after its {; other line breaks inside an expression are redone to fit
• Breaks a long clause before its parts (WITH COUNT INTO, AGGREGATE, INTO, PRUNE, OPTIONS) and a long SORT or COLLECT list one item per line; a part you put on its own line stays there, and AGGREGATE lines up with its COLLECT
• Normalizes keywords to UPPERCASE
• Preserves comments and string literals
• Splits independent statement groups at a scope separator: a bare //, a banner comment on its own line (// ---- Section ----, // ==== Query 2 ====), or any column-0 line comment that follows a blank line
• Preserves a single blank line between clauses and statements (multiple blank lines collapse to one); blank lines at the start or end of a subquery and inside an expression are removed
• Preserves comment placement (inline comments stay inline, own-line comments stay on their own line with the indentation you gave them; comments are never re-indented)
• Cleans up extraneous whitespace

Before:

FOR doc IN collection FILTER doc.active == true SORT doc.name ASC LIMIT 10 RETURN { name: doc.name, email: doc.email }

After:

FOR doc IN collection
  FILTER doc.active == TRUE
  SORT doc.name ASC
  LIMIT 10
  RETURN { name: doc.name, email: doc.email }

Syntax Highlighting

• Clause keywords and operator keywords
• String literals (single, double, and backtick quoted)
• Numeric literals (integer, float, hex)
• Line and block comments
• Boolean and null constants
• Bind parameters (@param, @@collection)
• Function calls
• Operators

Language Support

• Bracket matching and auto-closing
• Comment toggling (Ctrl+/)

ArangoDB explorer and query runner

Click the + icon in the ArangoDB view (or run AQL: Add Connection) and answer the prompts for name, URL, database, user and password. Connections are stored in the aql.connections user setting (workspace settings cannot define connections, so a repository cannot redirect a stored password) and names must be unique; passwords go to VS Code's secret storage, never to settings files. You can also edit the setting by hand and set the password afterwards with AQL: Set Connection Password:

"aql.connections": [
  { "name": "local", "url": "http://127.0.0.1:8529", "database": "_system", "username": "root" }
]

• The ArangoDB view in the activity bar lists connections, databases and collections. Click a collection to open its first documents as JSON. Use the check icon on a database to make it the target for queries. Right-click a connection to create a database, or a database to create a document or edge collection. The pencil icon edits a connection (rename, URL, database, user; leave the password empty to keep it). The trash icon removes a connection (optionally dropping its database); right-click a database or collection to drop it. Drops require typing the name to confirm.
• AQL: Run Query (Ctrl+Enter / Cmd+Enter in an .aql file) runs the selection, or the whole file when nothing is selected, and opens the result as a JSON document beside the editor, one tab per connection and database that updates on each run. Cancel stops waiting for the result; the query itself keeps running on the server. Queries that REMOVE documents always ask for confirmation, naming the affected collections. UPDATE, REPLACE and UPSERT ask too unless aql.confirmUpdates is off. INSERT never asks. The editor context menu offers "Run Selected Query" when text is selected.
• Bind parameters come from a /* bind { ... } */ comment anywhere in the file. Parameters the comment does not cover are asked for in an input box.

/* bind { "@c": "users", "minAge": 18 } */
FOR u IN @@c
  FILTER u.age >= @minAge
  RETURN u

Autocomplete

Keywords, builtin functions, collection names of the active database and the variables declared in the file (LET, FOR, COLLECT, AGGREGATE) are suggested everywhere. After variable. the attribute names sampled from the variable's collection appear. After @ the bind parameters already used in the file appear; after @@ the collection names.

Configuration

Installation

From VSIX (local)

cd aql-formatter
npm install
npx @vscode/vsce package
code --install-extension aql-formatter-*.vsix

From Source (development)

1. Open the aql-formatter folder in VS Code
2. Run npm install
3. Press F5 to launch the Extension Development Host
4. Open any .aql file and format it with Shift+Alt+F

Supported AQL Constructs

Development

npm install          # install dependencies
npm run compile      # compile TypeScript
npm run watch        # compile + watch for changes
npm test             # run tests
npm run lint         # run ESLint

License

This project is licensed under the GNU General Public License v3.0. GPL-3.0 was chosen to keep derivative editor extensions open source.