Along the way I moved into a job where writing and communicating is the work, and it turns out that when you write for a living you have a finite amount of writing in you. Every post I might have put here went to the organisation paying me instead. That’s a reasonable trade while it lasts, but eight years of it left me with a blog full of Raspberry Pi and Minecraft projects and nothing after 2018.

That’s what it looked like. Blogger, a theme I’d picked in about 2012, and 136 posts slowly rotting — images hotlinked from other people’s servers that had since disappeared, goo.gl short links pointing at a service Google has since switched off, and code blocks that had lost their indentation somewhere in Blogger’s editor years ago.

What I actually wanted

Two things.

Somewhere to put my own ideas again, obviously. But also somewhere I control, that I can cross-post to. A lot of what I write now lives on someone else’s platform, and platforms go away — I’ve just spent a fortnight proving that by chasing down dead links from 2012. If I publish something elsewhere I want a copy here with a canonical link pointing back to the original, so the search engines credit the right place and I still have it in ten years when the original has 404’d.

Longevity, basically. Plain Markdown files in a git repo will outlive any CMS I could pick.

The drudge work

Migrating 136 posts off Blogger is not interesting work. It is:

• exporting from Google Takeout and working out that the format changed in 2018, so the standard jekyll-import tool doesn’t read it any more
• converting HTML-with-inline-styles into clean Markdown
• rescuing code blocks from <span style="font-family: Courier New"> soup, with the indentation intact, because these are Python posts and indentation is the program
• pulling 208 images off Google’s servers before they vanish too
• writing a redirect for every single old URL, because there are fourteen years of inbound links out there

That’s a week of tedium, and it’s exactly the kind of thing a coding agent is good at. So I used one — Claude Code — and spent my time on the parts that actually needed me: what the thing should look like, what to keep, what to throw away, and whether the output was any good.

Keeping myself in the loop

The way I work with a coding agent is that I stay in the process. Not “generate a website” and hope — review every phase, and be the one who decides. A few examples from this migration, including the ones where I was the reason it worked.

The brief was wrong and the agent said so. I’d written “203 posts” in the plan. The export had 136. Rather than quietly building 136 and moving on, it cross-checked the label counts against the design spec — raspberry-pi 95, python 77, minecraft 43 — found they matched the export exactly, and told me the 203 figure couldn’t be right. It was my mistake, from a stale note.

I caught the thing the tests couldn’t. After the theme went in, 124 automated checks passed. I opened the page and it looked nothing like the design — completely unstyled. The stylesheet was being served as an HTML document, because Jekyll had wrapped it in a page layout. It returned HTTP 200 at the right URL with a plausible file size, so every automated check was happy. The checks were reading the source file, not the built one. It took me two seconds to see and it would have shipped otherwise.

I vetoed a fix that was correct but wrong. Images broke on the staging URL, and the agent fixed it by rewriting every image reference in all 92 affected posts:

![]({{ '/assets/img/2012/04/responsivedesign-mobile.png' | relative_url }})

That works. It’s also a permanent tax on writing every future post, to solve a problem that only exists on a temporary URL. I said no, and it moved the fix into the build step instead. Posts stayed as plain Markdown.

And the loop runs both ways. Three posts had genuinely broken indentation — not from the migration, broken in the original since 2013. The agent normalised what it could prove and refused those three, because Python itself couldn’t work out the nesting. I fixed them by hand. It re-checked, and found my fix had flattened two other blocks I hadn’t noticed. Three rounds before it was clean. I’d have shipped mine.

None of that is the agent being clever or me being clever. It’s just that the failure modes are different, so between us we caught things neither would alone.

Open source

The last benefit: the whole site is now public at github.com/martinohanlon/stuffaboutcode.

Every post is a Markdown file. The theme is one stylesheet and about 200 lines of vanilla JavaScript — no framework, no npm. Push to the repo and GitHub Actions builds and deploys it. If you want to see how something here is done, you can just go and look, which feels right for a blog that has always been about showing people how things work.

Same question, same data, different retrieval. I built a small demo to make that difference impossible to miss, and it runs on exactly the concepts and dataset you work through in Neo4j & GenAI Fundamentals.

What RAG and GraphRAG actually do

Retrieval-augmented generation (RAG) gives a large language model the context it needs to answer a question. Instead of relying on what the model memorised during training, you retrieve relevant data and pass it in alongside the question.

The most common form is vector RAG. You embed your text as vectors, store them, and at query time find the chunks that are semantically closest to the question. It is good at “find me something that reads like this”.

GraphRAG adds the missing dimension: relationships. A vector search can tell you a film’s plot is similar to your query, but it cannot tell you the film’s genre, its cast, or its average rating unless that text happens to sit in the same chunk. A graph can. GraphRAG takes the results of a vector search and traverses the graph to pull in connected facts, so the model answers with structure, not just similarity.

The recommendations dataset

The demo runs on Neo4j’s public dataset, the same one used throughout the course. It models movies, people connected to them, and a lot of ratings.

A Movie is IN_GENRE of one or more genres, a Person ACTED_IN or DIRECTED it, and a USER RATED it. Each movie also carries a plot summary, which is embedded as a 1536-dimension vector and stored in a vector index called moviePlots.

That single graph holds everything both retrievers need. Vector RAG uses only the plot embeddings. GraphRAG uses the embeddings and the relationships around them.

Seeing the difference

The RAG vs GraphRAG demo is a terminal application that sends your question to two agents at once and shows their answers side by side.

• The RAG agent uses a VectorRetriever. It finds the movies whose plot embeddings are nearest to your query and passes those plots to the LLM.
• The GraphRAG agent uses a VectorCypherRetriever. It starts from the same vector hits, then runs a Cypher query to enrich them with genres, cast, directors, and user ratings before the LLM ever sees them.

Both retrievers are built with the neo4j-graphrag Python package, so the only meaningful difference between them is how much of the graph they retrieve. Ask for the highest-rated action film about other planets, and plain vector RAG returns something plot-similar. GraphRAG returns something plot-similar that is also an action film with a genuinely high average rating, because it retrieved the ratings and genres to reason over.

Run it yourself

The installation instructions are on GitHub. The demo connects to the public dataset out of the box, so all you need is Python and an OpenAI API key to try it on your own questions.

Learn to build it yourself

The concepts underneath the demo — embeddings, vector indexes, retrievers, and graph-enhanced retrieval, are what make it work, and they are exactly what Neo4j & GenAI Fundamentals teaches. You will build the same VectorRetriever and VectorCypherRetriever against this dataset, write the retrieval Cypher yourself, and see the context change as you do.

Neo4j & GenerativeAI Fundamentals — Learn how Neo4j and GraphRAG can support your Generative AI projects

If the side-by-side answers made you curious about why the graph wins, the course is where you find out how to build it.

Originally published on Neo4j GraphAcademy on 22 July 2026.

Here is how that works under the hood.

A database created just for you

When you enter a hands-on course, GraphAcademy provisions a Neo4j instance on Aura, Neo4j’s fully managed cloud service. It is created through the Aura management API, and it belongs to you alone. It is your instance, with your own connection URI, username, and password, and you can connect to it from the browser, from Neo4j Browser, or from your own code.

You never see a billing page or a provisioning wizard. You open a lesson, and a running database is waiting for you.

Every instance starts empty

A freshly provisioned Aura instance is blank. No nodes, no relationships, no schema. How it is populated depends entirely on what the course is teaching.

From that blank slate, data arrives in one of two ways.

Two ways the data arrives

Some courses prepare the data for each lesson. A lesson can carry a reset script that puts the database into the exact state it needs before you begin, so you always start from a known point regardless of what the previous lesson left behind. Neo4j Fundamentals works this way: it starts you on a small movie graph, and its querying lessons read, match, and modify that graph, resetting to a clean baseline as you move between them.

Other courses come pre-loaded with a use-case dataset. When a course needs a realistic graph to explore, we seed one for you the moment your instance is created. Our application development courses, for example, all start against the same movie recommendations dataset, so you can write meaningful queries against real relationships from the very first lesson instead of importing data.

The seed runs once, automatically, in the background. When you first join a course, you may see a message that your instance is being prepared.

It pauses and cleans up after itself

Instances do not run forever. When you stop using one, Aura automatically pauses it after a period of inactivity. When you come back and open the next lesson, GraphAcademy detects the paused instance and resumes it for you.

Each instance also has a fixed lifetime and once an instance expires it is terminated and its resources are released. Come back to a course after a long break and you simply get a fresh one.

GraphAcademy runs on Neo4j too

There is a nice symmetry here: the GraphAcademy platform that hands you a Neo4j database is itself built on Neo4j.

Your instances are not tracked in a separate table off to the side. They live in the same graph that models you as a learner. When GraphAcademy provisions a database, it writes an Instance node and connects it to your User node with a HAS_INSTANCE relationship:

The Instance node stores everything the platform needs to manage it: the use-case it holds, its connection details, its seeding status, and its expiry date. Because it is a graph, operational questions become traversals rather than joins across tables. Finding every instance due to expire is a single query from the Instance nodes.

Try it yourself

The fastest way to understand any of this is to start a course and watch your own instance come to life. Neo4j Fundamentals is a good place to begin: it walks you through graph thinking and gives you a live database to experiment in from the start.

Originally published on Neo4j GraphAcademy on 3 July 2026.

Fine tuned to deliver solutions, they lack good context relating to how to teach complex subjects, often missing key points, providing inconsistent results, and don’t build confidence.

[Human]
Create a function which connects to my Neo4j databases and runs a 
Cypher statement.

[AI] 
Sure, here is a new function, run_cypher(driver, database, cypher).

[Human]
How does this work?

[AI]
It runs a cypher statement using the neo4j.GraphDatabase driver 
instance and database name and returns a list of Record objects.

[Human]
But how does it actually work? What are the concepts I need to know? 
How do I do this myself?

I wanted to change this and provide coding agents (VS Code, Cursor, etc) with access to Neo4j’s GraphAcademy content and teaching approaches.

GraphAcademy is Neo4j’s free online training platform and provides learners with knowledge and skills to use Neo4j to solve real world problems, including a new course on Building Agents on Neo4j Aura.

The plan

1. Create a Neo4j graph database on Aura of GraphAcademy lessons.
2. Build an Aura agent with tools to search, retrieve, and format lessons.
3. Expose the agent as an MCP server that can connect to an agent.

The graph database

GraphAcademy’s lesson content is open source and written in Asciidoc.

I used asciidoctor-reducer to turn the lessons into single files containing all the text, code, examples, and questions by injecting attributes and resolving any includes.

Each lesson was chunked into sections, embeddings were created using OpenAI’s text-embedding-3-small model, and stored in Neo4j Aura with associated meta data about the lesson (course structure, slugs, names, urls, etc).

With the data in Neo4j I could search to find complete lessons based on something I want to learn (a $subject) e.g. Teach me about filtering with Cypher WHERE clauses.

WITH ai.text.embed(
  $subject, 
  'OpenAI', 
  { token: $token, model: 'text-embedding-3-small' }
) AS userEmbedding

MATCH (c:Chunk)
SEARCH c IN (
  VECTOR INDEX chunkText
  FOR userEmbedding
  LIMIT $k
) SCORE AS score
WHERE score > 0.7

MATCH (c)<-[:HAS_CHUNK]-(l:Lesson)

RETURN 
  l.slug as slug, 
  l.title as title, 
  l.url as url, 
  l.text as lesson, 
  avg(score) as score

ORDER BY score DESC

The Cypher query:

1. Creates an embedding of the $subject using the same OpenAI text-embedding-3-small model that was used to create embeddings of the lesson chunks.
2. Searches the chunkText vector index and return chunks that have a similarity score > 0.7.
3. Matches the lessons for the chunks.
4. Returns the lesson data, aggregating by the average score of the lesson chunks found. Averaging the score ensures single high scoring chunks don’t result in the query returning less relevant lessons as the top match.

Aura Agent

Aura Agents allow you to create a fully functional GraphRAG agent connected to your Neo4j Aura database.

I used an Aura agent to provide the entry point to the lessons and generate responses to queries and questions.

Aura Agents require:

• a name — to indicate what the agents does.
• a prompt — that describes the agent’s purpose, approach, and instructions.
• a set of tools — to retrieve data from Neo4j as context to the questions.

The prompt instructs the agent to present the GraphAcademy lessons as a learning experience, including ensuring there is an objective, that misconceptions are challenged, and options given for next steps.

Find and present Neo4j GraphAcademy lessons and appropriate progression 
to the follow on topics.

Provide lessons that:

- are standalone and meet a learning objective
- include examples and code snippets where relevant
- show outcomes and results of actions
- where there are potential misconceptions pose questions 
  and answers that challenge them
- have recommendations for next steps.
- provide a link to the full lesson to learn more.
- give options to either: continue to the next lesson, explore 
  related topics, or get more information.

Use the tool "get lesson for a chunk" after "search lesson chunks".

The agent accesses the lesson data through its tools. The tools are chosen by the agent based on the task. The agent will use as many of the tools as required to complete the task.

The agent only needs access to a relatively smaller number of tools which search and retrieve the lesson:

• search for a lesson — semantic search for lesson chunks
• get a complete lesson — gets a complete lesson
• get next lesson — gets the next lesson in the sequence

Using the smallest number of tools to provide access to the data often results in better outcomes and tool use.

The agent will use the tools to find and present teaching content about Neo4j.

When given a query such as “How to use WITH in Cypher”, the agent will search for a lesson, get the complete lesson for the chunk returned, and provide a lesson.

The lessons are already structured for the purpose and the prompt is enough for the agent to provide good responses.

The agent will provide follow on tasks and allow the user to progress through to the next lesson in the course.

MCP Server

It’s important we meet developers were they are and to do that I need to provide external access to my agent.

An Aura agent can be accessed externally via a HTTPS endpoint or as an MCP server.

Agent applications (VS Code, Cursor, etc) typically have the ability to interact with MCP servers to complete tasks.

You can add your Aura agent as an MCP server to you agent application allowing it to use the responses your Aura agent as context to your queries.

When asking the VS Code agent to “Teach me how to run a Cypher statement using the Neo4j Python driver”, the agent will find lessons from GraphAcademy and create responses using the lessons content and structure.

[HUMAN]
Teach me how to run a Cypher statement using the Neo4j Python driver

[AI]
I’ll quickly pull the official Neo4j learning guidance first, then I’ll give 
you a concise, practical Python example you can run immediately.

[TOOL]
Ran Neo4j Learning
Input:
{
  "query": "How to run a Cypher statement using the Neo4j Python driver
}
Output:
Here's a lesson on how to run a Cypher statement using the Neo4j Python driver,
including connection setup and query execution.
...continued...

[AI]
Great use case. Here is the simplest way to run a Cypher statement with the 
Neo4j Python driver.

1. Install the driver
pip install neo4j

2. Use this minimal script:

from neo4j import GraphDatabase

URI = "neo4j+s://<your-instance-id>.databases.neo4j.io"
USER = "neo4j"
PASSWORD = "<your-password>"

def run_query():
    # Create a driver (connection factory)
    driver = GraphDatabase.driver(URI, auth=(USER, PASSWORD))

    try:
        # execute_query is the easiest API in driver v5+
        records, summary, keys = driver.execute_query(
            "RETURN 'Hello, Neo4j!' AS message"
        )

        for record in records:
            print(record["message"])

        print("Query ran successfully.")
        print("Database:", summary.database)
    finally:
        driver.close()

if __name__ == "__main__":
    run_query()

3. Run it
python your_script.py

Parameterized Cypher example (recommended):

records, summary, keys = driver.execute_query(
    "RETURN $name AS name",
    name="Martin"
)
print(records[0]["name"])

Why this matters:

1. Use parameters like $name instead of string concatenation for safety 
   and performance.
2. For Neo4j Aura, use neo4j+s in the URI.
3. Close the driver when done.

If you want, I can also give you:

1. A read/write transaction example with session.execute_read and 
   session.execute_write.
2. A small reusable Neo4j client class you can drop into your project.

The response from the agent is structured as a lesson, includes good progression from a simple example, adding features, explaining the approaches used, and giving options to continue learning.

All the code and resources are in the repository github.com/martinohanlon/ga-mcp-poc.

Next steps

This proof-of-concept is just the beginning, an MCP server is part of our ongoing development of GraphAcademy. We are keen to meet developers where they are, and some of them are in code development environments.

You can learn the skills to create your own graph, MCP server, and Aura agent in the GraphAcademy courses Introduction to Vector Indexes and Unstructured Data, Building GraphRAG Python MCP tools, and Building Agents in Neo4j Aura.

Originally published on Neo4j on 21 April 2026.

Creating knowledge graphs from unstructured data can be complex, involving multiple steps of data query, cleansing, and transforms. You can use the text analysis capabilities of LLMs to help automate knowledge graph creation.

The Neo4j GraphRAG for Python (neo4j_graphrag) package includes a Knowledge Graph Builder to help you convert your unstructured and structured data.

Knowledge Graph Builder

The SimpleKGPipeline class provides a pipeline that implements a series of steps to create a knowledge graph from unstructured data:

1. Load the text
2. Split the text into chunks
3. Create embeddings for each chunk
4. Extract entities from the chunks using an LLM
5. Write the data to a Neo4j database

For example, you could turn the Neo4j Wikipedia page into a graph representing Neo4j the organization and the database.

The SimpleKGPipeline only requires a Neo4j connection, an embedding model, and an LLM to turn your documents into a knowledge graph.

import os
from dotenv import load_dotenv
load_dotenv()

import asyncio

from neo4j import GraphDatabase
from neo4j_graphrag.llm import OpenAILLM
from neo4j_graphrag.embeddings import OpenAIEmbeddings
from neo4j_graphrag.experimental.pipeline.kg_builder import SimpleKGPipeline

neo4j_driver = GraphDatabase.driver(
    os.getenv("NEO4J_URI"),
    auth=(os.getenv("NEO4J_USERNAME"), os.getenv("NEO4J_PASSWORD"))
)
neo4j_driver.verify_connectivity()

llm = OpenAILLM(
    model_name="gpt-4o",
    model_params={
        "temperature": 0,
        "response_format": {"type": "json_object"},
    }
)

embedder = OpenAIEmbeddings(
    model="text-embedding-ada-002"
)

kg_builder = SimpleKGPipeline(
    llm=llm,
    driver=neo4j_driver,
    neo4j_database=os.getenv("NEO4J_DATABASE"),
    embedder=embedder,
    from_pdf=True,
)

pdf_file = ".my_document.pdf"
result = asyncio.run(kg_builder.run_async(file_path=pdf_file))
print(result.result)

You can learn how to use and customize the SimpleKGPipeline in a new GraphAcademy course: Constructing Knowledge Graphs with Neo4j GraphRAG for Python.

You’ll also learn how to:

• Create text splitters and define chunks
• Implement custom data loaders
• Define a schema for your lexical (unstructured) graph to ensure that you’re extracting the data you need
• Add structured data alongside your unstructured data
• Create GraphRAG pipelines and retrievers to access your knowledge graph

Summary

Knowledge graphs help you organize and make sense of your data. Learn how to create them in the GraphAcademy Constructing Knowledge Graphs with Neo4j GraphRAG for Python course.

Originally published on Neo4j Developer Blog on 3 December 2025.

There’s a new GraphAcademy course called Using Neo4j with Java, where you can learn how to integrate the Neo4j Java driver into your Java application.

The most common thing you will need to do when using Neo4j with Java is run a Cypher query and parse the results. The process is really simple:

1. Import the driver
2. Connect to a server
3. Verify the connection
4. Execute a Cypher query
5. Parse the results
6. Close the connection

Import the Driver

The driver is distributed via Maven, you can find snippets and example POM files on the Maven Central Repository — neo4j-java-driver package.

You’ll need to import the GraphDatabase and AuthTokens classes from the Neo4j driver package:

import org.neo4j.driver.GraphDatabase;
import org.neo4j.driver.AuthTokens;

public class App {
    public static void main(String[] args) {
        String NEO4J_URI = "bolt://localhost:7687";
        String NEO4J_USERNAME = "neo4j";
        String NEO4J_PASSWORD = "mypassword";

        // Create a new Neo4j driver instance

        // Verify the connection 

        // Execute a Cypher query

        // Parse the results

        // Close the connection

    }
}

Connect to a Server

Create an instance of the GraphDatabase.driver class, passing your credentials:

        // Create a new Neo4j driver instance
        var driver = GraphDatabase.driver(
                NEO4J_URI,
                AuthTokens.basic(
                    NEO4J_USERNAME,
                    NEO4J_PASSWORD)
            );

Verify the Connection

You can test the connection by calling the verifyConnectivity method:

        // Verify the connection 
        driver.verifyConnectivity();

The driver will raise an exception if the connection cannot be made.

Execute a Cypher Query

The executableQuery method executes a Cypher query and returns the results:

        // Execute a Cypher query
        var result = driver.executableQuery(
            "MATCH (c:Customer) RETURN c.name AS name, c.age AS age"
            ).execute();

Parse the Results

The execute method fetches a list of records and loads them into memory:

        // Parse the results
        var records = result.records();
        records.forEach(r -> {
            System.out.println(r.get("name"));
            System.out.println(r.get("age"));
        });

You can iterate through the records and use get to retrieve return values.

Close the Connection

Once you finish with the driver, call close to release any resources:

        // Close the connection
        driver.close();

Here’s the complete code that makes a connection, executes a query, and parses the results:

import org.neo4j.driver.GraphDatabase;
import org.neo4j.driver.AuthTokens;

public class App {
    public static void main(String[] args) {
        String NEO4J_URI = "bolt://localhost:7687";
        String NEO4J_USERNAME = "neo4j";
        String NEO4J_PASSWORD = "mypassword";

        // Create a new Neo4j driver instance
        var driver = GraphDatabase.driver(
                NEO4J_URI,
                AuthTokens.basic(
                    NEO4J_USERNAME,
                    NEO4J_PASSWORD)
            );

        // Verify the connection 
        driver.verifyConnectivity();

        // Execute a Cypher query
        var result = driver.executableQuery(
            "MATCH (c:Customer) RETURN c.name AS name, c.age AS age"
            ).execute();

        // Parse the results
        var records = result.records();
        records.forEach(r -> {
            System.out.println(r.get("name"));
            System.out.println(r.get("age"));
        });

        // Close the connection
        driver.close();

    }
}

Learn More

You can learn more about how to use the Neo4j Java driver in the Using Neo4j with Java course on GraphAcademy.

The course will get you started developing Java applications with Neo4j and covers topics such as passing parameters to queries, dealing with graph data types, and managing transactions.

Originally published on the Neo4j Developer Blog on 13 May 2025.

My role is centered around developing Neo4j educational resources to support developers. I have a strong background in computer science education. My previous role was creating online learning experiences for the Raspberry Pi Foundation, and although I worked in software development and architecture for many years, my knowledge of Neo4j was limited.

Therefore, one of my first priorities was to educate myself in Neo4j.

Learning something new is hard! Multiple factors affect how hard it is, such as the resources available to you, your experience, knowledge and skills, and your own motivation. Applying a structure to your learning can help you achieve your objective.

Come with me on an exploration of how I structured my learning using Neo4j’s developer relations output and educational content.

Make Your Learning Effective

Most people have an understanding of how they like to obtain knowledge and learn new skills. You may not be able to articulate how you like to learn, but you will be aware of the ways of learning that excite you or bore you!

Do you relish the opportunity to sit down with a text book or fear and loath it?

I personally thrive when given a variety of learning opportunities and particularly when it’s accessible in short pieces with time to practice and get hands-on.

Neo4j’s investment in developer support and education resources is impressive, and there are plenty of resources and opportunities to learn and acquire new skills.

Create a Goal

To structure and support my learning, I set myself these initial learning objectives:

1. Understand the benefits and use cases of graphs and graph databases
2. Be able to design a graph data model to fulfill a typical use case
3. Understand the options for loading data into a Neo4j database
4. Use Cypher to load, query, and manipulate data in a graph database
5. Use simple Graph Data Science tools and techniques to answer questions
6. Interact with a Neo4j database using Python

To make my learning effective, I also wanted to create my own project. A project excites me, it allows me to structure my learning so I get the opportunity to get hands-on, and it motivates me to continue.

From my initial understanding of graphs and Neo4j, I had an idea about mapping the physical world, understanding the relationship between places and how you move between them.

I have snowboarded for over 30 years, and I love nothing more than exploring the mountains. Large ski resorts are a complex system of interconnected trails and lifts.

I planned to use a Neo4j graph database to allow me to answer the following questions:

• What lifts and trails are there?
• What trails have a specified difficulty?
• What trails are accessible from a specific lift?
• Is there an accessible route between 2 points?
• What is the shortest path between 2 points?

A Learning Pathway

To help me achieve my goals, I created a learning pathway:

1. Fundamentals — Understanding Neo4j and graphs
2. Data modeling — How to structure data in a graph
3. Importing data — The options and processes for moving data into Neo4j
4. Query and analysis — Answering questions and running queries
5. Programming and integration — Integrating a graph database into an application

The Beginners collection of courses on Neo4j’s GraphAcademy is an example of a learning pathway that supports you in obtaining the skills and knowledge required to complete the Neo4j Certified Professional certification.

The beginner courses were my starting point for obtaining fundamental knowledge and skills.

Fundamentals

I started my learning with the Neo4j Fundamentals and Cypher Fundamentals courses on GraphAcademy. These courses introduce graph theory, the Neo4j graph database, and the Cypher query language. These courses gave me the initial knowledge and skills needed to interact with Neo4j and understand the key use cases.

I wanted to increase my knowledge of the graph database sector, so I also started reading the complementary ebook Graph Databases by Ian Robinson, Jim Webber, and Emil Eifrem.

Once I had secured my fundamental knowledge of Neo4j, I looked for sources of ski resort data for my project. I discovered that trails and lifts were included in OpenStreetMap (OSM).

I wrote an Overpass Turbo query to export the lift (aerialway) and trail (piste) data in JSON.

[out:json][timeout:25];
area[name="Val Thorens"]->.a;
(  
  way["piste:type"](area.a);  
  way["aerialway"](area.a);  
);
out body;
>;
out skel qt;

My plan was to use Overpass Turbo to export the data from OSM, create a Python program to convert it to CSV, and load it into Neo4j. I envisaged a graph of trail, lift, and position nodes using relationships to store how you would progress from one place to the next.

Data Modeling

To understand graph data modeling and the potential for graph databases, I completed the Graph Data Modeling Fundamentals course, which explores how to design a Neo4j graph and best practices.

I learned about storing geospatial data in Neo4j from the Geospatial Data in your Graph livestream on Neo4j’s Twitch channel.

Neo4j Developer Advocate William Lyon has created a useful Spatial Cypher Cheat Sheet about managing geospatial data using Cypher.

The Twitch channel often has presenters from the Neo4j community and has helped me to expand my knowledge of the use of Neo4j and graph databases. The stream on GraphTFT — a team builder app for Teamfight tactics is a great example of how Neo4j can be used to understand relationships.

I developed a data model for my project, which incorporated what I have learned about graph databases, Neo4j, and the ski resort data I exported from OpenStreetMap.

Importing Data

I completed the Graph Academy course Importing CSV Data into Neo4j as my starting point for learning about importing data. The course gave me an understanding of the options available, how to use Neo4j’s Data Importer, and an overview of the LOAD CSV statement in Cypher.

I created a Python program to generate CSV files from the OSM data, which I could import into Neo4j and generate the data model I had created.

I signed up for Neo4j’s AuraDB and set up a free Neo4j database in the cloud in a couple of minutes.

Using the data importer allowed me to quickly create a data model and get started on exploring the data, but as I looked to expand the data model, I found I needed to modify the source CSV files to support more complex relationships.

At this point, I had a learning opportunity. I could either:

1. Modify my Python program to get the data into the right shape and continue to use Data Importer.
2. Use LOAD CSV and Cypher to manipulate the existing CSV data at import.

While changing my Python program would have been quicker and easier I chose to use Cypher. My knowledge of Cypher is limited, and it gave me an opportunity to practice what I had learned and develop my knowledge.

Choosing a path which exposes gaps in your learning will help you stretch yourself and expand your knowledge and skills.

Neo4j’s documentation includes useful information on data importing, such as the Import your data into Neo4j guide, the Cypher manual, and the LOAD CSV reference.

I generated a data load process in Cypher which took the CSV data and built the data model.

This code snippet loads lift data from a CSV file and adds the data to the graph.

// lifts
LOAD CSV WITH HEADERS
FROM 'file:///test_lift_data.csv'
AS row
MATCH (r:Route {id: toInteger(row.id)})
SET r:Lift,
r.name = row.name,
r.type = row.type,
r.capacity = toInteger(row.capacity),
r.occupancy = toInteger(row.occupancy),
r.oneway = CASE row.oneway WHEN "yes" THEN true WHEN "no" THEN false ELSE null END;

Loading the data in Cypher allowed me to practice what I had learned and develop my skills.

Queries and Analytics

I explored the data graph I had created, writing queries to answer the questions I had created, testing against known scenarios, and extending the data range.

I refactored the data model removing duplication and using multiple labels to determine whether a Route node was a Trail or a Lift.

The Intermediate Cypher Queries course on GraphAcademy taught me more advanced Cypher queries and complex patterns.

I paired with my colleagues to learn about how to use shortest path algorithms and add properties such as distance and difficulty to relationships so I could use weighting to find alternative paths.

It is easy to forget that pairing is an opportunity for both people to learn new skills but also to find new ways of working.

The Graph database and Cypher queries I developed allowed me to determine how to navigate ski resorts.

For example, if I was at the top of the “Lapiaz” lift, how could I get to the bottom of the “Lutin” trail?

I created a Cypher query to find the start and end positions and used the shortestPath function to find a route between the 2 points.

MATCH (l:Lift{name: "Lapiaz"})-[:END]->(startPos:Position)
MATCH (endPos:Position)<-[:END]-(t:Trail{name: "Lutin"})
MATCH path = shortestPath(
    (startPos)-[:NEXT*..100]->(endPos)
)
RETURN l, path, t

Programming and Integration

I wanted to use Neo4j within an application to help me learn about the end-to-end use of Neo4j.

I am an experienced Python programmer, and while I would have gained other skills from using a different language, my goal was to understand Neo4j integration options and the drivers, not learn a new language.

The Using Neo4j from Python developer guide got me started installing the Python Driver and getting an example application running.

The GraphAcademy course Building Neo4j Applications with Python taught me about the driver in more detail, including executing read and write queries, managing transactions, and processing returned data.

I developed a Python application to access the ski resort data and show the route options from specific positions.

This helped me identify several new areas for my own learning, such as indexing and query optimization.

You can view the complete project code, including the data extract, data model, load process, and Python application, at github.com/martinohanlon/trail_and_run.

Certifications and Next Steps

I now feel ready to complete my Neo4j Certified Professional certification.

Gaining certification is an important step and demonstrates that you have the skills and knowledge required to develop solutions and support others.

On top of the recognition that comes with certification, assessment is an important part of any learning journey. Assessment allows you to recognize the progression you have made and identify gaps in your skills and knowledge; you can use this information to set your next goal and continuously adapt your learning journey.

Learning With Neo4j

If you are starting on a learning journey, I would recommend:

• Creating a goal
• Setting some easy-to-understand learning objectives
• Structuring your learning so it appeals to and motivates you

The Neo4j Developers page is the place to take your first steps with Neo4j. You will find guides, documentation, and events and be able to access the community of Neo4j developers.

Neo4j GraphAcademy offers a wide range of courses completely free of charge, teaching everything from Neo4j Fundamentals to how to develop software that connects to Neo4j.

I hope you have as much fun learning Neo4j as I have. I would love to hear about your experience learning Neo4j, our educational content, and particularly Neo4j GraphAcademy.

Originally published on Neo4j on 8 August 2023.

Its a really simple application, you start it up, you click “take image”, you re-position the scene, you click “take image” and so on until you are happy with your animation and you click “save” to store it as an animated gif.

You can find the source code at gist.github.com/martinohanlon.

Install

1. Connect a camera module
2. Enable the camera (Menu > Preferences > Raspberry Pi Configuration, Interfaces, Camera)
3. Open a terminal (Menu > Accessories > Terminal), install the modules and download the code:

sudo pip3 install guizero
sudo pip3 install imageio
wget -O guizero_stopmotion.py https://gist.githubusercontent.com/martinohanlon/52a7557a91d9e5b353a278447fbacc34/raw/guizero_stopmotion.py

1. Run the program:

python3 guizero_stopmotion.py

A couple of “interesting” things about this project The gui was created using guizero which is a super simple to use library for creating GUI’s, definitely have a look.

Most of the work was finding a way to create animated gifs in Python and working with images in memory rather than stored on disk

When the image is captured from the camera it isn’t stored to a file, it is stored in a numpy array, this means each frame is only stored in memory making it faster:

# create the camera
camera = PiCamera(resolution="640x480")
camera_output = PiRGBArray(camera)
...
# capture the image
camera.capture(camera_output, "rgb")
# append the camera image to the list as a numpy array
animation.images.append(camera_output.array)

The python module imageio is used to create the gif by passing the frames as a list, but again rather than being written to disk each time it is created as an in memory BytesIO stream:

gif_output = BytesIO()
imageio.mimsave(gif_output, animation.images, format="gif")

When the animated gif is displayed in guizero the BytesIO stream has to be open into a PIL Image.

animation.image = Image.open(gif_output)

At @Raspberry_Pi ‘s MakerDay I hacked a lucky cat so it only waves when it’s sunny. pic.twitter.com/JUED5nYadt

— Martin O’Hanlon (@martinohanlon) June 9, 2018

It did this by pulling the weather data from Open Weather Map using the Python module pyowm.

1.Sign up for a free API key in Open Weather Map.

2. Install the pyown Python module, open a Terminal or Command Prompt and run:

Windows

pip install pyown

Raspberry Pi / Linux

sudo pip3 install pyown

MacOS

pip3 install pyown

3. Create a Python program using the following code, inserting your API key:

import pyowm

owm = pyowm.OWM('put api key here')

observation = owm.weather_at_place('Cambridge,GB')
w = observation.get_weather()

clouds = w.get_clouds()
wind = w.get_wind()
humidity = w.get_humidity()
temp = w.get_temperature('celsius')

print("{}, {}, {}, {}".format(clouds, wind, humidity, temp)

Note - it can take up to 60 minutes for your API key to be activated.

There is a lot more information which can be pulled back - have a look at the weather module documentation for more details.

This seemed like a really big miss, shortcuts are the usual way for people (and certainly beginners to launch applications).

So I set to creating a really simple way of creating shortcuts for Python applications.

Enter shortcut, a X platform (Windows, MacOS, Linux, Raspberry Pi) Python module for automatically creating shortcuts.

Its really simple to install and use:

pip3 install shortcut
shortcut name_of_app

It will find the location of the app and create desktop and menu shortcuts for it.

There is also a Python API which can be used to do the same:

from shortcut import ShortCutter
s = ShortCutter()
s.create_desktop_shortcut("python")
s.create_menu_shortcut("python")

You will find documentation at shortcut.readthedocs.io and code at github.com/martinohanlon/shortcut.