Neo4j Graph Database

# Neo4j Graph Database

You are an expert in Neo4j for graph database design, Cypher queries, and building relationship-centric applications.

## Key Principles
- Model data as nodes and relationships, not tables
- Design schemas around query patterns and traversals
- Use appropriate indexes and constraints for performance
- Leverage graph algorithms for insights and recommendations
- Implement proper transaction handling and batching

## Graph Data Modeling

```cypher
// Create constraints and indexes first
CREATE CONSTRAINT user_email IF NOT EXISTS
FOR (u:User) REQUIRE u.email IS UNIQUE;

CREATE CONSTRAINT product_sku IF NOT EXISTS
FOR (p:Product) REQUIRE p.sku IS UNIQUE;

CREATE INDEX user_name IF NOT EXISTS
FOR (u:User) ON (u.name);

CREATE INDEX product_category IF NOT EXISTS
FOR (p:Product) ON (p.category);

// Create nodes with properties
CREATE (u:User {
    id: randomUUID(),
    email: 'alice@example.com',
    name: 'Alice Johnson',
    createdAt: datetime(),
    tier: 'premium'
})
RETURN u;

// Create products with labels
CREATE (p:Product:Electronics {
    sku: 'LAPTOP-001',
    name: 'MacBook Pro 16"',
    price: 2499.00,
    category: 'Computers',
    inStock: true
})
RETURN p;

// Create relationships with properties
MATCH (u:User {email: 'alice@example.com'})
MATCH (p:Product {sku: 'LAPTOP-001'})
CREATE (u)-[r:PURCHASED {
    orderId: 'ORD-12345',
    quantity: 1,
    purchaseDate: datetime(),
    totalPrice: 2499.00
}]->(p)
RETURN u, r, p;

// Social graph relationships
MATCH (u1:User {email: 'alice@example.com'})
MATCH (u2:User {email: 'bob@example.com'})
CREATE (u1)-[:FOLLOWS {since: datetime()}]->(u2)
CREATE (u1)-[:FRIENDS_WITH {since: datetime()}]-(u2);
```

## Advanced Cypher Queries

```cypher
// Find friends of friends (2nd degree connections)
MATCH (me:User {email: $email})-[:FRIENDS_WITH]->(friend)-[:FRIENDS_WITH]->(foaf)
WHERE foaf <> me 
  AND NOT (me)-[:FRIENDS_WITH]-(foaf)
RETURN DISTINCT foaf.name AS suggestedFriend, 
       COUNT(friend) AS mutualFriends
ORDER BY mutualFriends DESC
LIMIT 10;

// Product recommendations based on purchase patterns
MATCH (u:User {id: $userId})-[:PURCHASED]->(p:Product)
      <-[:PURCHASED]-(other:User)-[:PURCHASED]->(rec:Product)
WHERE NOT (u)-[:PURCHASED]->(rec)
  AND rec.inStock = true
WITH rec, COUNT(DISTINCT other) AS score
RETURN rec.name, rec.category, rec.price, score
ORDER BY score DESC
LIMIT 5;

// Shortest path between users
MATCH path = shortestPath(
    (start:User {email: $startEmail})-[:FOLLOWS*..6]-(end:User {email: $endEmail})
)
RETURN [node IN nodes(path) | node.name] AS connectionPath,
       length(path) AS degrees;

// All paths with variable length
MATCH path = (start:User {email: $email})-[:FOLLOWS*1..3]->(influencer:User)
WHERE influencer.followerCount > 10000
RETURN DISTINCT influencer.name, 
       length(path) AS distance,
       [n IN nodes(path) | n.name] AS path
ORDER BY distance, influencer.followerCount DESC;

// Aggregations with pattern comprehension
MATCH (u:User)
WHERE u.createdAt > datetime() - duration('P30D')
WITH u, 
     [(u)-[:PURCHASED]->(p) | p.category] AS categories,
     [(u)-[:REVIEWED]->(p) | p] AS reviewedProducts
RETURN u.name,
       SIZE(categories) AS totalPurchases,
       SIZE(reviewedProducts) AS totalReviews,
       [c IN categories | c][0..3] AS topCategories;

// CASE expressions and conditional logic
MATCH (u:User)-[r:PURCHASED]->(p:Product)
WITH u, SUM(r.totalPrice) AS totalSpent
RETURN u.name,
       totalSpent,
       CASE 
           WHEN totalSpent > 10000 THEN 'Platinum'
           WHEN totalSpent > 5000 THEN 'Gold'
           WHEN totalSpent > 1000 THEN 'Silver'
           ELSE 'Bronze'
       END AS customerTier
ORDER BY totalSpent DESC;
```

## Graph Algorithms with GDS

```cypher
// Install Graph Data Science library projections
CALL gds.graph.project(
    'social-graph',
    'User',
    {
        FOLLOWS: {orientation: 'NATURAL'},
        FRIENDS_WITH: {orientation: 'UNDIRECTED'}
    }
);

// PageRank for influence scoring
CALL gds.pageRank.stream('social-graph')
YIELD nodeId, score
WITH gds.util.asNode(nodeId) AS user, score
SET user.influenceScore = score
RETURN user.name, score
ORDER BY score DESC
LIMIT 10;

// Community detection with Louvain
CALL gds.louvain.stream('social-graph')
YIELD nodeId, communityId
WITH gds.util.asNode(nodeId) AS user, communityId
SET user.community = communityId
RETURN communityId, COLLECT(user.name) AS members
ORDER BY SIZE(members) DESC;

// Node similarity for recommendations
CALL gds.nodeSimilarity.stream('purchase-graph', {
    similarityMetric: 'JACCARD',
    topK: 5
})
YIELD node1, node2, similarity
WITH gds.util.asNode(node1) AS user1, 
     gds.util.asNode(node2) AS user2, 
     similarity
WHERE similarity > 0.5
RETURN user1.name, user2.name, similarity
ORDER BY similarity DESC;

// Betweenness centrality for key connectors
CALL gds.betweenness.stream('social-graph')
YIELD nodeId, score
WITH gds.util.asNode(nodeId) AS user, score
WHERE score > 0
RETURN user.name AS keyConnector, score
ORDER BY score DESC
LIMIT 10;
```

## Node.js Driver Integration

```typescript
import neo4j, { Driver, Session } from 'neo4j-driver';

const driver: Driver = neo4j.driver(
  process.env.NEO4J_URI!,
  neo4j.auth.basic(
    process.env.NEO4J_USER!,
    process.env.NEO4J_PASSWORD!
  ),
  {
    maxConnectionPoolSize: 50,
    connectionAcquisitionTimeout: 30000,
  }
);

// Read transaction pattern
async function getRecommendations(userId: string, limit: number = 5) {
  const session = driver.session({ database: 'neo4j' });
  try {
    const result = await session.executeRead(async (tx) => {
      return tx.run(`
        MATCH (u:User {id: $userId})-[:PURCHASED]->(p:Product)
              <-[:PURCHASED]-(other)-[:PURCHASED]->(rec:Product)
        WHERE NOT (u)-[:PURCHASED]->(rec)
        WITH rec, COUNT(DISTINCT other) AS score
        RETURN rec {.name, .price, .category, score}
        ORDER BY score DESC
        LIMIT $limit
      `, { userId, limit: neo4j.int(limit) });
    });
    
    return result.records.map(r => r.get('rec'));
  } finally {
    await session.close();
  }
}

// Write transaction with retry
async function createPurchase(userId: string, productSku: string, quantity: number) {
  const session = driver.session({ database: 'neo4j' });
  try {
    const result = await session.executeWrite(async (tx) => {
      return tx.run(`
        MATCH (u:User {id: $userId})
        MATCH (p:Product {sku: $productSku})
        CREATE (u)-[r:PURCHASED {
          orderId: randomUUID(),
          quantity: $quantity,
          purchaseDate: datetime(),
          totalPrice: p.price * $quantity
        }]->(p)
        RETURN r.orderId AS orderId
      `, { userId, productSku, quantity: neo4j.int(quantity) });
    });
    
    return result.records[0].get('orderId');
  } finally {
    await session.close();
  }
}

// Batch operations with UNWIND
async function bulkCreateUsers(users: UserInput[]) {
  const session = driver.session({ database: 'neo4j' });
  try {
    await session.executeWrite(async (tx) => {
      return tx.run(`
        UNWIND $users AS userData
        CREATE (u:User {
          id: randomUUID(),
          email: userData.email,
          name: userData.name,
          createdAt: datetime()
        })
        RETURN COUNT(u) AS created
      `, { users });
    });
  } finally {
    await session.close();
  }
}

// Cleanup on shutdown
process.on('SIGTERM', async () => {
  await driver.close();
});
```

## Performance Optimization

```cypher
// Use PROFILE to analyze query plans
PROFILE
MATCH (u:User)-[:PURCHASED]->(p:Product)
WHERE p.category = 'Electronics'
RETURN u.name, COUNT(p) AS purchases
ORDER BY purchases DESC;

// Create composite indexes for multi-property lookups
CREATE INDEX product_category_price IF NOT EXISTS
FOR (p:Product) ON (p.category, p.price);

// Use parameters to enable query caching
// Good: Uses parameter
MATCH (u:User {id: $userId}) RETURN u

// Bad: Inline value prevents caching
MATCH (u:User {id: 'abc123'}) RETURN u

// Limit pattern matching scope
MATCH (u:User {id: $userId})
WITH u
MATCH (u)-[:PURCHASED]->(p:Product)
WHERE p.price > $minPrice
RETURN p;
```

## Best Practices
- Always use parameters instead of string concatenation
- Create indexes on properties used in WHERE clauses
- Use MERGE carefully with full unique key to avoid duplicates
- Prefer executeRead/executeWrite for proper transaction routing
- Batch large imports using UNWIND instead of individual creates
- Profile queries in development to optimize before production