Cypher Technology: The Good, The Unhealthy and The Messy | by Silvia Onofrei | Jan, 2024


Strategies for creating fine-tuning datasets for text-to-Cypher technology.

Created with ChatGPT-DALLE

Cypher is Neo4j’s graph question language. It was impressed and bears similarities with SQL, enabling knowledge retrieval from data graphs. Given the rise of generative AI and the widespread availability of enormous language fashions (LLMs), it’s pure to ask which LLMs are able to producing Cypher queries or how we are able to finetune our personal mannequin to generate Cypher from the textual content.

The problem presents appreciable challenges, primarily as a result of shortage of fine-tuning datasets and, for my part, as a result of such a dataset would considerably depend on the precise graph schema.

On this weblog publish, I’ll focus on a number of approaches for making a fine-tuning dataset aimed toward producing Cypher queries from textual content. The preliminary method is grounded in Massive Language Fashions (LLMs) and makes use of a predefined graph schema. The second technique, rooted solely in Python, gives a flexible means to provide an enormous array of questions and Cypher queries, adaptable to any graph schema. For experimentation I created a data graph that’s based mostly on a subset of the ArXiv dataset.

As I used to be finalizing this blogpost, Tomaz Bratanic launched an initiative project aimed toward creating a complete fine-tuning dataset that encompasses varied graph schemas and integrates a human-in-the-loop method to generate and validate Cypher statements. I hope that the insights mentioned right here may even be advantageous to the undertaking.

I like working with the ArXiv dataset of scientific articles due to its clear, easy-to-integrate format for a data graph. Using strategies from my current Medium blogpost, I enhanced this dataset with further key phrases and clusters. Since my main focus is on constructing a fine-tuning dataset, I’ll omit the specifics of establishing this graph. For these , particulars could be discovered on this Github repository.

The graph is of an inexpensive dimension, that includes over 38K nodes and nearly 96K relationships, with 9 node labels and eight relationship sorts. Its schema is illustrated within the following picture:

Picture by the Creator

Whereas this data graph isn’t absolutely optimized and could possibly be improved, it serves the needs of this blogpost fairly successfully. In case you want to simply check queries with out constructing the graph, I uploaded the dump file on this Github repository.

The primary method I carried out was impressed by Tomaz Bratanic’s blogposts on building a knowledge graph chatbot and finetuning a LLM with H2O Studio. Initially, a choice of pattern queries was supplied within the immediate. Nevertheless, a few of the current fashions have enhanced functionality to generate Cypher queries immediately from the graph schema. Subsequently, along with GPT-4 or GPT-4-turbo, there at the moment are accessible open supply alternate options reminiscent of Mixtral-8x7B I anticipate might successfully generate first rate high quality coaching knowledge.

On this undertaking, I experimented with two fashions. For the sake of comfort, I made a decision to make use of GPT-4-turbo along with ChatGPT, see this Colab Notebook. Nevertheless, on this notebook I carried out just a few checks with Mixtral-7x2B-GPTQ, a quantized mannequin that’s sufficiently small to run on Google Colab, and which delivers passable outcomes.

To take care of knowledge range and successfully monitor the generated questions, Cypher statements pairs, I’ve adopted a two steps method:

  • Step 1: present the total schema to the LLM and request it to generate 10–15 totally different classes of potential questions associated to the graph, together with their descriptions,
  • Step 2: present schema data and instruct the LLM to create a particular quantity N of coaching pairs for every recognized class.

Extract the classes of samples:

For this step I used ChatGPT Professional model, though I did iterate via the immediate a number of instances, mixed and enhanced the outputs.

  • Extract a schema of the graph as a string (extra about this within the subsequent part).
  • Construct a immediate to generate the classes:
chatgpt_categories_prompt = f"""
You might be an skilled and helpful Python and Neo4j/Cypher developer.

I've a data graph for which I wish to generate
attention-grabbing questions which span 12 classes (or sorts) concerning the graph.
They need to cowl single nodes questions,
two or three extra nodes, relationships and paths. Please recommend 12
classes along with their brief descriptions.
Right here is the graph schema:

  • Ask the LLM to generate the classes.
  • Overview, make corrections and improve the classes as wanted. Here’s a pattern:
'''Authorship and Collaboration: Questions on co-authorship and collaboration patterns.
For instance, "Which authors have co-authored articles probably the most?"''',
'''Article-Creator Connections: Questions concerning the relationships between articles and authors,
reminiscent of discovering articles written by a particular creator or authors of a selected article.
For instance, "Discover all of the authors of the article with tile 'Explorations of manifolds'"''',
'''Pathfinding and Connectivity: Questions that contain paths between a number of nodes,
reminiscent of tracing the connection path from an article to a subject via key phrases,
or from an creator to a journal via their articles.
For instance, "How is the creator 'John Doe' related to the journal 'Nature'?"'''


  • If the graph schema may be very giant, cut up it into overlapping subgraphs (this is determined by the graph topology additionally) and repeat the above course of for every subgraph.
  • When working with open supply fashions, select the very best mannequin you may match in your computational assets. TheBloke has posted an intensive record of quantized fashions, Neo4j GenAI offers instruments to work by yourself {hardware} and LightningAI Studio is a lately launched platform which provides you entry to a large number of LLMs.

Generate the coaching pairs:

This step was carried out with OpenAI API, working with GPT-4-turbo which additionally has the choice to output JSON format. Once more the schema of the graph is supplied with the immediate:

def create_prompt(schema, class):
"""Construct and format the immediate."""
formatted_prompt = [
{"role": "system",
"content": "You are an experienced Cypher developer and a
helpful assistant designed to output JSON!"},
{"role": "user",
"content": f"""Generate 40 questions and their corresponding
Cypher statements about the Neo4j graph database with
the following schema:
The questions should cover {category} and should be phrased
in a natural conversational manner. Make the questions diverse
and interesting.
Make sure to use the latest Cypher version and that all
the queries are working Cypher queries for the provided graph.
You may add values for the node attributes as needed.
Do not add any comments, do not label or number the questions.
return formatted_prompt

Construct the operate which is able to immediate the mannequin and can retrieve the output:

def prompt_model(messages):
"""Perform to provide and extract mannequin's technology."""
response =
mannequin="gpt-4-1106-preview", # work with gpt-4-turbo
response_format={"kind": "json_object"},
return response.decisions[0].message.content material

Loop via the classes and acquire the outputs in an inventory:

def build_synthetic_data(schema, classes):
"""Perform to loop via the classes and generate knowledge."""

# Record to gather all outputs
for class in classes:
# Immediate the mannequin and retrieve the generated reply
output = [prompt_model(create_prompt(schema, category))]
# Retailer all of the outputs in an inventory
full_output += output
return full_output

# Generate 40 pairs for every of the classes
full_output = build_synthetic_data(schema, classes)

# Save the outputs to a file
write_json(full_output, data_path + synthetic_data_file)

At this level within the undertaking I collected nearly 500 pairs of questions, Cypher statements. Here’s a pattern:

{"Query": "What articles have been written by 'John Doe'?",
"Cypher": "MATCH (a:Creator {first_name:'John', last_name:'Doe'})-
[:WRITTEN_BY]-(article:Article) RETURN article.title, article.article_id;"}

The information requires important cleansing and wrangling. Whereas not overly advanced, the method is each time-consuming and tedious. Listed here are a number of of the challenges I encountered:

  • non-JSON entries on account of incomplete Cypher statements;
  • the anticipated format is {’query’: ‘some query’, ‘cypher’:’some cypher’}, however deviations are frequent and should be standardized;
  • situations the place the questions and the Cypher statements are clustered collectively, necessiting their separation and group.


It’s higher to iterate via variations of the immediate than looking for the very best immediate format from the start. In my expertise, even with diligent changes, producing a big quantity of knowledge like this inevitably results in some deviations.

Now concerning the content material. GPT-4-turbo is kind of succesful to generate good questions concerning the graph, nonetheless not all of the Cypher statements are legitimate (working Cypher) and proper (extract the supposed data). When fine-tuning in a manufacturing surroundings, I might both rectify or get rid of these faulty statements.

I created a operate execute_cypher_queries() that sends the queries to the Neo4j graph database . It both information a message in case of an error or retrieves the output from the database. This operate is obtainable on this Google Colab notebook.

From the immediate, you could discover that I instructed the LLM to generate mock knowledge to populate the attributes values. Whereas this method is less complicated, it ends in quite a few empty outputs from the graph. And it calls for additional effort to determine these statements involving hallucinatins, reminiscent of made-up attributes:

'MATCH (creator:Creator)-[:WRITTEN_BY]-(article:Article)-[:UPDATED]-
WHERE article.creation_date = updateDate.update_date
RETURN DISTINCT creator.first_name, creator.last_name;"

The Article node has no creation_date attribute within the ArXiv graph!


To attenuate the empty outputs, we might as an alternative extract situations immediately from the graph. These situations can then be integrated into the immediate, and instruct the LLM to make use of this data to complement the Cypher statements.

This technique permits to create wherever from lots of to lots of of 1000’s of right Cypher queries, relying on the graph’s dimension and complexity. Nevertheless, it’s essential to strike a steadiness bewteen the amount and the range of those queries. Regardless of being right and relevant to any graph, these queries can sometimes seem formulaic or inflexible.

Extract Data In regards to the Graph Construction

For this course of we have to begin with some knowledge extraction and preparation. I take advantage of the Cypher queries and the a few of the code from the module in Langchain.

  • Hook up with an current Neo4j graph database.
  • Extract the schema in JSON format.
  • Extract a number of node and relationship situations from the graph, i.e. knowledge from the graph to make use of as samples to populate the queries.

I created a Python class that perfoms these steps, it’s out there at utils/ within the Github repository. With all these in place, extracting the related knowledge concerning the graph necessitates just a few strains of code solely:

# Initialize the Neo4j connector
graph = Neo4jGraph(url=URI, username=USER, password=PWD)
# Initialize the schema extractor module
gutils = Neo4jSchema(url=URI, username=USER, password=PWD)

# Construct the schema as a JSON object
jschema = gutils.get_structured_schema
# Retrieve the record of nodes within the graph
nodes = get_nodes_list(jschema)
# Learn the nodes with their properties and their datatypes
node_props_types = jschema['node_props']

# Examine the output
print(f"The properties of the node Report are:n{node_props_types['Report']}")

>>>The properties of the node Report are:
[{'property': 'report_id', 'datatype': 'STRING'}, {'property': 'report_no', 'datatype': 'STRING'}]

# Extract an inventory of relationships
relationships = jschema['relationships']

# Examine the output

>>>[{'start': 'Article', 'type': 'HAS_KEY', 'end': 'Keyword'},
{'start': 'Article', 'type': 'HAS_DOI', 'end': 'DOI'}]

Extract Information From the Graph

This knowledge will present genuine values to populate our Cypher queries with.

  • First, we extract a number of node situations, this may retrieve all the info for nodes within the graph, together with labels, attributes and their values :
# Extract node samples from the graph - 4 units of node samples
node_instances = gutils.extract_node_instances(
nodes, # record of nodes to extract labels
4) # what number of situations to extract for every node
  • Subsequent, extract relationship situations, this consists of all the info on the beginning node, the connection with its kind and properties, and the top node data:
# Extract relationship situations
rels_instances = gutils.extract_multiple_relationships_instances(
relationships, # record of relationships to extract situations for
8) # what number of situations to extract for every relationship


  • Each of the above strategies work for the total lists of nodes, relationships or sublists of them.
  • If the graph comprises situations that lack information for some attributes, it’s advisable to gather extra situations to make sure all attainable eventualities are coated.

The subsequent step is to serialize the info, by changing the Neo4j.time values with strings and put it aside to information.

Parse the Extracted Information

I confer with this section as Python gymnastics. Right here, we deal with the info obtained within the earlier step, which consists of the graph schema, node situations, and relationship situations. We reformat this knowledge to make it simply accessible for the capabilities we’re creating.

  • We first determine all of the datatypes within the graph with:
dtypes = retrieve_datatypes(jschema)


  • For every datatype we extract the attributes (and the corresponding nodes) which have that dataype.
  • We parse situations of every datatype.
  • We additionally course of and filter the relationships in order that the beginning and the top nodes have attributes of specifid knowledge sorts.

All of the code is obtainable within the Github repository. The explanations of doing all these will turn out to be clear within the subsequent part.

Learn how to Construct One or One Thousand Cypher Statements

Being a mathematician, I usually understand statements by way of the underlying capabilities. Let’s think about the next instance:

q = "Discover the Subject whose description comprises 'Jordan regular type'!"
cq = "MATCH (n:Subject) WHERE n.description CONTAINS 'Jordan regular type' RETURN n"

The above could be considered capabilities of a number of variables f(x, y, z) and g(x. y, z) the place

f(x, y, z) = f"Discover the {x} whose {y} comprises {z}!"
q = f('Subject', 'description', 'Jordan regular type')

g(x, y, z) = f"MATCH (n:{x}) WHERE n.{y} CONTAINS {z} RETURN n"
qc = g('Subject', 'description', 'Jordan regular type')

What number of queries of this sort can we construct? To simplify the argument let’s assume that there are N node labels, every having in common n properties which have STRING datatype. So not less than Nxn queries can be found for us to construct, not making an allowance for the choices for the string decisions z.


Simply because we’re in a position to assemble all these queries utilizing a single line of code doesn’t suggest that we must always incorporate your entire set of examples into our fine-tuning dataset.

Develop a Course of and a Template

The principle problem lies in making a sufficiently various record of queries that covers a variety of elements associated to the graph. With each proprietary and open-source LLMs able to producing fundamental Cypher syntax, our focus can shift to producing queries concerning the nodes and relationships throughout the graph, whereas omitting syntax-specific queries. To collect question examples for conversion into purposeful type, one might confer with any Cypher language ebook or discover the Neo4j Cypher documentation site.

Within the GitHub repository, there are about 60 varieties of these queries which might be then utilized to the ArXiv data graph. They’re versatile and relevant to any graph schema.

Beneath is the whole Python operate for creating one set of comparable queries and incorporate it within the fine-tuning dataset:

def find_nodes_connected_to_node_via_relation():
def prompter(label_1, prop_1, rel_1, label_2):
subschema = get_subgraph_schema(jschema, [label_1, label_2], 2, True)
message = {"Immediate": "Convert the next query right into a Cypher question utilizing the supplied graph schema!",
"Query": f"""For every {label_1}, discover the variety of {label_2} linked by way of {rel_1} and retrieve the {prop_1} of the {label_1} and the {label_2} counts in ascending order!""",
"Schema": f"Graph schema: {subschema}",
"Cypher": f"MATCH (n:{label_1}) -[:{rel_1}]->(m:{label_2}) WITH DISTINCT n, m RETURN n.{prop_1} AS {prop_1}, depend(m) AS {label_2.decrease()}_count ORDER BY {label_2.decrease()}_count"
return message

for e in all_rels:
for okay, v in e[1].objects():
temp_dict = prompter(e[0], okay, e[2], e[3])

return sampler

  • the operate find_nodes_connected_to_node_via_relation() takes the producing prompter and evaluates it for all the weather in all_rels which is the gathering of extracted and processed relationship situations, whose entries are of the shape:
{'name': 'logarithms', 'key_id': '720452e14ca2e4e07b76fa5a9bc0b5f6'},
{'cluster': 0}]
  • the prompter inputs are two nodes denoted label_1 and label_2 , the property prop_1 for label_1 and the connection rel_1 ,
  • the message comprises the parts of the immediate for the corresponding entry within the fine-tuning dataset,
  • the subschema extracts first neighbors for the 2 nodes denoted label_1 and label_2 , this implies: the 2 nodes listed, all of the nodes associated to them (distance one within the graph), the relationships and all of the corresponding attributes.


Together with the subschema within the finetuning dataset just isn’t important, though the extra intently the immediate aligns with the fine-tuning knowledge, the higher the generated output tends to be. From my perspective, incorporating the subschema within the fine-tuning knowledge nonetheless gives benefits.

To summarize, publish has explored varied strategies for constructing a fine-tuning dataset for producing Cypher queries from textual content. Here’s a breakdown of those strategies, together with their benefits and downsides:

LLM generated query and Cypher statements pairs:

  • The tactic could seem easy by way of knowledge assortment, but it usually calls for extreme knowledge cleansing.
  • Whereas sure proprietary LLMs yield good outcomes, many open supply LLMs nonetheless lack the proficiency of producing a variety of correct Cypher statements.
  • This system turns into burdensome when the graph schema is advanced.

Purposeful method or parametric question technology:

  • This technique is adaptable throughout varied graphs schemas and permits for simple scaling of the pattern dimension. Nevertheless, it is very important be sure that the info doesn’t turn out to be overly repetitive and maintains range.
  • It requires a big quantity of Python programming. The queries generated can usually appear mechanial and should lack a conversational tone.

To increase past these approaches:

  • The graph schema could be seamlessley integrated into the framework for creating the purposeful queries. Take into account the next query, Cypher assertion pair:
Query: Which articles have been written by the creator whose final identify is Doe?
Cypher: "MATCH (a:Article) -[:WRITTEN_BY]-> (:Creator {last_name: 'Doe') RETURN a"

As an alternative of utilizing a direct parametrization, we might incorporate fundamental parsing (reminiscent of changing WRITTEN_BY with written by), enhancing the naturalness of the generated query.

This highligts the importance of the graph schema’s design and the labelling of graph’s entities within the development of the fine-tuning pars. Adhering to normal norms like utilizing nouns for node labels and suggestive verbs for the relationships proves helpful and might create a extra organically conversational hyperlink between the weather.

  • Lastly, it’s essential to not overlook the worth of accumulating precise consumer generated queries from graph interactions. When out there, parametrizing these queries or enhancing them via different strategies could be very helpful. Finally, the effectiveness of this technique is determined by the precise targets for which the graph has been designed.

To this finish, it is very important point out that my focus was on easier Cypher queries. I didn’t deal with creating or modifying knowledge throughout the graph, or the graph schema, nor I did embrace APOC queries.

Are there every other strategies or concepts you may recommend for producing such fine-tuning query and Cypher assertion pairs?


Github Repository: Knowledge_Graphs_Assortment — for constructing the ArXiv data graph

Github Repository: Cypher_Generator — for all of the code associated to this blogpost


• Repository of scholary articles: arXiv Dataset that has CC0: Public Domain license.


Related Articles

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button