Neo4j Introduction

Neo4j is the database that put graph databases on the map. eBay uses it to detect fraud rings in real time. Airbnb uses it to power identity verification across 800 million listings. NASA uses it to manage the relationships between spacecraft components. The reason they all chose Neo4j comes down to one thing: Cypher — a query language so readable that a pattern you draw on a whiteboard is almost identical to the query you write in code.

What Makes Neo4j Different

Neo4j is a native graph database — meaning the storage engine itself is built around nodes and relationships, not tables that simulate a graph. Every node stores a direct physical pointer to each of its relationships. Every relationship stores direct pointers to its start and end nodes. Traversal follows those pointers — no index involved, no table scan, no JOIN.

The Cypher query language is designed around pattern matching. You describe the shape of the graph you want to find using ASCII art, and Neo4j finds it. Parentheses are nodes (), square brackets are relationships [], and arrows show direction ->.

Neo4j Architecture — How It Works Internally

Understanding Neo4j's internals helps you write faster queries and design better schemas.

Cypher Fundamentals — Reading the ASCII Art

Cypher has five core clauses. Everything you will ever write is a combination of these:

Hands-on — Building a Fraud Detection Graph

The scenario: You are a data engineer at a payment processor. Your fraud team has identified that fraudsters operate in rings — multiple accounts sharing the same device fingerprint or phone number, coordinating small transactions that individually look legitimate. Your existing SQL queries miss these rings because they only check one-hop relationships. You are prototyping a Neo4j model to surface connected suspicious accounts.

-- Create accounts with MERGE (safe to run multiple times — no duplicates)
MERGE (a1:Account {id: 'acc_001', name: 'Alice', status: 'flagged'})
MERGE (a2:Account {id: 'acc_002', name: 'Bob',   status: 'clean'})
MERGE (a3:Account {id: 'acc_003', name: 'Carol', status: 'clean'})

-- Create a shared device node
MERGE (d1:Device {fingerprint: 'fp_XK99'})

-- Connect all three accounts to the same device
MERGE (a1)-[:USES_DEVICE]->(d1)
MERGE (a2)-[:USES_DEVICE]->(d1)
MERGE (a3)-[:USES_DEVICE]->(d1);

Merged 1 node, set 3 properties, completed in 8 ms.
Merged 1 node, set 3 properties, completed in 2 ms.
Merged 1 node, set 3 properties, completed in 2 ms.
Merged 1 node, set 1 property, completed in 3 ms.
Created 1 relationship, completed in 2 ms.
Created 1 relationship, completed in 1 ms.
Created 1 relationship, completed in 1 ms.

The scenario continues: Alice's account has been flagged by the risk engine. You need to find every account that shares a device with Alice — one hop away — plus all accounts that share a device with those accounts — two hops. That is the fraud ring. In SQL: three self-joins and a UNION. In Cypher: variable-length traversal with a single pattern.

-- Find all accounts connected to Alice within 2 hops via shared devices
MATCH (alice:Account {name: 'Alice'})
      -[:USES_DEVICE*1..2]-(connected:Account)
WHERE connected <> alice
RETURN connected.name  AS account,
       connected.status AS status,
       connected.id     AS id;

+-----------------------+
| account | status | id      |
+-----------------------+
| "Bob"   | clean  | acc_002 |
| "Carol" | clean  | acc_003 |
+-----------------------+
2 rows available after 11 ms

The scenario continues: The risk team wants to see the actual path between Alice and each connected account — which device is the link, and when the connection was established. Returning the path object gives them full visibility without running separate queries.

-- Return the full path so investigators can see the connection chain
MATCH path = (alice:Account {name: 'Alice'})
             -[:USES_DEVICE*1..2]-(connected:Account)
WHERE connected <> alice
RETURN path,
       length(path)       AS hops,
       connected.name     AS connected_account
ORDER BY hops;

+--------------------------------------------------------+
| path                                    | hops | connected_account |
+--------------------------------------------------------+
| (Alice)-[:USES_DEVICE]->(fp_XK99)
  <-[:USES_DEVICE]-(Bob)                 | 2    | Bob               |
| (Alice)-[:USES_DEVICE]->(fp_XK99)
  <-[:USES_DEVICE]-(Carol)               | 2    | Carol             |
+--------------------------------------------------------+
2 rows available after 9 ms

Indexing in Neo4j — Making Lookups Fast

Every traversal in Neo4j starts somewhere. That starting point — the first node in a MATCH — needs to be found quickly. Without an index, Neo4j scans every node with the given label. With an index, it jumps directly to matching nodes. Always index the properties you use in your starting MATCH conditions.

The scenario: Your fraud graph now has 10 million account nodes. Every fraud investigation starts with MATCH (a:Account {id: 'acc_001'}). Without an index on id, Neo4j scans all 10 million Account nodes to find one. With an index, it is a single lookup. You are adding the index before the team runs production queries.

-- Create a range index on Account.id (Neo4j 5.x syntax)
CREATE INDEX account_id_idx IF NOT EXISTS
FOR (a:Account) ON (a.id);

-- Verify the index was created
SHOW INDEXES
YIELD name, labelsOrTypes, properties, state
WHERE 'Account' IN labelsOrTypes;

+------------------------------------------------------------------+
| name              | labelsOrTypes | properties | state  |
+------------------------------------------------------------------+
| account_id_idx    | ["Account"]   | ["id"]     | ONLINE |
+------------------------------------------------------------------+
1 row available after 14 ms

Index created and ONLINE — lookup on Account.id is now O(log n).

Connecting from Python — The Official Driver

The scenario: Your fraud detection service is written in Python. Every time the risk engine flags a transaction, it calls your service to check whether the source account is connected to any known-bad accounts within three hops. You need a production-safe Neo4j connection with a connection pool, parameterised queries to prevent injection, and proper session management.

from neo4j import GraphDatabase

# Driver maintains a connection pool — create once, reuse across requests
driver = GraphDatabase.driver(
    "bolt://localhost:7687",
    auth=("neo4j", "yourpassword")
)

def find_connected_accounts(account_id: str, max_hops: int = 3):
    query = """
        MATCH (start:Account {id: $account_id})
              -[:USES_DEVICE*1..$max_hops]-(connected:Account)
        WHERE connected <> start
        RETURN connected.id   AS id,
               connected.name AS name,
               connected.status AS status
    """
    with driver.session(database="neo4j") as session:
        result = session.run(query,
                             account_id=account_id,
                             max_hops=max_hops)
        return [record.data() for record in result]

>>> find_connected_accounts('acc_001', max_hops=2)
[
  {'id': 'acc_002', 'name': 'Bob',   'status': 'clean'},
  {'id': 'acc_003', 'name': 'Carol', 'status': 'clean'}
]
Query completed in 11 ms.

Query Planning — Understanding EXPLAIN and PROFILE

Before pushing a query to production, you want to know whether it is using your indexes or doing a full node scan. Neo4j has two tools for this: EXPLAIN shows the query plan without running the query, and PROFILE runs it and shows actual row counts at each step.

The scenario: A junior engineer wrote a fraud query that is taking 800ms in staging. You suspect it is doing a NodeByLabelScan instead of using the account_id_idx index. You run PROFILE to confirm before pushing a fix.

-- PROFILE runs the query and reports rows processed at each step
PROFILE
MATCH (alice:Account {id: 'acc_001'})
      -[:USES_DEVICE*1..2]-(connected:Account)
WHERE connected <> alice
RETURN connected.name, connected.status;

Operator              | Rows | DB Hits | Details
----------------------+------+---------+----------------------------
ProduceResults        |    2 |       0 | connected.name, status
Filter                |    2 |       4 | connected <> alice
VarLengthExpand(All)  |    2 |       8 | *1..2 via USES_DEVICE
NodeIndexSeek         |    1 |       2 | :Account(id) = 'acc_001'  ✓
----------------------+------+---------+----------------------------
Total DB hits: 14     |  Completed in 9 ms

Neo4j Deployment Options

Practice Questions — You're the Engineer

Quiz — Neo4j in Production