Real-World Modeling & App Integration

Application graphs succeed when the model matches access patterns, not when it mirrors every spreadsheet column. Start from questions: “What movies will a user like next?”, “Which users share taste?”, “How do we ingest ratings safely?” Nodes represent stable entities (User, Movie, Person); relationships carry verbs and often properties (RATED {score, at}. Avoid untyped catch-all edges.

Identity keys must be unique and immutable from the application’s perspective: a UUID or external auth subject for users, a catalog id for movies. Display titles are not reliable primary keys (remakes, localizations). Place uniqueness constraints on those keys. Add RANGE indexes for frequent filters (email lookup, movie slug). Document labels and relationship types in a short schema README so every service uses the same vocabulary.

The Movie graph you used in lessons 01–09 is a teaching dataset. Production recommendation features typically extend it with User nodes and RATED relationships, or a separate ratings subgraph linked to the same movies. Keep write paths idempotent with MERGE on constrained keys.

Neo4j supports official drivers for JavaScript/TypeScript, Python, Java, .NET, and Go. This lesson uses the JavaScript driver (neo4j-driver) and the Python driver (neo4j package). Create one Driver per application process. Drivers manage connection pooling and routing to cluster members. Do not open a new driver per HTTP request.

Acquire a Session for a unit of work, then run queries either as auto-commit statements or—preferred for writes and multi-statement logic—inside transaction functions (session.execute_read / execute_write in Python; session.executeRead / executeWrite in JavaScript). Transaction functions are retried automatically on transient errors when written as pure functions of the transaction object.

Always parameterize: pass a parameters map/dict, never concatenate user input into Cypher strings. Parameterization prevents Cypher injection and improves plan cache reuse. Close sessions when done; close the driver on process shutdown. Configuration values such as URI, username, and password must come from environment variables or a secrets manager—examples below use explicit placeholders only.

// Official neo4j-driver — placeholders only, no real secrets
import neo4j from 'neo4j-driver';

const uri = process.env.NEO4J_URI ?? 'neo4j://localhost:7687';
const user = process.env.NEO4J_USER ?? 'neo4j';
const password = process.env.NEO4J_PASSWORD ?? 'REPLACE_WITH_PASSWORD';

const driver = neo4j.driver(uri, neo4j.auth.basic(user, password));

async function moviesForActor(name) {
  const session = driver.session({ defaultAccessMode: neo4j.session.READ });
  try {
    return await session.executeRead(async (tx) => {
      const result = await tx.run(
        `MATCH (p:Person {name: $name})-[:ACTED_IN]->(m:Movie)
         RETURN m.title AS title ORDER BY title`,
        { name }
      );
      return result.records.map((r) => r.get('title'));
    });
  } finally {
    await session.close();
  }
}

# Official neo4j Python driver — placeholders only
import os
from neo4j import GraphDatabase, READ_ACCESS

URI = os.environ.get("NEO4J_URI", "neo4j://localhost:7687")
USER = os.environ.get("NEO4J_USER", "neo4j")
PASSWORD = os.environ.get("NEO4J_PASSWORD", "REPLACE_WITH_PASSWORD")

driver = GraphDatabase.driver(URI, auth=(USER, PASSWORD))

def movies_for_actor(name: str):
    def work(tx):
        result = tx.run(
            """
            MATCH (p:Person {name: $name})-[:ACTED_IN]->(m:Movie)
            RETURN m.title AS title ORDER BY title
            """,
            name=name,
        )
        return [record["title"] for record in result]

    with driver.session(default_access_mode=READ_ACCESS) as session:
        return session.execute_read(work)

Collaborative filtering on a graph: users who rated the same movies similarly can suggest unseen titles. Model:

• (:User {userId}) with uniqueness on userId
• (:Movie {movieId, title}) uniqueness on movieId
• (:User)-[:RATED {score}]->(:Movie) with score in 1–5

Seed a few users and ratings, then score candidate movies by counting distinct co-raters or summing neighbor scores. Production systems add normalization, time decay, content features, and online metrics—but the graph pattern is the durable core. Integrate the scoring Cypher behind a read transaction in your API, cache top-N when needed, and test with fixed seed data.

Testing. Load a fixture graph (constraints + seed MERGEs) in a disposable database or Aura free instance. Assert that Alice receives Top Gun before she rates it, and that after she rates it the title disappears from recommendations. Integration tests should spin a session, run Cypher, and never print passwords. Prefer testcontainers or an ephemeral DBMS when CI allows.

Production. Store NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD in a secrets manager. Enable TLS-capable URIs (neo4j+s:// or bolt+s://) for hosted services. Set connection pool size to match concurrent request levels. Use read replicas routing for pure recommend paths when on clusters. Monitor latency and failure rates; PROFILE the scoring query on realistic cardinality and add indexes on User(userId) and Movie(movieId) (constraints already provide them).

Security. Never embed API keys, passwords, or cloud tokens in committed source, lesson notes, or client-side JavaScript bundles. Rate-limit recommendation endpoints, authenticate callers, and authorize that userId in the query matches the authenticated subject unless an admin role is present.

Evolution. When you outgrow simple co-rating, consider storing normalized preference weights, separating implicit plays from explicit stars, or hybridizing with content features (genres as nodes). The driver lifecycle and parameterization rules do not change as the Cypher grows more sophisticated.