arangodb

ArangoDB

ArangoDB is a native multi-model database. It allows you to store data as Key/Values, JSON Documents, and Graphs, and query them all with a single language (AQL).

When to Use

• Multi-Model Data Architectures: Unifying document (JSON), graph, and key-value models into a single query engine with ACID transactions.
• Complex Graph Traversals: Executing high-performance depth-first and breadth-first traversals with edge attributes in AQL.
• Unified Knowledge Graphs: Storing entity metadata as rich documents while querying interconnected relationships as graphs.
• Search & Full-Text Integration: Leveraging ArangoSearch for integrated full-text indexing, BM25 scoring, and geo-spatial queries.

Quick Start

// AQL (ArangoDB Query Language) - SQL-like
FOR u IN users
  FILTER u.active == true
  FOR order IN OUTBOUND u orders
    RETURN { user: u.name, order: order.product }

Core Concepts

Multi-Model Document & Edge Collections

Documents store unstructured JSON entities; Edge collections define directed connections between documents using _from and _to attributes:

// Vertex Document (users/alice)
{ "_key": "alice", "name": "Alice Mercer", "role": "Lead Architect" }

// Edge Document (knows/edge_1)
{ "_from": "users/alice", "_to": "users/bob", "relationship": "mentor", "since": 2024 }

ArangoDB Query Language (AQL) Graph Traversal

Traverses interconnected relationship graphs up to N hops:

// 1 to 3 hops outward traversal from Alice
FOR v, e, p IN 1..3 OUTBOUND 'users/alice' GRAPH 'socialGraph'
  FILTER e.relationship == 'mentor'
  RETURN {
    colleague: v.name,
    distance: LENGTH(p.edges),
    path: p.vertices[*].name
  }

Distributed Cluster Sharding (OneShard & SmartGraphs)

Ensures interconnected graph vertices and edges are colocated on identical physical DB servers to eliminate network hop penalties:

// Creates a SmartGraph partitioned by customer tenant ID
const graph = db._createSmartGraph(
  "tenantSocialGraph",
  [{ collection: "members", from: ["users"], to: ["users"] }],
  { smartGraphAttribute: "tenantId" },
);

Common Patterns

Graph Traversal with AQL

Problem: Querying deeply nested social or hierarchy connections in relational stores requires slow multi-table recursive joins.

Solution: Traverse nodes and edges declaratively with AQL:

FOR v, e, p IN 1..3 OUTBOUND 'users/alice' GRAPH 'social_graph'
  FILTER v.status == 'active'
  RETURN {
    friend: v.name,
    distance: LENGTH(p.edges),
    path: p.vertices[*].name
  }

Best Practices

Do:

• Leverage SmartGraphs for Multi-Tenant Clusters: Colocate graph subtrees on single cluster nodes using smartGraphAttribute to eliminate network hop latencies.
• Use ArangoSearch Views: Replace separate external Elasticsearch clusters by indexing collections directly with ArangoSearch.
• Filter Early in Graph Traversals: Use PRUNE and inline FILTER conditions to stop traversals down dead-end relationship paths.
• Bind Parameters in AQL: Always pass variables as @param to prevent AQL injection and maximize query compilation cache reuse.

Don't:

• Perform unbounded graph traversals: Never run 1..99 traversals without a PRUNE condition or depth limits.
• Use Edge collections without indexes: ArangoDB automatically indexes _from and _to; avoid overriding them with inefficient manual indexes.
• Mix cross-tenant data without SmartGraph keys: Sharding graphs randomly across nodes causes severe distributed RPC overhead.

Troubleshooting

Error	Cause	Solution
[1200] conflict	Optimistic locking collision on document update.	Retry update using current document _rev or use overwriteMode: 'replace'.
[1501] collection not found	Attempted query against non-existent collection or typo.	Verify collection names and ensure creation migrations have executed.
Out of memory in graph traversal	Unbounded traversal depths on large dense graphs.	Specify explicit min..max depths and add prune/filter conditions early in traversal.

References

• ArangoDB Documentation