ArangoDB | System Designer

What is ArangoDB?

ArangoDB is a native multi-model database that stores key-addressed records, JSON documents, and graph relationships in one database engine. Its query language, AQL, can filter document attributes, follow graph edges, aggregate results, and combine those operations in one query.

In plain language, one customer record can be retrieved by its key, queried as a document, and connected to accounts or devices as a graph node. The application does not need to copy that same fact into three separate databases just to use three access patterns.

The core invariant is the stored model must make the application's dominant query and correctness boundary explicit. A unified engine does not remove index design, edge lifecycle, transaction scope, shard placement, replication, or recovery work.

Native multi-model is a query choice, not three storage engines

ArangoDB's key-value model is a subset of its document model. Graph nodes and edges are also documents; edge documents add _from and _to references. The important design decision is which access path owns each request.

See one engine through three access paths

Each model makes a different application question direct.

Known identity

Key-value access

Every document has an immutable string _key inside its collection. The built-in primary index supports exact _key and _id lookups without a user-created index.

Attributes and aggregates

Document query

A document is a JSON object whose attributes can be filtered, sorted, projected, and aggregated with AQL. Secondary indexes should follow real query predicates.

Paths and neighborhoods

Graph traversal

Vertices live in document collections and directed edges live in edge collections. AQL can traverse inbound, outbound, or either direction over bounded depths.

Use the narrowest model that answers the question. A profile lookup does not need a graph traversal; a fraud neighborhood cannot be discovered from a known-key lookup alone.

Choose the model from the query shape

Select an application query, then try each access path. The lab changes the required index, execution steps, and maintenance cost. It is a decision model based on query semantics, not a latency or throughput benchmark.

Query-shape decision lab

Choose an access path before choosing a model

Loading the document, graph, and key-value decision model.

Loading query shapes

Write the expected query before creating collections. Include the known identifiers, attribute predicates, relationship direction and depth, sort order, projection, result limit, and the facts that must be transactionally correct.

Express each access path in AQL

AQL is declarative: describe the documents and paths you need, then inspect the query plan to verify which indexes, traversals, remote operations, and gathers it uses.

Filter by _key equality when the collection is known. The built-in primary index is the intended access path.

Fetch one document through the primary index

Use explicit predicates, sorting, projection, and limits. Create a persistent index only after the full query shape and write cost are understood.

Filter and project documents

Bound the direction and depth. Return only the vertex, edge, or path fields the caller needs, and use PRUNE when a condition can stop expansion early.

Traverse exactly two outbound hops

One AQL query can filter starting documents, traverse edge documents, inspect connected vertices, and return the path as evidence.

Combine document filters and graph evidence

Run EXPLAIN before production and PROFILE with representative data. Concise AQL syntax does not prove that a distributed query is selective or local.

Keep transaction claims inside the deployment boundary

ArangoDB supports ACID transactions, but the exact guarantee depends on deployment and query scope.

Broad local boundary

Single server

Multi-document and multi-collection transactions can be fully ACID when the work stays inside one server and avoids documented intermediate-commit limits.

Native atomic unit

Cluster, one document

A single-document operation in a cluster is fully ACID. A multi-document query can also be ACID when its collection has one shard.

Distributed limit

Cluster, many shards

Do not claim one atomic transaction across arbitrary shards or collections. Use OneShard for eligible multi-collection ACID work, or design an application workflow with idempotency and reconciliation.

Also separate transaction atomicity from disk and replica acknowledgement. Options such as waitForSync, replicationFactor, and writeConcern describe different durability boundaries and should be reviewed explicitly.

Design shard keys from placement and lookup behavior

In a cluster, every collection is divided into a configured number of shards. Coordinators route work to DB-Servers, and the default shard key is _key.

1
Routing
List equality lookups
Record which requests know _key, tenant, account, region, or another stable ownership attribute. A Coordinator can target one shard only when it has the shard-key values.
2
Balance
Measure key distribution
Check cardinality, frequency, and the largest value. Every document with the same shard key value maps together, so a dominant tenant or region can create a hot shard.
3
Locality
Trace cross-collection work
Identify joins, transactions, and graph traversals that cross collection boundaries. Independent sharding can turn one logical query into network fan-out.
4
Lifecycle
Lock the creation contract
Choose shard keys and shard count before loading data, then test rebalancing, failure, backup, and restore. Shard-key attributes cannot be changed in place.

A custom shard key changes point-lookup routing

If a collection is sharded by something other than _key, a lookup that supplies only the document key may need to contact every shard. Include the custom shard-key values when the operation supports a lookup hint, and verify the AQL plan.

Trace replication and failure at one shard

The topology below models one shard with replicationFactor: 3 and writeConcern: 2. Switch scenarios to see how follower loss, leader promotion, write concern, and independent backup change the result. Select any node to inspect its responsibility.

The model intentionally omits timing. Detection, promotion, resynchronization, and replacement duration depend on the deployed version, configuration, data size, and infrastructure. Measure those values in failure drills.

Make collection assumptions executable

This arangosh example creates an illustrative collection with six shards, a tenant shard key, three configured copies, and a two-copy write concern.

Create a sharded, replicated collection

These values are not defaults or universal recommendations. Before using them:

replay the real tenant distribution and measure the hottest shard;
confirm common lookups include tenantId when targeted routing matters;
verify the cluster has enough DB-Servers for the replication factor;
inject follower and leader failures while observing write acknowledgement;
calculate physical storage from logical bytes, replicas, indexes, compaction, and operational headroom.

Operate query, shard, and recovery contracts together

Monitor facts that identify which boundary is failing:

queries: execution plans, scanned documents, result rows, remote operations, Coordinator memory, traversal depth, branching, and cancellation;
indexes: selectivity, write maintenance, cache behavior, build status, and indexes that no observed query uses;
shards: document and byte distribution, request rate per shard, leader placement, under-replication, resynchronization, and rebalance progress;
writes: accepted, rejected, timed out, retried, and reconciled operations, plus the active writeConcern and waitForSync contract;
recovery: independent backup age, restore duration, recovered point in time, document validation, graph-edge integrity, and application-level verification.

Replication is not a backup. A valid delete or corrupt application write can be copied to every follower, so recovery needs an independent artifact and a tested restore path.

Know when ArangoDB is a strong fit

Several connected access patterns

Strong fit

Choose ArangoDB when the same owned facts need document filters, known-key access, and relationship traversal, and one team can operate their shared transaction, sharding, backup, and access-control boundary.

One simpler dominant contract

Weak fit

Prefer a simpler store when the workload is only key-value lookup, requires unrestricted cross-shard ACID transactions, centers on large analytical scans, or needs a graph copy that is clearly derived from another authoritative database.

Multi-model capability is valuable when it removes a real synchronization boundary. It is not a reason to put unrelated workloads into one cluster.

Verify decisions against official documentation

These primary Arango references define the semantics used in this lesson:

Pin the deployed ArangoDB version in runbooks. Defaults, limitations, and operational procedures can change between releases.

No quiz questions available

Could not load questions file