/using-graph-databases

name: using-graph-databases
description: Graph database implementation for relationship-heavy data models. Use when building social networks, recommendation engines, knowledge graphs, or fraud detection. Covers Neo4j (primary), ArangoDB, Amazon Neptune, Cypher query patterns, and graph data modeling.

Graph Databases

Purpose

This skill guides selection and implementation of graph databases for applications where relationships between entities are first-class citizens. Unlike relational databases that model relationships through foreign keys and joins, graph databases natively represent connections as properties, enabling efficient traversal-heavy queries.

When to Use This Skill

Use graph databases when:

• **Deep relationship traversals** (4+ hops): "Friends of friends of friends"
• **Variable/evolving relationships**: Schema changes don't break existing queries
• **Path finding**: Shortest route, network analysis, dependency chains
• **Pattern matching**: Fraud detection, recommendation engines, access control

**Do NOT use graph databases when**:

• Fixed schema with shallow joins (2-3 tables) → Use PostgreSQL
• Primarily aggregations/analytics → Use columnar databases
• Key-value lookups only → Use Redis/DynamoDB

Quick Decision Framework

DATA CHARACTERISTICS?
├── Fixed schema, shallow joins (≤3 hops)
│   └─ PostgreSQL (relational)
│
├── Already on PostgreSQL + simple graphs
│   └─ Apache AGE (PostgreSQL extension)
│
├── Deep traversals (4+ hops) + general purpose
│   └─ Neo4j (battle-tested, largest ecosystem)
│
├── Multi-model (documents + graph)
│   └─ ArangoDB
│
├── AWS-native, serverless
│   └─ Amazon Neptune
│
└── Real-time streaming, in-memory
    └─ Memgraph

Core Concepts

Property Graph Model

Graph databases store data as:

• **Nodes** (vertices): Entities with labels and properties
• **Relationships** (edges): Typed connections with properties
• **Properties**: Key-value pairs on nodes and relationships

(Person {name: "Alice", age: 28})-[:FRIEND {since: "2020-01-15"}]->(Person {name: "Bob"})

Query Languages

| Language | Databases | Readability | Best For | |----------|-----------|-------------|----------| | **Cypher** | Neo4j, Memgraph, AGE | ⭐⭐⭐⭐⭐ SQL-like | General purpose | | **Gremlin** | Neptune, JanusGraph | ⭐⭐⭐ Functional | Cross-database | | **AQL** | ArangoDB | ⭐⭐⭐⭐ SQL-like | Multi-model | | **SPARQL** | Neptune, RDF stores | ⭐⭐⭐ W3C standard | Semantic web |

Common Cypher Patterns

Reference `references/cypher-patterns.md` for comprehensive examples.

Pattern 1: Basic Matching

// Find all users at a company
MATCH (u:User)-[:WORKS_AT]->(c:Company {name: 'Acme Corp'})
RETURN u.name, u.title

Pattern 2: Variable-Length Paths

// Find friends up to 3 degrees away
MATCH (u:User {name: 'Alice'})-[:FRIEND*1..3]->(friend)
WHERE u <> friend
RETURN DISTINCT friend.name
LIMIT 100

Pattern 3: Shortest Path

// Find shortest connection between two users
MATCH path = shortestPath(
  (a:User {name: 'Alice'})-[*]-(b:User {name: 'Bob'})
)
RETURN path, length(path) AS distance

Pattern 4: Recommendations

// Collaborative filtering: Products liked by similar users
MATCH (u:User {id: $userId})-[:PURCHASED]->(p:Product)<-[:PURCHASED]-(similar)
MATCH (similar)-[:PURCHASED]->(rec:Product)
WHERE NOT exists((u)-[:PURCHASED]->(rec))
RETURN rec.name, count(*) AS score
ORDER BY score DESC
LIMIT 10

Pattern 5: Fraud Detection

// Detect circular money flows
MATCH path = (a:Account)-[:SENT*3..6]->(a)
WHERE all(r IN relationships(path) WHERE r.amount > 1000)
RETURN path, [r IN relationships(path) | r.amount] AS amounts

Database Selection Guide

Neo4j (Primary Recommendation)

**Use for**: General-purpose graph applications

**Strengths**:

• Most mature (2007), largest community (2M+ developers)
• 65+ graph algorithms (GDS library): PageRank, Louvain, Dijkstra
• Best tooling: Neo4j Browser, Bloom visualization
• Comprehensive Cypher support

**Installation**:

# Python driver
pip install neo4j

# TypeScript driver
npm install neo4j-driver

# Rust driver
cargo add neo4rs

Reference: `references/neo4j.md`

ArangoDB

**Use for**: Multi-model applications (documents + graph)

**Strengths**:

• Store documents AND graph in one database
• AQL combines document and graph queries
• Schema flexibility with relationships

Reference: `references/arangodb.md`

Apache AGE

**Use for**: Adding graph capabilities to existing PostgreSQL

**Strengths**:

• Extend PostgreSQL with graph queries
• No new infrastructure needed
• Query both relational and graph data

Reference: Implementation details in examples/

Amazon Neptune

**Use for**: AWS-native, serverless deployments

**Strengths**:

• Fully managed, auto-scaling
• Supports Gremlin AND SPARQL
• AWS ecosystem integration

Graph Data Modeling Patterns

Reference `references/graph-modeling.md` for comprehensive patterns.

Best Practice 1: Relationships as First-Class Citizens

**Anti-pattern** (storing relationships in node properties):

// BAD
(:Person {name: 'Alice', friend_ids: ['b123', 'c456']})

**Pattern** (explicit relationships):

// GOOD
(:Person {name: 'Alice'})-[:FRIEND]->(:Person {id: 'b123'})
(:Person {name: 'Alice'})-[:FRIEND]->(:Person {id: 'c456'})

Best Practice 2: Relationship Properties for Metadata

// Track interaction details on relationships
(:Person)-[:FRIEND {
  since: '2020-01-15',
  strength: 0.85,
  last_interaction: datetime()
}]->(:Person)

Best Practice 3: Bounded Traversals for Performance

// SLOW: Unbounded traversal
MATCH (a)-[:FRIEND*]->(distant)
RETURN distant

// FAST: Bounded depth with index
MATCH (a)-[:FRIEND*1..4]->(distant)
WHERE distant.active = true
RETURN distant
LIMIT 100

Best Practice 4: Avoid Supernodes

**Problem**: Nodes with thousands of relationships slow traversals.