ArangoDB (AQL)

The graph databases guide covers the stores that
implement the ORM-structured graph contract — thirteen compile* methods that
take findAll-shaped specs and return a { text, params } statement. This
page covers the ArangoDB implementation, AqlGraphDialect, and the structured
path it gives ArangoStore.

Before it existed, ArangoStore could create collections and read documents by
key, but anything resembling a query meant writing AQL by hand. It no longer
does: you pass the same spec objects the other graph dialects take, and the
dialect compiles the AQL.

The mapping

ArangoDB is multi-model. Documents live in collections; a collection whose
documents carry _from and _to is an edge collection that can be
traversed. That makes the mapping unusually direct:

ORM concept	ArangoDB
node label	document collection of the same name
edge label	edge collection of the same name
node	a document (`_key`, `_id`, `_rev` are ArangoDB's own)
edge	a document whose `_from` / `_to` hold document `_id`s
association / `include`	a one-hop traversal over the edge collection

A label maps to a collection of the same name unless you say otherwise:

new AqlGraphDialect({
  collections: { User: 'users' },        // node label  -> document collection
  edgeCollections: { HAS_POSTS: 'authored' }, // edge label -> edge collection
});

Side by side: the call and the AQL it runs

Every call below is on ArangoStore; the AQL tab is exactly what getGraphDialect() compiles for it, bind parameters included.

import { Op } from 'ts-prorm-orm';
import { ArangoStore } from 'ts-prorm-orm/nosql/arangodb';

const store = new ArangoStore({ url: 'http://localhost:8529', databaseName: '_system' });
await store.connect();

// 1. filtered, sorted, paged read
const page3 = await store.matchNodes({
  label: 'users',
  where: { age: { [Op.gte]: 18 }, active: true },
  order: [['age', 'DESC']],
  limit: 10,
  offset: 20,
});

// 2. one-hop include: each user with their posts
const withPosts = await store.matchNodes({
  label: 'users',
  where: { name: 'Ada' },
  include: [{ edgeLabel: 'authored', direction: 'out', targetLabel: 'posts', as: 'posts' }],
});

// 3. multi-hop traversal
const reachable = await store.traverseNodes({
  label: 'users', where: { name: 'Ada' },
  edgeLabel: 'authored', direction: 'out', maxDepth: 2, targetLabel: 'posts',
});

// 4. create-or-update an edge between two matched documents
await store.relateNodes({
  fromLabel: 'users', fromWhere: { _key: 'ada' },
  edgeLabel: 'authored',
  toLabel: 'posts', toWhere: { _key: 'p1' },
  props: { at: '2026-07-05' },
});

// 5. atomic counter
await store.incrementNodes('posts', { views: 1 }, { _key: 'p1' });

// 1. params: { '@c0': 'users', v0: 'age', v1: 18, v2: 'active', v3: true, v4: 'age' }
FOR doc IN @@c0
FILTER (doc[@v0] >= @v1 AND doc[@v2] == @v3)
SORT doc[@v4] DESC
LIMIT 20, 10
RETURN doc

// 2. params: { '@c0': 'users', '@c1': 'authored', v0: 'name', v1: 'Ada', v2: 'posts', v3: 'posts' }
FOR doc IN @@c0
FILTER doc[@v0] == @v1
RETURN MERGE(doc, { [@v2]: (FOR n0 IN 1..1 OUTBOUND doc @@c1 FILTER PARSE_IDENTIFIER(n0._id).collection == @v3 RETURN n0) })

// 3. params: { '@c0': 'users', '@c1': 'authored', v0: 'name', v1: 'Ada', v2: 'posts' }
WITH posts
FOR doc IN @@c0
FILTER doc[@v0] == @v1
FOR node IN 1..2 OUTBOUND doc @@c1
FILTER PARSE_IDENTIFIER(node._id).collection == @v2
RETURN DISTINCT node

// 4. params: { '@c0': 'users', '@c1': 'posts', '@c2': 'authored', v0: '_key', v1: 'ada', v2: '_key', v3: 'p1', v4: { at: '2026-07-05' } }
FOR src IN @@c0
FILTER src[@v0] == @v1
FOR dst IN @@c1
FILTER dst[@v2] == @v3
UPSERT { _from: src._id, _to: dst._id } INSERT MERGE(@v4, { _from: src._id, _to: dst._id }) UPDATE @v4 IN @@c2
RETURN NEW

// 5. params: { '@c0': 'posts', v0: '_key', v1: 'p1', v2: 'views', v3: 1 }
FOR doc IN @@c0
FILTER doc[@v0] == @v1
UPDATE doc WITH { [@v2]: (doc[@v2] == null ? 0 : doc[@v2]) + @v3 } IN @@c0
RETURN NEW

With store.configureGraph({ graph: 'social' }), the traversal (3) names the graph instead of an edge collection, and the WITH prelude goes away:

// params: { '@c0': 'users', v0: 'name', v1: 'Ada', v2: 'social', v3: 'posts' }
FOR doc IN @@c0
FILTER doc[@v0] == @v1
FOR node IN 1..2 OUTBOUND doc GRAPH @v2
FILTER PARSE_IDENTIFIER(node._id).collection == @v3
RETURN DISTINCT node

Two query forms, not one

AQL has a collection form and a traversal form, and they are not
interchangeable. compileMatch uses the first:

FOR doc IN @@c0
FILTER (doc[@v0] == @v1 AND doc[@v2] >= @v3)
SORT doc[@v4] DESC
LIMIT 20, 10
RETURN doc

compileTraverse uses the second:

WITH posts
FOR doc IN @@c0
FILTER doc[@v0] == @v1
FOR node IN 1..3 OUTBOUND doc @@c1
FILTER PARSE_IDENTIFIER(node._id).collection == @v2
RETURN DISTINCT node

Note the start vertex. AQL traversals start from a document _id, but you
never build one: an enclosing FOR selects the start documents with the full
ORM where surface and hands the document itself to the traversal.

An include nests the second form inside the first, as a subquery:

FOR doc IN @@c0
RETURN MERGE(doc, { [@v0]: (FOR n0 IN 1..1 OUTBOUND doc @@c1 RETURN n0) })

Named graph or edge collections

Both are supported. Configure a named graph and traversals compile to
… GRAPH @v0, with ArangoDB resolving the edge collections from the graph
definition:

import { ArangoStore } from 'ts-prorm-orm/nosql/arangodb';

const store = new ArangoStore({ url: 'http://localhost:8529', databaseName: '_system' });
store.configureGraph({ graph: 'social' });

Leave it unset and each traversal names its own edge collection
(… OUTBOUND doc @@c1), which needs no graph to exist. The named graph is the
default target when one is configured, because it is the only form that knows
the reachable vertex collections without being told — the anonymous form needs
a WITH prelude in a cluster, which is why one appears above.

Bind parameters: `@value` versus `@@collection`

This is the injection boundary, so it is worth being exact.

AQL has two kinds of bind parameter. A value parameter is @name and may
hold anything JSON. A collection parameter is @@name, must be a plain
string, and is only accepted where the grammar expects a collection: after
FOR … IN, INSERT … INTO, UPDATE/REPLACE/REMOVE/UPSERT … IN, and in
a traversal's edge-collection list. The two are written asymmetrically — the
key in the bind map carries one @, the reference in the query carries
two:

Bound, never written into the query text:

every filter value, and every filter field name — AQL can bind a property
name through doc[@v0], so not even a key is parsed as query text;

sort keys, projection lists (KEEP/UNSET take a bound array), include
aliases (a bound dynamic object key, { [@v0]: … }), patch and upsert
documents;

collection names, as @@ parameters;

the named graph's name — it is a string value, not a collection, so it binds
with a single @.

Written into the text, and therefore validated first:

the traversal direction keyword. ArangoDB documents that this cannot be a
bind parameter, so it comes from a fixed three-entry enum
(out/in/both → OUTBOUND/INBOUND/ANY); anything else falls back
to OUTBOUND rather than reaching the query;

the depth range min..max and LIMIT offset, count, coerced to
non-negative integers — Number('10 REMOVE doc IN users') is NaN, and a
ValidationError is raised rather than a query built;

collection names in the WITH prelude of an anonymous-graph traversal. They
have to be known when the query is parsed, so this is the one place a
collection name is text rather than a parameter.

Because of that last case, collection names are validated, not sanitized:
they must match ArangoDB's traditional naming rule ([A-Za-z][A-Za-z0-9_-]*,
max 256 characters) or a ValidationError names the label and the call. The
shared safeIdent() helper is deliberately not used on them — it rewrites
offending characters to _, so my-graph would silently become my_graph, a
different and probably empty collection. Mangling is fine for an identifier the
compiler is minting; it is wrong for a name that has to resolve to something
that already exists.

Labels are checked before any of this by requireGraphLabel(), so a missing
one raises a ValidationError instead of putting undefined in the query.

Writes

Call	AQL
`createNode`	`INSERT @v0 INTO @@c0 RETURN NEW`
`updateNodes`	`FOR doc IN @@c0 FILTER … UPDATE doc WITH @v2 IN @@c0 RETURN NEW`
`upsertNode`	`UPSERT @v0 INSERT @v1 UPDATE @v1 IN @@c0 RETURN NEW`
`incrementNodes`	`UPDATE doc WITH { [@v2]: (doc[@v2] == null ? 0 : doc[@v2]) + @v3 }`
`deleteNodes`	`FOR doc IN @@c0 FILTER … REMOVE doc IN @@c0 RETURN OLD`
`relateNodes`	`UPSERT { _from: src._id, _to: dst._id } INSERT MERGE(@v4, …) UPDATE @v4 IN @@c2`

Three of those are worth a note.

Upsert uses AQL's dedicated UPSERT … INSERT … UPDATE … IN statement: one
atomic server-side operation, not a read followed by a racy write.

Removing an attribute (passing undefined as a value) compiles to null
plus OPTIONS { keepNull: false }, which is the only way AQL's UPDATE can
delete one. The option only appears when a removal was actually requested —
switching it on unconditionally would silently delete an explicitly stored
null instead of writing it.

Relating two documents reads _from/_to off the documents the filters
matched, so a collection/key identifier is never assembled from caller input.
The UPSERT on the endpoint pair gives Cypher MERGE's semantics: re-relating
the same pair updates the edge rather than adding a parallel one.

Deleting a vertex does not delete its edges

ArangoDB leaves edges pointing at a removed vertex dangling, and AQL cannot
fix that in one statement: a query may contain one data-modification
operation, and none inside a subquery. So the vertex removal and the edge
sweep are genuinely two queries, and detach is handled by the store rather
than pretended at by the compiler:

const store = new ArangoStore({ url: 'http://localhost:8529', databaseName: '_system' });
await store.deleteNodes('users', { _key: 'k1' }, {
  detach: true,
  edgeCollections: ['authored'],   // or configureGraph({ graph }) and let it look them up
});

Asking to detach with neither an edge-collection list nor a configured named
graph is an error — a plain delete that quietly leaves the edges behind is not
a reasonable fallback.

Indexes are not AQL

AQL has no DDL. Creating an index is a driver call, not a query, so the four
DDL compile* methods emit an #ARANGO-DDL#-prefixed JSON directive that
query() (on the dialect) or runGraphStatement() (on the store) executes
through the driver. Emitting a harmless no-op query instead would let
createTable() quietly skip the unique index it asked for.

Unique and primary-key constraints become sparse unique persistent
indexes: non-sparse, every document missing the attribute would index as null
and collide with the others.

`Op.contains`

Op.contains in a where renders the AQL membership test that matches its
value (fragments of the compiled FILTER, from the builder):

Value	AQL
an element: `{ tags: { [Op.contains]: 'admin' } }`	`@v1 IN doc[@v0]`
an array: `{ tags: { [Op.contains]: ['a', 'b'] } }`	`@v1 ALL IN doc[@v0]`
a document: `{ prefs: { [Op.contains]: { theme: 'dark' } } }`	`MATCHES(doc[@v0], @v1)`

The other graph dialects do not render it and refuse it. An operator the graph
where does not know (a symbol or a $ key) is refused with a
ValidationError, and so is an object that mixes operators with plain keys;
a plain object with no operators is still equality. Before 4.9.2 an unknown
operator was dropped: alone, { [Op.contains]: 'x' } became an equality
against {} and matched nothing, and beside another operator it vanished from
the filter.

What throws

GraphCapabilityError, for the things AQL genuinely cannot express:

Existence constraints. An ArangoDB index cannot require an attribute to
be present — a sparse index skips the documents that lack it, a non-sparse
one indexes them as null, so neither rejects a write. The nearest feature is
collection-level JSON Schema validation, which is a property of the
collection rather than an index. compileCreateConstraint(…, 'exists')
refuses rather than creating an index that enforces nothing.

Interactive transactions with no declared collections. ArangoDB's
streaming transactions take their locks when the transaction starts, so
the collections have to be declared then; TransactionOptions carries no
collection list and guessing "all of them" would lock the database. Pass
them explicitly:

await dialect.startTransaction({ collections: { write: ['users'] } } as any);

compileShowLabels() lists collections via COLLECTIONS(), which reports no
type — so it cannot tell a document collection from an edge collection, and
edge labels appear in the list too. store.listCollections() carries the type
when the distinction matters.

Using it from the store

End to end: create the collections, write, query, clean up.

import { Op } from 'ts-prorm-orm';
import { ArangoStore } from 'ts-prorm-orm/nosql/arangodb';

interface User {
  _key: string;
  name: string;
  age: number;
}

const store = new ArangoStore({ url: 'http://localhost:8529', databaseName: '_system', auth: { username: 'root', password: 'openSesame' } });
await store.connect();

try {
  await store.createCollection('users');
  await store.createCollection('posts');
  await store.createEdgeCollection('authored');

  await store.createNode('users', { _key: 'ada', name: 'Ada', age: 36 });
  await store.createNode('posts', { _key: 'p1', title: 'Notes on the Analytical Engine' });
  await store.relateNodes({
    fromLabel: 'users', fromWhere: { _key: 'ada' },
    edgeLabel: 'authored',
    toLabel: 'posts', toWhere: { _key: 'p1' },
    props: { at: new Date().toISOString() },
  });

  const adults = await store.matchNodes<User>({
    label: 'users',
    where: { age: { [Op.gte]: 18 } },
    order: [['age', 'DESC']],
    limit: 10,
  });
  const posts = await store.traverseNodes({
    label: 'users', where: { name: 'Ada' },
    edgeLabel: 'authored', direction: 'out', maxDepth: 2,
    targetLabel: 'posts',
  });

  await store.updateNodes('users', { _key: 'ada' }, { age: 37 });
  console.log(adults.map((u) => u.name), posts.length, await store.countNodes('users'));

  // Removing a vertex leaves its edges dangling unless you detach
  await store.deleteNodes('users', { _key: 'ada' }, { detach: true, edgeCollections: ['authored'] });
} finally {
  for (const c of ['authored', 'posts', 'users']) await store.dropCollection(c);
  await store.disconnect();
}

getGraphDialect() returns the compiler if you want the statement without
running it — for logging, or to pass to query() with extra options:

const store = new ArangoStore({ url: 'http://localhost:8529', databaseName: '_system' });
const stmt = store.getGraphDialect().compileMatch({ label: 'users', where: { name: 'Ada' } });
// { text: 'FOR doc IN @@c0\nFILTER doc[@v0] == @v1\nRETURN doc',
//   params: { '@c0': 'users', v0: 'name', v1: 'Ada' } }

Dropping to raw AQL

The escape hatch is unchanged, and it is still the right tool for what the
contract does not cover — COLLECT-based aggregation, SHORTEST_PATH, a
traversal that needs the edge or path variables, or a filter that has to hit a
persistent index (a bound attribute name, doc[@v0], cannot use one):

const store = new ArangoStore({ url: 'http://localhost:8529', databaseName: '_system' });
const rows = await store.queryAll(
  `FOR v, e, p IN OUTBOUND SHORTEST_PATH @from TO @to GRAPH 'social' RETURN p`,
  { from: 'users/ada', to: 'users/grace' },
);

Graph databases — the shared contract and the other dialects

OrientDB, Neptune and TigerGraph

Store adapters

Query operators

The mapping#

Side by side: the call and the AQL it runs#

Two query forms, not one#

Named graph or edge collections#

Bind parameters: @value versus @@collection#

Writes#

Deleting a vertex does not delete its edges#

Indexes are not AQL#

Op.contains#

What throws#

Using it from the store#

Dropping to raw AQL#

Related reading#