GenAI Assistant Procedures
Query with natural language
This procedure apoc.ml.query
takes a question in natural language and returns the results of that query.
It uses the chat/completions
API which is documented here.
CALL apoc.ml.query("What movies did Tom Hanks play in?") yield value, query
RETURN *
+------------------------------------------------------------------------------------------------------------------------------+
| value | query |
+------------------------------------------------------------------------------------------------------------------------------+
| {m.title -> "You've Got Mail"} | "cypher
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'})
RETURN m.title
" |
| {m.title -> "Apollo 13"} | "cypher
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'})
RETURN m.title
" |
| {m.title -> "Joe Versus the Volcano"} | "cypher
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'})
RETURN m.title
" |
| {m.title -> "That Thing You Do"} | "cypher
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'})
RETURN m.title
" |
| {m.title -> "Cloud Atlas"} | "cypher
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'})
RETURN m.title
" |
| {m.title -> "The Da Vinci Code"} | "cypher
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'})
RETURN m.title
" |
| {m.title -> "Sleepless in Seattle"} | "cypher
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'})
RETURN m.title
" |
| {m.title -> "A League of Their Own"} | "cypher
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'})
RETURN m.title
" |
| {m.title -> "The Green Mile"} | "cypher
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'})
RETURN m.title
" |
| {m.title -> "Charlie Wilson's War"} | "cypher
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'})
RETURN m.title
" |
| {m.title -> "Cast Away"} | "cypher
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'})
RETURN m.title
" |
| {m.title -> "The Polar Express"} | "cypher
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person {name: 'Tom Hanks'})
RETURN m.title
" |
+------------------------------------------------------------------------------------------------------------------------------+
12 rows
name | description |
---|---|
question |
The question in the natural language |
conf |
An optional configuration map, please check the next section |
name | description | mandatory |
---|---|---|
retries |
The number of retries in case of API call failures |
no, default |
retryWithError |
If true, in case of error retry the api adding the following messages to the body request:
{ |
no, default |
apiKey |
OpenAI API key |
in case |
model |
The Open AI model |
no, default |
sample |
The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It’s used as a parameter to |
no, default is a random number |
name | description |
---|---|
value |
the result of the query |
cypher |
the query used to compute the result |
We can use the additionalPrompts
config to improve the request, e.g. adding the natural language description of the schema (like the output of the apoc.ml.schema
for instance).
Since OpenAI is mainly trained to elaborate natural language questions asked in, rather than Cypher queries, by using this configuration it is possible to achieve better results.
For example, given the Northwind dataset we can execute:
CALL apoc.ml.schema({apiKey: $apiKey}) YIELD value
WITH value
CALL apoc.ml.query("Which 5 employees had sold the product 'Chocolade' and has the highest selling count of another product?
Please returns the employee identificator, the other product name and the count orders of another product",
{
retries: 8,
retryWithError: true,
apiKey: $apiKey,
additionalPrompts: [
{role: "system", content: "The human description of the schema is the following:\n" + value}
]
})
YIELD query, value RETURN query, value
with a result similar to the following.
the results are not deterministic and will potentially change each time the query is re-executed |
query | value |
---|---|
"cypher MATCH (p:Product {productName: 'Chocolade'})←[:CONTAINS]-(:Order)←[:SOLD]-(e:Employee) MATCH (e)-[:SOLD]→(o:Order)-[:CONTAINS]→(p2:Product) WITH e, p2, COUNT(DISTINCT o) AS orderCount ORDER BY orderCount DESC RETURN e.employeeID AS employeeID, p2.productName AS otherProduct, orderCount LIMIT 5 " |
{ "otherProduct": "Gnocchi di nonna Alice", "employeeID": "4", "orderCount": 14 } |
"cypher MATCH (p:Product {productName: 'Chocolade'})←[:CONTAINS]-(:Order)←[:SOLD]-(e:Employee) MATCH (e)-[:SOLD]→(o:Order)-[:CONTAINS]→(p2:Product) WITH e, p2, COUNT(DISTINCT o) AS orderCount ORDER BY orderCount DESC RETURN e.employeeID AS employeeID, p2.productName AS otherProduct, orderCount LIMIT 5 " |
{ "otherProduct": "Pâté chinois", "employeeID": "4", "orderCount": 12 } |
"cypher MATCH (p:Product {productName: 'Chocolade'})←[:CONTAINS]-(:Order)←[:SOLD]-(e:Employee) MATCH (e)-[:SOLD]→(o:Order)-[:CONTAINS]→(p2:Product) WITH e, p2, COUNT(DISTINCT o) AS orderCount ORDER BY orderCount DESC RETURN e.employeeID AS employeeID, p2.productName AS otherProduct, orderCount LIMIT 5 " |
{ "otherProduct": "Gumbär Gummibärchen", "employeeID": "3", "orderCount": 12 } |
"cypher MATCH (p:Product {productName: 'Chocolade'})←[:CONTAINS]-(:Order)←[:SOLD]-(e:Employee) MATCH (e)-[:SOLD]→(o:Order)-[:CONTAINS]→(p2:Product) WITH e, p2, COUNT(DISTINCT o) AS orderCount ORDER BY orderCount DESC RETURN e.employeeID AS employeeID, p2.productName AS otherProduct, orderCount LIMIT 5 " |
{ "otherProduct": "Flotemysost", "employeeID": "1", "orderCount": 12 } |
"cypher MATCH (p:Product {productName: 'Chocolade'})←[:CONTAINS]-(:Order)←[:SOLD]-(e:Employee) MATCH (e)-[:SOLD]→(o:Order)-[:CONTAINS]→(p2:Product) WITH e, p2, COUNT(DISTINCT o) AS orderCount ORDER BY orderCount DESC RETURN e.employeeID AS employeeID, p2.productName AS otherProduct, orderCount LIMIT 5 " |
{ "otherProduct": "Pavlova", "employeeID": "1", "orderCount": 11 } |
Respect to using the procedure without the natural language schema description, the output has fewer hallucinations, like properties hold by different labels and relationships linked to other entities.
Describe the graph model with natural language
This procedure apoc.ml.schema
returns a description, in natural language, of the underlying dataset.
It uses the chat/completions
API which is documented here.
CALL apoc.ml.schema() yield value
RETURN *
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| value |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "The graph database schema represents a system where users can follow other users and review movies. Users (:Person) can either follow other users (:Person) or review movies (:Movie). The relationships allow users to express their preferences and opinions about movies. This schema can be compared to social media platforms where users can follow each other and leave reviews or ratings for movies they have watched. It can also be related to movie recommendation systems where user preferences and reviews play a crucial role in generating personalized recommendations." |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1 row
name | description |
---|---|
conf |
An optional configuration map, please check the next section |
name | description | mandatory |
---|---|---|
apiKey |
OpenAI API key |
in case |
model |
The Open AI model |
no, default |
sample |
The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It’s used as a parameter to |
no, default is a random number |
name | description |
---|---|
value |
the description of the dataset |
Create cypher queries from a natural language query
This procedure apoc.ml.cypher
takes a natural language question and transforms it into a number of requested cypher queries.
It uses the chat/completions
API which is documented here.
CALL apoc.ml.cypher("Who are the actors which also directed a movie?", {count: 4}) yield cypher
RETURN *
+----------------------------------------------------------------------------------------------------------------+
| query |
+----------------------------------------------------------------------------------------------------------------+
| "
MATCH (a:Person)-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(d:Person)
RETURN a.name as actor, d.name as director
" |
| "cypher
MATCH (a:Person)-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(a)
RETURN a.name
" |
| "
MATCH (a:Person)-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(d:Person)
RETURN a.name
" |
| "cypher
MATCH (a:Person)-[:ACTED_IN]->(:Movie)<-[:DIRECTED]-(a)
RETURN DISTINCT a.name
" |
+----------------------------------------------------------------------------------------------------------------+
4 rows
name | description | mandatory |
---|---|---|
question |
The question in the natural language |
yes |
conf |
An optional configuration map, please check the next section |
no |
name | description | mandatory |
---|---|---|
count |
The number of queries to retrieve |
no, default |
apiKey |
OpenAI API key |
in case |
model |
The Open AI model |
no, default |
sample |
The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It’s used as a parameter to |
no, default is a random number |
name | description |
---|---|
value |
the description of the dataset |
We can use the additionalPrompts
config to improve the request, e.g. adding the natural language description of the schema (like the output of the apoc.ml.schema
for instance).
Since OpenAI is mainly trained to elaborate natural language questions asked in, rather than Cypher queries, by using this configuration it is possible to achieve better results.
For example, given the Northwind dataset we can execute:
CALL apoc.ml.schema({apiKey: $apiKey}) YIELD value
WITH value
CALL apoc.ml.cypher("Which 5 employees had sold the product 'Chocolade' and has the highest selling count of another product?
Please returns the employee identificator, the other product name and the count orders of another product",
{
count: 1,
apiKey: $apiKey,
additionalPrompts: [
{role: "system", content: "The human description of the schema is the following:\n" + value}
]
})
YIELD value RETURN value
with a result similar to the following.
the results are not deterministic and will potentially change each time the query is re-executed |
value |
---|
MATCH (p:Product {productName: 'Chocolade'})←[:CONTAINS]-(o:Order)←[:SOLD]-(e:Employee) MATCH (e)-[:SOLD]→(o2:Order)-[:CONTAINS]→(p2:Product) WITH e, p2, COUNT(DISTINCT o2) AS ordersCnt ORDER BY ordersCnt DESC RETURN e.employeeID AS employeeID, p2.productName AS otherProduct, ordersCnt LIMIT 5 |
Respect to using the procedure without the natural language schema description, the output has fewer hallucinations, like properties hold by different labels and relationships linked to other entities.
Create a natural language query explanation from a cypher query
This procedure apoc.ml.fromCypher
takes a natural language question and transforms it into natural language query explanation.
It uses the chat/completions
API which is documented here.
CALL apoc.ml.cypher("MATCH (p:Person {name: "Tom Hanks"})-[:ACTED_IN]->(m:Movie) RETURN m", {}) yield value
RETURN *
value |
---|
this database schema represents a simplified version of a common movie database model. the |
name | description | mandatory |
---|---|---|
cypher |
The question in the natural language |
yes |
conf |
An optional configuration map, please check the next section |
no |
name | description | mandatory |
---|---|---|
retries |
The number of retries in case of API call failures |
no, default |
apiKey |
OpenAI API key |
in case |
model |
The Open AI model |
no, default |
sample |
The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It’s used as a parameter to |
no, default is a random number |
name | description |
---|---|
value |
the description of the dataset |
Create explanation of the subgraph from a set of queries
This procedure apoc.ml.fromQueries
returns an explanation, in natural language, of the given set of queries.
It uses the chat/completions
API which is documented here.
CALL apoc.ml.fromQueries(['MATCH (n:Movie) RETURN n', 'MATCH (n:Person) RETURN n'],
{apiKey: <apiKey>})
YIELD value
RETURN *
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| value |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "The database represents movies and people, like in a movie database or social network.
There are no defined relationships between nodes, allowing flexibility for future connections.
The Movie node includes properties like title, tagline, and release year." |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1 row
CALL apoc.ml.fromQueries(['MATCH (n:Movie) RETURN n', 'MATCH p=(n:Movie)--() RETURN p'],
{apiKey: <apiKey>})
YIELD value
RETURN *
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| value |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| "models relationships in the movie industry, connecting :Person nodes to :Movie nodes.
It represents actors, directors, writers, producers, and reviewers connected to movies they are involved with.
Similar to a social network graph but specialized for the entertainment industry.
Each relationship type corresponds to common roles in movie production and reviewing.
Allows for querying and analyzing connections and collaborations within the movie business." |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1 row
name | description |
---|---|
queries |
The list of queries |
conf |
An optional configuration map, please check the next section |
name | description | mandatory |
---|---|---|
apiKey |
OpenAI API key |
in case |
model |
The Open AI model |
no, default |
sample |
The number of nodes to skip, e.g. a sample of 1000 will read every 1000th node. It’s used as a parameter to |
no, default is a random number |
name | description |
---|---|
value |
the description of the dataset |