Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 30 ยท Projects

Project: a knowledge graph

Build a small knowledge graph: entities, typed relationships, a CSV import with LOAD CSV and MERGE, and path queries that explain how things connect.

A knowledge graph stores facts as a network: things (entities) and the typed links between them. "Linus Torvalds created Linux", "Linux is written in C", "Dennis Ritchie created C". Each fact is a small triple of subject, relationship and object, and a graph database lets you chain those triples to answer questions nobody asked when the data was loaded. "How is Linus Torvalds connected to Dennis Ritchie?" is answered by finding a path, not by writing a join.

In this project you model a small knowledge graph about software and the people behind it, load it from two CSV files, and query it with paths. Neo4j cannot run on this site, so the Cypher is read-only. Python stand-ins load the same CSV text into dictionaries and implement MERGE-style loading and path search, so you can run the logic and see real output. They are stand-ins for the ideas, not Neo4j itself.

Step 1: choose the entities and relationships

Start from the questions the graph should help answer:

  • Who created a piece of technology, and where was it written or used?
  • What is written in what, and what influenced what?
  • How are two entities connected, and through which facts?

From those questions, pick a small set of labels and relationship types. Keep the vocabulary tight; a knowledge graph with 200 vaguely named relationship types is hard to query.

Label Examples
Person Linus Torvalds, Dennis Ritchie
Org Facebook, Amazon, Google
Tech Linux, C, Cassandra, Java
Relationship Meaning Direction
CREATED made or co-made Person or Org to Tech
WRITTEN_IN implementation language Tech to Tech
INFLUENCED design influence Tech to Tech, older to newer
BUILT_AT where it was first built Tech to Org
flowchart LR
    Linus["Linus Torvalds"] -->|CREATED| Linux
    Linux -->|WRITTEN_IN| C
    Dennis["Dennis Ritchie"] -->|CREATED| C
    Dennis -->|CREATED| Unix
    Unix -->|INFLUENCED| Linux
    Linus -->|CREATED| Git
    Git -->|WRITTEN_IN| C

A slice of the knowledge graph: facts about Linux, C and Unix become labelled arrows.

Step 2: the data as two CSV files

A common way to load a graph is one CSV for the nodes and one for the relationships. These are the files this project uses (a small, hand-checked set of public facts):

Text
nodes.csv
id,label,name
p1,Person,Linus Torvalds
p2,Person,Dennis Ritchie
p3,Person,Ken Thompson
p4,Person,Avinash Lakshman
p5,Person,Emil Eifrem
o1,Org,Facebook
o2,Org,Amazon
o3,Org,Google
t1,Tech,Linux
t2,Tech,Unix
t3,Tech,C
t4,Tech,Git
t5,Tech,Cassandra
t6,Tech,Java
t7,Tech,Neo4j
t8,Tech,Dynamo
t9,Tech,Bigtable
Text
edges.csv
from,type,to
p1,CREATED,t1
p1,CREATED,t4
p2,CREATED,t3
p2,CREATED,t2
p3,CREATED,t2
p4,CREATED,t5
p5,CREATED,t7
t1,WRITTEN_IN,t3
t4,WRITTEN_IN,t3
t2,WRITTEN_IN,t3
t5,WRITTEN_IN,t6
t7,WRITTEN_IN,t6
t2,INFLUENCED,t1
t8,INFLUENCED,t5
t9,INFLUENCED,t5
t5,BUILT_AT,o1
t8,BUILT_AT,o2
t9,BUILT_AT,o3

Putting a stable id in the data matters. It gives MERGE something to match on, and it lets you load the file twice without creating duplicates.

Step 3: import with LOAD CSV

In Neo4j, LOAD CSV reads a file row by row. First you create a uniqueness constraint for the identifier of each label (you met constraints in Cypher: MERGE, SET, DELETE and constraints); it also creates the index that makes MERGE fast. The statements below are read-only here and assume the files are in the server's import folder.

CYPHER
CREATE CONSTRAINT person_id IF NOT EXISTS FOR (n:Person) REQUIRE n.id IS UNIQUE;
CREATE CONSTRAINT org_id    IF NOT EXISTS FOR (n:Org)    REQUIRE n.id IS UNIQUE;
CREATE CONSTRAINT tech_id   IF NOT EXISTS FOR (n:Tech)   REQUIRE n.id IS UNIQUE;

// nodes: one pass per label, because a label cannot be a parameter
LOAD CSV WITH HEADERS FROM 'file:///nodes.csv' AS row
WITH row WHERE row.label = 'Person'
MERGE (n:Person {id: row.id})
  SET n.name = row.name;
// ...repeat for Org and Tech

// relationships: one pass per type, matching both ends first
LOAD CSV WITH HEADERS FROM 'file:///edges.csv' AS row
WITH row WHERE row.type = 'CREATED'
MATCH (a {id: row.from}), (b {id: row.to})
MERGE (a)-[:CREATED]->(b);
// ...repeat for WRITTEN_IN, INFLUENCED and BUILT_AT

Two details are worth remembering. A relationship type cannot come from a variable in plain Cypher, which is why the loader repeats a block per type (the APOC plugin can create relationships with a dynamic type, if you have it). And MERGE (a)-[:CREATED]->(b) is idempotent: running the import again leaves the graph unchanged. That is what you want for a pipeline that is re-run when the files change.

For very large files, wrap the load in CALL { ... } IN TRANSACTIONS OF 10000 ROWS so memory stays bounded. Check the manual for your Neo4j release for the exact form.

Stand-in 1: loading CSV with MERGE semantics

The stand-in below reads the same two CSV texts with Python's csv module and builds an in-memory graph. The functions merge_node and merge_edge do what MERGE does: create if missing, otherwise leave alone. The program loads the files twice to prove that the second load changes nothing.

Python LOAD CSV and MERGE, as a Python stand-in

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second load creates nothing, which is exactly the property you rely on when a nightly job re-imports an updated file. The two summary lines at the end are the equivalent of the sanity checks you should always run after an import: MATCH (n) RETURN labels(n), count(*) and MATCH ()-[r]->() RETURN type(r), count(*).

Step 4: path queries

Now the graph earns its keep. Questions about connection are variable-length path patterns, which you learned in Paths, aggregation and WITH.

CYPHER
// the shortest chain of facts between two people, ignoring direction
MATCH p = shortestPath(
  (a:Person {name: 'Linus Torvalds'})-[*..6]-(b:Person {name: 'Dennis Ritchie'})
)
RETURN [n IN nodes(p) | n.name] AS chain,
       [r IN relationships(p) | type(r)] AS facts;

// everything built from the same language as Cassandra
MATCH (c:Tech {name: 'Cassandra'})-[:WRITTEN_IN]->(lang)<-[:WRITTEN_IN]-(other:Tech)
WHERE other <> c
RETURN lang.name, other.name;

// the influence lineage of Linux, following INFLUENCED backwards
MATCH (src:Tech)-[:INFLUENCED*1..4]->(:Tech {name: 'Linux'})
RETURN src.name;

The first pattern leaves out the arrow direction, because for a connection question you want to walk a relationship either way. The second finds technologies that share a language with Cassandra through one shared node. The third walks one relationship type backwards through several hops.

Stand-in 2: shortest paths that explain themselves

The next stand-in does a breadth-first search that ignores direction and reports each step with its relationship, and that is the useful part of a knowledge graph: the answer comes with its evidence. It reuses the same data, shortened here to the fields it needs.

Python Shortest path with the facts along the way

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Each answer is a readable chain, such as a creator, the thing they created, the thing that thing was written in, and back to another creator. The last query returns no path because, in this small data set, nothing links the Neo4j and Linux communities within the hop limit: knowing a path does not exist is also an answer, and it depends entirely on how complete the data is. A knowledge graph is only as connected as the facts you put in.

Step 5: keep it healthy

  • Provenance. Add a source and a retrieved property to relationships (or model a Source node). Without them you cannot tell which fact to trust when two disagree.
  • Normalize names. Use ids for identity; keep names as display properties. Two nodes named "Java" (the language and the island) must not merge.
  • Direction with meaning. INFLUENCED points from older to newer. If half the data points the other way, path queries lie.
  • Constrain early. Uniqueness constraints on every id catch duplicate loads before they spread.
  • Watch supernodes. A node such as C with thousands of incoming WRITTEN_IN relationships makes some traversals slow. Modeling guidance for that follows in Graph data modeling.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the CSV loader use MERGE instead of CREATE?

    MERGE matches an existing node or relationship and creates it only if absent, so a second load does not make duplicates.
  2. 2. What is the purpose of a uniqueness constraint on a node id?

    A uniqueness constraint rejects duplicates and is backed by an index, which also makes MERGE on that property fast.
  3. 3. In the pattern (a)-[*..6]-(b), why is no arrowhead written?

    Leaving out the arrow matches the relationship in both directions, so the path can wander along the facts regardless of how each was stored.
  4. 4. A path search returns nothing between two entities. What does that tell you?

    A graph only knows the facts loaded into it. No path means no stored connection within the limit.

Summary

  • A knowledge graph stores facts as labelled nodes and typed, directed relationships.
  • Design the vocabulary from your questions, and keep the number of labels and relationship types small.
  • Load nodes and relationships from CSV with LOAD CSV, MERGE and uniqueness constraints so the import is repeatable.
  • shortestPath and variable-length patterns answer connection questions, and the path itself is the evidence.
  • Add provenance, stable ids and meaningful direction to keep the graph trustworthy as it grows.

Next: Practice exercises with solutions.