Building graph queries can be challenging for developers new to the Cypher query language. While Cypher’s ASCII art syntax graph has a lot of power, it can feel unfamiliar for those coming from the SQL world. Enter the Visual Cypher Builder — a prototype tool that helps you create Cypher queries with an easy-to-use drag-and-drop interface.
From Text to Blocks
In my job, I see a lot new people trying out Neo4j. Over the years, I observe a consistent pattern: People quickly grasp the concept of graph databases — nodes connected by relationships — but translating their mental model into Cypher syntax can be a big step.
Even though Cypher’s ASCII art style makes queries concise and expressive, newcomers often struggle with questions like:
- “What are the conceptual parts of a Cypher query?”
- “When do I use square brackets, round brackets, and arrows?”
- “How do I order my clauses like MATCH, WHERE, ORDER BY?”
As an example, consider the following query that finds movies directed by Christopher Nolan:
MATCH (p:Person)-[:DIRECTED]->(m:Movie)
WHERE p.name = "Christopher Nolan"
RETURN m.title, m.year
This query consists of several conceptual blocks, representing the matching pattern, filtering, and returning values.
While blocks help grasp the syntax, the order and meaning of the blocks is still hard to figure out. The Visual Cypher Builder tries to bridge this gap by turning abstract syntax into tangible, flexible building blocks, while also guiding you in structuring your query.
Building Queries Through Interaction
The Visual Cypher Builder offers four intuitive ways to construct queries:
1. A Gallery of Blocks
Inside the query builder, you’re presented with a gallery of blocks. You can click on a block to add it to your query. The gallery consists of two parts:
- On the left: A sidebar with different categories of blocks
- Below the query builder: A dynamic wizard that suggests some next blocks
Blocks can be dragged inside the query to rearrange them. Nodes, relationships, and properties will be generated based on your database schema. This is done by sampling your database when the tool starts up. As you start building your query, more blocks will become available in the sidebar.
2. Customization and Smart Suggestions
After placing the blocks, you can modify them to fit your needs. Based on the type of block you added (node, relationship, variable, etc.), you’ll be given suggestions on what to enter in the block’s text boxes. Since the builder is aware of your schema, it can also give suggestions on properties for certain nodes.
Again using sampling, we can discover the different types of variables. Given that query variables can have many types, we can also suggest different blocks based on your current query. This is where the wizard comes in.
3. The Wizard’s Guide
The wizard (🧙) watches your query construction and suggests logical next steps. Building a query becomes a conversation: “I see you’re matching Person nodes — would you like to add a relationship?” The wizard can be used together with the sidebar to build queries quickly.
In the initial version of the query builder, the wizard is powered by a rule-based engine. Looking at the last clause and last elements in your query, the wizard can suggest a valid next step. The wizard is also schema-aware — if you add a certain node pattern, the suggested relationship will be one linked to that node. You’ll discover that even with a simple set of 11 rules, the wizard can provide great suggestions on your next possible steps.
4. Template Learning
For those who learn best by example, the Templates menu offers a collection of pre-built queries addressing common graph questions. Templates are also generated based on your graph schema, providing a first look into what is possible with Cypher.
While these are a limited set of static examples, you can always load in a template and build on top of it. For those completely new to Cypher, templates can provide examples of how natural language questions translate into structured queries. The current set of templates consists mainly of simple queries (filtering, ordering, one-hop traversal). In future versions, we can dynamically generate complex queries or even use an LLM to generate queries for you.
Looking Ahead
This initial release (v0.1) focuses on making the fundamentals of Cypher queries accessible and intuitive. Future versions could expand the prototype to include:
- Advanced pattern building with variable-length relationships and quantified path patterns
- Live validation of syntax and hints for fixing broken queries
- Steering builders into placing correct blocks with visual highlighting, block colors, etc.
- An integrated query runner to visualize your results
Try It Out
You can try out the query builder prototype from your own web browser. If you’re feeling lucky, you can use it with your own database, but you can always use a public (read-only) demo.
As a prototype, the Visual Query Builder is available inside Neo4j Labs. Neo4j Labs is an incubator for experimental tools; these are free to try out, but not officially supported by Neo4j. We’re very much interested to hear your feedback and suggestions on the current prototype. Pull requests and issues are welcome in our GitHub repository.
Happy Cypher building!
Visual Cypher Builder — Querying Neo4j for everyone was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.
