Intermediate Examples

// Example 27: OPTIONAL MATCH Preserves Rows as NULL.
CREATE (:Person {name: 'Ada'});
// => Ada has NO relationships at all
CREATE (m:Person {name: 'Grace'})-[:DIRECTED]->(:Movie {title: 'Compile Error'});
// => Ada directed nothing; Grace directed one movie -- deliberately asymmetric fixture
 
// OPTIONAL MATCH (co-05) never drops the outer row, even when the inner pattern matches nothing.
MATCH (p:Person)
// => matches BOTH Ada and Grace, unfiltered
OPTIONAL MATCH (p)-[:DIRECTED]->(m)
// => for Ada, this inner pattern finds NOTHING -- but her outer row survives anyway
RETURN p.name, m;
// => Ada's row SURVIVES with m = NULL -- a plain MATCH here would have dropped her entirely

+------------------------------------+
| p.name  | m                        |
+------------------------------------+
| "Ada"   | NULL                     |
| "Grace" | (:Movie {title: "..."})  |
+------------------------------------+
2 rows

// Example 28: Pipeline a Query with WITH.
CREATE (p1:Person {name: 'Ada'})-[:ACTED_IN]->(:Movie {title: 'M1'})
// => Ada's first movie, p1 aliased for reuse below
CREATE (p1)-[:ACTED_IN]->(:Movie {title: 'M2'})
// => Ada's second movie
CREATE (p1)-[:ACTED_IN]->(:Movie {title: 'M3'})
// => Ada's third movie
CREATE (:Person {name: 'Bob'})-[:ACTED_IN]->(:Movie {title: 'M4'});
// => Ada: 3 movies, Bob: 1 movie
 
// WITH (co-23) carries p and the computed movies count FORWARD into a second WHERE stage.
MATCH (p:Person)-[:ACTED_IN]->(m)
// => matches every (person, movie) pair, one row per ACTED_IN edge
WITH p, count(m) AS movies
// => aggregates rows PER person -- movies is now a count, not individual movie rows
WHERE movies > 2
// => this filter runs AFTER aggregation -- impossible with a plain WHERE alone
RETURN p.name, movies;
// => Bob (1 movie) is filtered out HERE -- a plain WHERE before aggregation cannot express this

+---------+---------+
| p.name  | movies  |
+---------+---------+
| "Ada"   | 3       |
+---------+---------+
1 row

// Example 29: UNWIND a List into Rows.
UNWIND [1, 2, 3] AS x
CREATE (:Number {value: x});
// => co-23: UNWIND expands the 3-element list into 3 separate rows -- CREATE then runs ONCE PER ROW
 
MATCH (n:Number) RETURN n.value ORDER BY n.value;
// => three SEPARATE nodes exist, one per list element

+----------+
| n.value  |
+----------+
| 1        |
| 2        |
| 3        |
+----------+
3 rows

// Example 30: Aggregate with count() and collect().
CREATE (p:Person {name: 'Ada'})-[:ACTED_IN]->(:Movie {title: 'M1'})
// => Ada's first movie, p aliased for reuse
CREATE (p)-[:ACTED_IN]->(:Movie {title: 'M2'});
// => Ada's second movie -- two ACTED_IN edges off the SAME person
 
// co-23: p.name is the IMPLICIT grouping key -- collect(m.title) aggregates per group.
MATCH (p:Person)-[:ACTED_IN]->(m)
// => two rows come out of this MATCH, one per ACTED_IN edge
RETURN p.name, collect(m.title) AS movies;
// => one row per DISTINCT p.name, with every matching m.title folded into a single list

+---------+------------------+
| p.name  | movies           |
+---------+------------------+
| "Ada"   | ["M1", "M2"]     |
+---------+------------------+
1 row

// Example 31: ORDER BY, LIMIT, and SKIP.
CREATE (:Person {name: 'Ada', born: 1815});
// => oldest of the five
CREATE (:Person {name: 'Grace', born: 1906});
CREATE (:Person {name: 'Alan', born: 1912});
CREATE (:Person {name: 'Katherine', born: 1918});
// => second-most-recently born
CREATE (:Person {name: 'Radia', born: 1943});
// => most recently born of the five -- expected to sort FIRST under DESC below
 
// co-23: ORDER BY sorts, LIMIT caps, SKIP offsets -- all THREE apply AFTER RETURN's projection.
MATCH (p:Person)
// => all 5 people, unfiltered
RETURN p.name
// => projects just the name -- born is used for sorting only, not returned
ORDER BY p.born DESC
// => sorts the 5 rows newest-born first
SKIP 0
// => SKIP 0 means "start from the very top" -- must precede LIMIT (Cypher clause order is
// ORDER BY, then SKIP, then LIMIT)
LIMIT 3;
// => the 3 MOST RECENTLY BORN people, most recent first

+--------------+
| p.name       |
+--------------+
| "Radia"      |
| "Katherine"  |
| "Alan"       |
+--------------+
3 rows

// Example 32: A CALL {} Subquery.
CREATE (t1:Team {name: 'Alpha'})<-[:PLAYS_FOR]-(:Player {name: 'Ada'})
// => Alpha's first player, t1 aliased for reuse
CREATE (t1)<-[:PLAYS_FOR]-(:Player {name: 'Bob'})
// => Alpha's second player
CREATE (t2:Team {name: 'Beta'})<-[:PLAYS_FOR]-(:Player {name: 'Cid'});
// => Alpha: 2 players, Beta: 1 player
 
MATCH (t:Team)
// => outer MATCH: one row per team, Alpha and Beta
CALL (t) {
  // co-05: this subquery re-matches per OUTER row -- t is explicitly scoped in via CALL (t)
  MATCH (p:Player)-[:PLAYS_FOR]->(t)
  // => finds players for THIS row's team only, never mixing across teams
  RETURN collect(p.name) AS players
  // => the subquery's own return value -- one list, scoped to this one team
}
RETURN t.name, players;
// => co-23: one correctly-scoped player list PER team, computed inside its own subquery

+---------+--------------------+
| t.name  | players            |
+---------+--------------------+
| "Alpha" | ["Ada", "Bob"]     |
| "Beta"  | ["Cid"]            |
+---------+--------------------+
2 rows

-- Example 33a: many-to-many via a JOIN TABLE.
-- => 3 tables total: 2 entity tables (student, course) + 1 junction table (enrollment)
CREATE TABLE student (id INTEGER PRIMARY KEY, name TEXT NOT NULL);
 
-- => the "one" entity side, no relationship info here
-- => id auto-increments via INTEGER PRIMARY KEY -- the same pattern every entity table below uses
CREATE TABLE course (id INTEGER PRIMARY KEY, name TEXT NOT NULL);
 
-- => the "other" entity side, also no relationship info
CREATE TABLE enrollment (
  student_id INTEGER NOT NULL,
  -- => foreign key by convention only -- SQLite does not enforce it without FOREIGN KEY syntax
  course_id INTEGER NOT NULL
  -- => paired with student_id, together forming the composite "who takes what" fact
);
 
-- => enrollment is the JOIN TABLE -- its only job is connecting the two entity tables
-- => it has no PRIMARY KEY of its own -- the pair (student_id, course_id) IS the only fact stored
-- => nothing here PREVENTS duplicate (student_id, course_id) rows without an added constraint
INSERT INTO
  student
VALUES
  (1, 'Ada');
 
-- => id 1, Ada -- becomes the JOIN anchor (student.id) resolved below
-- => nothing about "what Ada takes" lives on this row at all
INSERT INTO
  course
VALUES
  (1, 'Graph Theory');
 
-- => id 1, Graph Theory -- becomes the JOIN target (course.id) resolved below
-- => one student row, one course row -- neither knows about the other yet
INSERT INTO
  enrollment
VALUES
  (1, 1);
 
-- => (student_id 1, course_id 1) -- the ONLY row connecting Ada to Graph Theory
-- => a second course for Ada would be a SECOND row here, not a change to an existing one
-- => the fact "Ada takes Graph Theory" lives ONLY in this junction row
SELECT
  student.name,
  -- => projects the student side of the fact
  course.name
  -- => projects the course side of the fact -- both columns come from DIFFERENT tables
  -- => neither column comes from enrollment itself -- it only supplies the JOIN path
FROM
  student
  -- => the starting table -- everything else below joins outward from here
  JOIN enrollment ON enrollment.student_id = student.id
  -- => join 1: student to its enrollment rows
  -- => this is the ONLY point where student and enrollment connect at all
  JOIN course ON course.id = enrollment.course_id;
 
-- => join 2: enrollment row to the actual course
-- => TWO joins needed just to answer "who takes what"
-- => a THIRD student or course would still need only these SAME two joins to resolve
-- => contrast with Example 33b below -- the graph form needs ZERO extra joins for this same fact

// Example 33b: the SAME many-to-many fact, a TAKES relationship (co-12, co-03).
CREATE (:Student {name: 'Ada'})-[:TAKES]->(:Course {name: 'Graph Theory'});
// => the relationship itself IS the join table -- no separate junction node needed
 
MATCH (s:Student)-[:TAKES]->(c:Course)
// => a single 1-hop pattern -- no intermediate junction to join through
RETURN s.name, c.name;
// => ZERO extra joins -- the pattern is one hop, whether one student or one thousand

relational.sql -> ("Ada", "Graph Theory")   (2 JOINs)
graph.cypher   -> ("Ada", "Graph Theory")   (1 hop, 0 joins)

// Example 34: A Property on a Many-to-Many Relationship. (co-12)
CREATE (s:Student {name: 'Ada'})-[:TAKES {grade: 'A'}]->(:Course {name: 'Graph Theory'})
// => Ada's first enrollment, s aliased for reuse -- grade 'A' lives ON this edge
CREATE (s)-[:TAKES {grade: 'B'}]->(:Course {name: 'Databases'});
// => the SAME student, two different enrollments, each with its OWN grade on the edge
 
MATCH (s:Student)-[t:TAKES]->(c:Course)
// => t is bound to the RELATIONSHIP -- t.grade below reads off the edge, not a node
RETURN c.name, t.grade;
// => t.grade is queryable PER enrollment -- not duplicated onto the student or the course

+----------------+---------+
| c.name         | t.grade |
+----------------+---------+
| "Graph Theory" | "A"     |
| "Databases"    | "B"     |
+----------------+---------+
2 rows

// Example 35: Walk a Hierarchical Tree Upward. (co-13)
CREATE (:Person {name: 'IC'})-[:REPORTS_TO]->(:Person {name: 'Manager'})
      -[:REPORTS_TO]->(:Person {name: 'Director'})-[:REPORTS_TO]->(:Person {name: 'CEO'});
// => a 3-hop reporting chain, IC at the bottom, CEO at the top
 
MATCH (ic:Person {name: 'IC'})-[:REPORTS_TO*]->(boss)
// => unbounded * walks the chain AS FAR AS IT GOES upward from ic
RETURN boss.name;
// => hand-traced: Manager (1 hop), Director (2 hops), CEO (3 hops) -- the WHOLE chain upward

+-------------+
| boss.name   |
+-------------+
| "Manager"   |
| "Director"  |
| "CEO"       |
+-------------+
3 rows

// Example 36: Walk a Hierarchical Tree Downward. (co-13, co-09)
// ONE query, two CREATE clauses with NO semicolon between them, so mgr stays bound
// across BOTH clauses -- this is what avoids accidentally creating a SECOND Manager node.
CREATE (mgr:Person {name: 'Manager'})<-[:REPORTS_TO]-(:Person {name: 'Senior'})
      <-[:REPORTS_TO]-(:Person {name: 'Junior'})
// => a 2-hop downward chain off mgr: Manager <- Senior <- Junior
CREATE (mgr)<-[:REPORTS_TO]-(:Person {name: 'Senior2'});
// => a THIRD, direct report, reusing the SAME mgr -- not a second Manager node
 
MATCH (m:Person {name: 'Manager'})<-[:REPORTS_TO*]-(report)
// => reversed arrow (co-09) walks DOWNWARD -- every direct AND indirect report of Manager
RETURN DISTINCT report.name;
// => three reports total: Senior (1 hop), Senior2 (1 hop), Junior (2 hops, via Senior)

+-------------+
| report.name |
+-------------+
| "Senior"    |
| "Senior2"   |
| "Junior"    |
+-------------+
3 rows

// Example 37: Bill-of-Materials Parts Explosion. (co-14, co-09)
CREATE (bolt:Part {name: 'Bolt'})-[:PART_OF]->(bracket:Part {name: 'Bracket'})
      -[:PART_OF]->(frame:Part {name: 'Frame'})
// => Bolt is PART_OF Bracket; Bracket is PART_OF Frame -- a 2-hop assembly chain
CREATE (:Part {name: 'Screw'})-[:PART_OF]->(bracket);
// => a SECOND part feeding into the SAME bracket -- Bracket is made of Bolt AND Screw
 
MATCH (frame:Part {name: 'Frame'})<-[:PART_OF*]-(sub)
// => reversed *, unbounded -- every part in the WHOLE sub-assembly tree beneath Frame
RETURN sub.name;
// => hand-traced: Bracket (1 hop), Bolt (2 hops, via Bracket), Screw (2 hops, via Bracket)

+-----------+
| sub.name  |
+-----------+
| "Bracket" |
| "Bolt"    |
| "Screw"   |
+-----------+
3 rows

-- Example 38a: the SAME bill-of-materials explosion, a recursive CTE (co-14).
-- one table for every part, self-referencing to express the assembly hierarchy
CREATE TABLE part (
  id INTEGER PRIMARY KEY,
  -- => auto-incrementing identity -- the same PRIMARY KEY pattern every table in this course uses
  name TEXT NOT NULL,
  -- => the human-readable label the final SELECT below eventually returns
  part_of INTEGER
  -- => nullable, self-referencing -- NULL means "top of the assembly, part of nothing"
);
 
-- => part_of is a self-referencing foreign key -- the SQL analogue of :PART_OF
-- => one row per part -- the whole hierarchy lives entirely in this single self-referencing column
-- => 4 parts, 3 assembly levels deep: Frame -> Bracket -> {Bolt, Screw}
INSERT INTO
  part
VALUES
  (1, 'Frame', NULL),
  -- => the TOP assembly -- part_of NULL means "not part of anything else"
  (2, 'Bracket', 1),
  -- => part_of 1 means "Bracket is part of Frame" -- the base case's target below
  (3, 'Bolt', 2),
  -- => part_of 2 means "Bolt is part of Bracket"
  (4, 'Screw', 2);
 
-- => part_of 2 again -- Bracket has TWO children, Bolt and Screw, both pointing back to id 2
-- => Frame itself never appears as a part_of value -- nothing claims to be "part of Frame's parent"
-- => a second child of Bracket -- Bracket is made of BOTH Bolt and Screw
-- the recursive CTE itself -- base case, then a repeated recursive case, unioned together
-- => "recursive" here means SQLite re-runs the SELECT after UNION ALL until it adds zero new rows
WITH RECURSIVE
  -- => RECURSIVE is required here -- a plain WITH would reject the self-reference in the JOIN below
  sub_parts (id, name) AS (
    -- => sub_parts is the CTE's own name -- the recursive half below refers back to it by name
    -- => declares the CTE's shape up front -- two columns, id and name, matching both SELECTs below
    SELECT
      id,
      -- => seeds the id column of sub_parts
      name
      -- => seeds the name column of sub_parts
    FROM
      part
      -- => the base case reads directly from the raw part table, not from sub_parts itself
    WHERE
      part_of = 1 -- base case: direct children of Frame
      -- => runs EXACTLY ONCE -- seeds sub_parts with Bracket's direct children, id 2 only
    UNION ALL
    -- => UNION ALL is what keeps FEEDING the recursion its own prior output
    -- => UNION (no ALL) would also de-duplicate rows -- unnecessary here since ids are already unique
    SELECT
      p.id,
      -- => the recursive half's id column, unioned onto the base case's rows
      p.name
      -- => the recursive half's name column
    FROM
      part p
      -- => aliased p -- every part row is a CANDIDATE child this round, filtered by the JOIN below
      JOIN sub_parts sp ON p.part_of = sp.id -- recursive case: children of children
      -- => re-runs each round against whatever sub_parts already holds, growing it by one level
      -- => round 1 matches Bolt and Screw (part_of 2); round 2 finds no new matches and stops
  )
  -- => the recursion terminates when a round finds no new matching rows
SELECT
  name
  -- => projects only the name column from the fully-expanded sub_parts result
FROM
  sub_parts;
 
-- => sub_parts now holds every descendant -- base case rows PLUS every recursive round's rows
-- => output: Bracket, Bolt, Screw -- Frame itself is excluded, WHERE seeded ONLY at part_of = 1
-- => the recursive UNION ALL must be written explicitly, base case + recursive case, by hand
-- => forgetting the recursive JOIN condition risks an infinite loop -- Cypher's * has no such risk
-- => a 5th assembly level would need ZERO query changes -- the recursion already handles any depth

// Example 38b: repeated here for direct comparison (co-03).
MATCH (frame:Part {name: 'Frame'})<-[:PART_OF*]-(sub)
// => reversed *, unbounded -- same one-line traversal Example 37 already used
// => no rewrite needed when the assembly tree grows another level deep
RETURN sub.name;
// => sub binds to every part reachable in that reversed PART_OF chain
// => output: Bracket, Bolt, Screw -- identical 3 rows as the SQL CTE above
// => the ENTIRE recursion is expressed by *, no explicit base-case/recursive-case split

relational.sql (recursive CTE) -> Bracket, Bolt, Screw  (same 3 rows as Example 37)

// Example 39: Recommendation by Co-Occurrence. (co-15, co-08)
CREATE (u:User {name: 'Ada'})-[:BOUGHT]->(shared:Item {name: 'Keyboard'})
// => Ada bought exactly one item, shared aliased for reuse below
CREATE (other:User {name: 'Bob'})-[:BOUGHT]->(shared)
// => Bob bought the SAME Keyboard node as Ada -- bound once and reused, not a second CREATE
// with a matching name, which would mint a structurally distinct node
CREATE (other)-[:BOUGHT]->(:Item {name: 'Mousepad'});
// => Ada and Bob BOTH bought Keyboard; Bob ALSO bought Mousepad -- Ada has not
 
MATCH (u:User {name: 'Ada'})-[:BOUGHT]->(:Item)<-[:BOUGHT]-(other)-[:BOUGHT]->(rec:Item)
// => 3-hop walk: Ada's item -> co-buyer -> co-buyer's OTHER purchase, bound as rec
WHERE NOT (u)-[:BOUGHT]->(rec)
// => the exclusion filter -- rec must NOT already be one of Ada's own purchases
RETURN rec.name, count(*) AS score
ORDER BY score DESC;
// => Mousepad recommended -- co-08 walks: shared item -> other buyer -> their OTHER purchase

+------------+---------+
| rec.name   | score   |
+------------+---------+
| "Mousepad" | 1       |
+------------+---------+
1 row

// Example 40: Recommendation with a Minimum-Overlap Threshold. (co-15, co-23)
CREATE (u:User {name: 'Ada'})-[:BOUGHT]->(kb:Item {name: 'Keyboard'})
// => Ada's first item, u and kb both aliased for reuse below
CREATE (u)-[:BOUGHT]->(mon:Item {name: 'Monitor'})
// => Ada's second item, mon aliased for reuse below
CREATE (strong:User {name: 'Bob'})-[:BOUGHT]->(kb)
// => Bob shares the SAME Keyboard node as Ada -- bound once and reused, not re-CREATEd
CREATE (strong)-[:BOUGHT]->(mon)
// => Bob shares the SAME Monitor node as Ada too -- overlap = 2 shared nodes, not 2 coincidences
CREATE (strong)-[:BOUGHT]->(:Item {name: 'Mousepad'})
// => Bob's OWN extra item, the eventual recommendation candidate
CREATE (weak:User {name: 'Cid'})-[:BOUGHT]->(kb)
// => Cid shares the SAME Keyboard node with Ada -- overlap = 1
CREATE (weak)-[:BOUGHT]->(:Item {name: 'Headset'});
// => Bob shares 2 items with Ada (strong overlap); Cid shares only 1 (weak overlap)
 
MATCH (u:User {name: 'Ada'})-[:BOUGHT]->(shared:Item)<-[:BOUGHT]-(other)
// => matches every (shared item, co-buyer) pair for Ada
// co-23: WITH computes a per-other-user overlap COUNT before the recommendation stage runs
WITH u, other, count(DISTINCT shared) AS overlap
// => aggregates PER co-buyer -- overlap is now a count, not individual shared-item rows
WHERE overlap >= 2
// => the threshold gate -- only co-buyers meeting this bar reach the next MATCH
MATCH (other)-[:BOUGHT]->(rec:Item)
// => the surviving co-buyer's OWN full purchase list
WHERE NOT (u)-[:BOUGHT]->(rec)
// => excludes anything Ada already owns
RETURN DISTINCT rec.name;
// => co-15: only Bob (overlap=2) contributes -- Cid's single shared item never clears the bar

+------------+
| rec.name   |
+------------+
| "Mousepad" |
+------------+
1 row

// Example 41: Fraud Ring via a Shared Attribute. (co-16, co-08)
CREATE (a:Account {name: 'Acc-A'})-[:USES]->(d:Device {id: 'dev-42'})<-[:USES]-(b:Account {name: 'Acc-B'});
// => planted fraud ring: two DIFFERENT accounts both use the SAME device
CREATE (:Account {name: 'Acc-C'})-[:USES]->(:Device {id: 'dev-99'});
// => an unrelated account on its OWN device -- must NOT show up below
 
MATCH (a:Account)-[:USES]->(d:Device)<-[:USES]-(b:Account)
// => finds every (account, device, account) triple sharing a device, in EITHER direction
WHERE a <> b
// => excludes a device matching against ITSELF -- a real requirement, not decoration
RETURN a.name, b.name, d.id;
// => co-08: only the SHARED-device pair surfaces -- Acc-C's isolated device matches nothing

+---------+---------+-----------+
| a.name  | b.name  | d.id      |
+---------+---------+-----------+
| "Acc-A" | "Acc-B" | "dev-42"  |
+---------+---------+-----------+
1 row

// Example 42: Fraud Cycle Detection. (co-16, co-09)
CREATE (a:Account {name: 'A'})-[:SENT]->(:Account {name: 'B'})-[:SENT]->(:Account {name: 'C'})-[:SENT]->(a);
// => a planted 3-hop CYCLE: A -> B -> C -> A -- money flows back to its own origin
 
MATCH p = (a:Account)-[:SENT*3..5]->(a)
RETURN [n IN nodes(p) | n.name] AS ring;
// => co-09: the pattern's start and end node are the SAME variable "a" -- only a real cycle matches

+---------------------------+
| ring                      |
+---------------------------+
| ["A", "B", "C", "A"]      |
| ["B", "C", "A", "B"]      |
| ["C", "A", "B", "C"]      |
+---------------------------+
3 rows

// Example 43: Identify a Supernode by Degree. (co-17)
// ONE statement, NO semicolon after the first CREATE -- hub must stay bound into the
// UNWIND+CREATE below; a semicolon there would end the statement and hub would be undefined.
CREATE (hub:Person {name: 'Hub'})
// => the eventual supernode -- currently degree 0
WITH hub
UNWIND range(1, 20) AS i
// => generates 20 rows, i = 1 through 20
CREATE (hub)-[:KNOWS]->(:Person {name: 'Leaf' + toString(i)});
// => Hub now has 20 KNOWS edges -- a deliberately synthetic SUPERNODE
CREATE (:Person {name: 'Ordinary'})-[:KNOWS]->(:Person {name: 'Friend'});
// => an ordinary node with degree 1, for contrast
 
MATCH (n)
// => every node in the database, Hub, its 20 leaves, and the ordinary pair
RETURN n.name, COUNT { (n)--() } AS degree
// => undirected degree count, per node
ORDER BY degree DESC
// => highest-degree node sorts first
LIMIT 5;
// => "Hub" comes back FIRST with degree=20 -- every Leaf and the ordinary pair trail far behind

+------------+---------+
| n.name     | degree  |
+------------+---------+
| "Hub"      | 20      |
| "Leaf1"    | 1       |
| "Leaf2"    | 1       |
| "Leaf3"    | 1       |
| "Leaf4"    | 1       |
+------------+---------+
5 rows

# Example 44: Supernode Traversal Cost. (co-17, co-04)
from neo4j import GraphDatabase  # => driver package, `pip install neo4j`
import time  # => stdlib, used only for perf_counter() timing below
 
driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))
# => a live connection -- swap the URI/credentials for your own setup
 
 
def build_fixture(tx) -> None:
    # Builds TWO separate subgraphs: an ordinary degree-1 node and a deliberately extreme
    # degree-50,000 supernode -- the two shapes this example's timing compares.
    tx.run(
        "CREATE CONSTRAINT person_name_unique IF NOT EXISTS "
        "FOR (p:Person) REQUIRE p.name IS UNIQUE"
    )
    # => an index-backed uniqueness constraint on Person.name, created BEFORE any Person node exists
    # -- without it, time_expand's MATCH (p:Person {name: $name}) pays an unindexed label scan across
    # every Person node (50,003 of them once the fixture below finishes), which swamps the
    # degree-driven expand cost this example is trying to isolate
    tx.run("CREATE (:Person {name: 'Ordinary'})-[:KNOWS]->(:Person {name: 'OneFriend'})")
    # => degree-1 node: exactly ONE relationship to expand through
    tx.run(
        # a single Cypher statement, string-built here for readability, run as ONE query
        "CREATE (hub:Person {name: 'Hub'}) "
        "WITH hub UNWIND range(1, 50000) AS i "
        "CREATE (hub)-[:KNOWS]->(:Person {name: 'L' + toString(i)})"
        # => WITH hub carries the alias into UNWIND, exactly like Example 43's fix
    )  # => degree-50,000 SUPERNODE -- deliberately extreme, to make the cost gap visible
 
 
def time_expand(tx, name: str) -> float:
    # Times a full 1-hop expansion out of the named node -- the operation under comparison.
    start = time.perf_counter()  # => wall-clock start, right before the expansion query runs
    tx.run("MATCH (p:Person {name: $name})-[:KNOWS]->(x) RETURN count(x)", name=name).consume()
    # => expands EVERY relationship the named node has -- the operation under comparison
    # => .consume() forces the whole result to be pulled server-side before timing stops
    return time.perf_counter() - start  # => elapsed seconds for exactly this one-hop expansion
 
 
with driver.session() as session:
    session.execute_write(build_fixture)  # => runs the constraint + both CREATE statements above, once
    ordinary_t = session.execute_read(time_expand, "Ordinary")  # => degree-1 expansion
    hub_t = session.execute_read(time_expand, "Hub")  # => degree-50,000 expansion
    print(f"ordinary (degree 1):    {ordinary_t:.4f}s")
    # => prints the small-degree timing for visual comparison
    print(f"hub      (degree 50000): {hub_t:.4f}s")
    # => prints the supernode timing -- see Verify below for what to expect, qualitatively
 
driver.close()
# => releases the driver's connection pool cleanly

# Example 45: Graph Sharding and the Edge Cut. (co-18)
# A small, pure-Python simulation (no live database needed) -- models a naive ID-range shard
# split and counts how many edges end up crossing the shard boundary.
NODES: list[int] = list(range(1, 11))  # => 10 nodes, ids 1 through 10
EDGES: list[tuple[int, int]] = [(1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 7), (7, 8), (8, 9), (9, 10), (10, 1)]
# => a RING: every node connects to its neighbor, and node 10 wraps back to node 1
 
# Naive shard split: nodes 1-5 go to shard A, nodes 6-10 go to shard B -- pure ID-range.
shard_of: dict[int, str] = {n: ("A" if n <= 5 else "B") for n in NODES}
 
crossing = [e for e in EDGES if shard_of[e[0]] != shard_of[e[1]]]
# => an edge "crosses" if its two endpoints land in DIFFERENT shards -- co-18's edge cut
print(f"total edges: {len(EDGES)}")
print(f"crossing edges: {len(crossing)} -> {crossing}")

total edges: 10
crossing edges: 2 -> [(5, 6), (10, 1)]

// Example 46: Gremlin: Add a Vertex and an Edge. (co-25, co-01)
// Run inside the TinkerPop Gremlin Console -- TinkerGraph is a pure in-memory, embedded
// graph engine, so this needs no external server, matching this example's self-containment.
graph = TinkerGraph.open()               // => a fresh in-memory graph, no server required
g = graph.traversal()                    // => the traversal source every step below chains off
 
g.addV('person').property('name', 'Ada').as('a').
  addV('person').property('name', 'Charles').as('c').
  addE('knows').from('a').to('c').iterate()
// => step-chained: TWO vertices created, aliased 'a' and 'c', THEN one edge between them
// => .iterate() actually EXECUTES the traversal -- Gremlin traversals are lazy until iterated
 
g.V().has('person', 'name', 'Ada').out('knows').values('name')
// => follow-up traversal: confirms BOTH the vertices and the edge landed correctly

// Example 47: Gremlin: has() and out(). (co-25, co-08)
graph = TinkerGraph.open()  // => a fresh in-memory graph, no server required
g = graph.traversal()  // => the traversal source every step below chains off
 
g.addV('person').property('name', 'Ada').as('a').
  addV('person').property('name', 'Charles').as('c').
  addE('knows').from('a').to('c').iterate()
// => same fixture shape as Example 46 -- Ada KNOWS Charles
 
g.V().has('person', 'name', 'Ada').out('knows').values('name')
// => has() FILTERS the vertex set down to the ONE starting vertex
// => out('knows') then steps ONE hop forward along that edge label
// => values('name') projects just the name property off the resulting vertex

gremlin> g.V().has('person', 'name', 'Ada').out('knows').values('name')
==>Charles

// Example 48: Gremlin: repeat().path(). (co-25, co-09)
graph = TinkerGraph.open()  // => a fresh in-memory graph, no server required
g = graph.traversal()  // => the traversal source every step below chains off
 
g.addV('person').property('name', 'Ada').as('a').
  addV('person').property('name', 'Bob').as('b').
  addV('person').property('name', 'Cid').as('c').
  addE('knows').from('a').to('b').
  addE('knows').from('b').to('c').iterate()
// => a 2-hop chain: Ada -> Bob -> Cid, identical shape to Example 14's Cypher fixture
// => .iterate() actually EXECUTES the traversal -- Gremlin traversals are lazy until iterated
 
g.V().has('name', 'Ada').repeat(out('knows')).times(2).path().by('name')
// => repeat(out('knows')) is the STEP to repeat -- one knows-hop, per repetition
// => .times(2) bounds the repeat to EXACTLY 2 repetitions
// => .path() returns the full route walked, not just the final vertex
// => .by('name') projects EVERY vertex on the path through its `name` property -- without it,
// .path() emits raw Vertex objects, which TinkerGraph renders as v[<numeric-id>], never as a name

gremlin> g.V().has('name', 'Ada').repeat(out('knows')).times(2).path().by('name')
==>[Ada, Bob, Cid]

// Example 49: Gremlin: valueMap() (LEGACY overload -- flagged deliberately). (co-25)
graph = TinkerGraph.open()
g = graph.traversal()
 
g.addV('person').property('name', 'Ada').property('born', 1815).iterate()
// => one vertex, two properties
 
g.V().hasLabel('person').valueMap(true)
// => valueMap(true) is the LEGACY, deprecated overload -- it still works today, but it is no
// longer the recommended current-TinkerPop way to include vertex id + labels alongside properties.
// Prefer .valueMap().with(WithOptions.tokens) or .elementMap() in new code instead.

g.V().hasLabel('person').elementMap()
// => .elementMap() is the current, non-deprecated way to get id + label + properties together

gremlin> g.V().hasLabel('person').valueMap(true)
==>[id:0, label:person, name:[Ada], born:[1815]]

# Example 50: SPARQL OPTIONAL and FILTER. (co-24)
from rdflib import Graph  # => the RDF graph class this whole script revolves around
 
# Turtle fixture, built as concatenated lines rather than one triple-quoted block, so each
# line can carry its own inline comment -- the same pattern Example 44 uses for Cypher strings.
TURTLE_DATA = (
    "@prefix ex: <http://example.org/> .\n"  # => namespace prefix for our example IRIs
    "@prefix foaf: <http://xmlns.com/foaf/0.1/> .\n"  # => the standard FOAF vocabulary prefix
    'ex:Ada foaf:name "Ada" ; foaf:mbox "ada@example.org" .\n'  # => Ada HAS an email triple
    'ex:Bob foaf:name "Bob" .\n'  # => Bob deliberately has NO mbox -- the asymmetry OPTIONAL tests
)  # => end of the Turtle fixture string
 
g = Graph()  # => an empty in-memory RDF graph
g.parse(data=TURTLE_DATA, format="turtle")  # => loads both people's triples into g
 
query = (
    "PREFIX foaf: <http://xmlns.com/foaf/0.1/>\n"  # => the same namespace, needed again here
    "SELECT ?name ?mbox WHERE {\n"  # => opens the WHERE block -- the pattern to match
    "  ?x foaf:name ?name .\n"  # => REQUIRED triple: every result row must bind a name
    "  OPTIONAL { ?x foaf:mbox ?mbox }\n"  # => OPTIONAL triple: a missing mbox still keeps the row
    '  FILTER regex(?name, "Ada")\n'  # => narrows the results to names matching the regex "Ada"
    "}\n"  # => closes the WHERE block
)  # => end of the SPARQL query string
 
for row in g.query(query):  # => one result row per person surviving the FILTER
    print(row.name, row.mbox)  # => mbox prints as None whenever the OPTIONAL block found nothing

Ada ada@example.org

# Example 51a: "who does Ada know", answered in SPARQL over RDF triples. (co-24, co-02)
from rdflib import Graph  # => the RDF graph class this whole script revolves around
 
g = Graph()  # => an empty in-memory RDF graph
TURTLE_DATA = (
    "@prefix ex: <http://example.org/> .\n"  # => namespace prefix for our example IRIs
    "ex:Ada ex:knows ex:Charles .\n"  # => Ada's first known-fact triple
    "ex:Ada ex:knows ex:Babbage .\n"  # => Ada's second known-fact triple -- same fixture as Example 26
)  # => end of the Turtle fixture string
g.parse(data=TURTLE_DATA, format="turtle")  # => loads both triples above into g
 
SPARQL_QUERY = (
    "PREFIX ex: <http://example.org/> "  # => namespace prefix, needed by the query itself
    "SELECT ?n WHERE { ex:Ada ex:knows ?n }"  # => the OBJECT bound to ?n, for every matching triple
)  # => end of the SPARQL query string
 
for row in g.query(SPARQL_QUERY):  # => one result row per matching triple pattern
    print(row.n)  # => prints each bound URI, one per matching triple

// Example 51b: the SAME question, Cypher over a property graph.
CREATE (a:Person {name: 'Ada'})-[:KNOWS]->(:Person {name: 'Charles'})
// => Ada's first KNOWS edge, a aliased for reuse
CREATE (a)-[:KNOWS]->(:Person {name: 'Babbage'});
// => Ada's second KNOWS edge -- same two-fact fixture as the SPARQL form above
 
MATCH (:Person {name: 'Ada'})-[:KNOWS]->(n:Person)
// => n is bound to a full NODE object, not a triple-pattern object
RETURN n.name;
// => the NODE bound to n, for every matching pattern -- co-02's contrast, made concrete

sparql_form.py -> http://example.org/Charles, http://example.org/Babbage
cypher_form.cypher -> "Charles", "Babbage"

// Example 52: Pin a Query to Cypher 5. (co-21)
CREATE (:Order {id: 1, status: 'shipped'});
 
CYPHER 5 MATCH (n:Order) RETURN n;
// => the CYPHER 5 prefix pins THIS query to the frozen dialect -- bug-fixes only, no new features,
// regardless of whatever the database's own default_language setting happens to be configured to

+--------------------------------+
| n                               |
+--------------------------------+
| (:Order {id: 1, status: "..."}) |
+--------------------------------+
1 row

// Example 53: Pin a Query to Cypher 25. (co-21)
CREATE (:Order {id: 1, status: 'shipped'});
 
CYPHER 25 MATCH (n:Order) RETURN n;
// => same query, same fixture as Example 52, pinned to the EVOLVING Cypher 25 dialect instead --
// identical result here, because this particular pattern uses no dialect-specific feature

+--------------------------------+
| n                               |
+--------------------------------+
| (:Order {id: 1, status: "..."}) |
+--------------------------------+
1 row

// Example 54a: city as a plain PROPERTY -- cannot carry its own attributes.
CREATE (:Person {name: 'Ada', city: 'Berlin'});
// => "Berlin" is just a string -- there is nowhere to attach a population or a timezone to it

// Example 54b: city refactored into its OWN node + relationship. (co-11)
CREATE (:Person {name: 'Ada'})-[:LIVES_IN]->(:City {name: 'Berlin', population: 3700000});
// => city now HAS its own attributes (population) -- impossible when it was a scalar property
 
MATCH (p:Person)-[:LIVES_IN]->(c:City)
WHERE c.population > 1000000
RETURN p.name, c.name;
// => a query against CITY's own attributes now works -- it could not before the refactor

before.cypher -> city stored, but c.population is not expressible at all
after.cypher  -> ("Ada", "Berlin")   -- the population-based query now succeeds