Cypher on GDS graph

This chapter explains how to execute Cypher queries on named graphs in the Neo4j Graph Data Science library.

This feature is in the alpha tier.

Exploring in-memory graphs after loading them and potentially executing algorithms in mutate mode can be tricky in the Neo4j Graph Data Science library. A natural way to achieve this in the Neo4j database is to use Cypher queries. Cypher queries allow for example to get a hold of which properties are present on a node among many other things. Executing Cypher queries on an in-memory graph can be achieved by leveraging the gds.alpha.create.cypherdb procedure. This procedure will create a new impermanent database which you can switch to. That database will then use data from the in-memory graph as compared to the store files for usual Neo4j databases.

1. Limitations

Although it is possible to execute arbitrary Cypher queries on the database created by the gds.alpha.create.cypherdb procedure, not every aspect of Cypher is implemented yet. Some known limitations are listed below:

  • Dropping the newly created database

    • Restarting the DBMS will remove the database instead

  • Writes

    • All queries that attempt to write things, such as nodes, properties or labels, will fail

  • Referencing relationships

    • Referencing variables bound to a relationship is not supported, this includes returning relationships

    • It is however possible to use relationship as traversal, i.e. MATCH (n)-[:KNOWS]→(m) will work as expected

2. Syntax

CALL gds.alpha.create.cypherdb(
    dbName: String
    graphName: String
)
YIELD
    dbName: String,
    graphName: String,
    createMillis: Integer
Table 1. Parameters
Name Type Optional Description

dbName

String

no

The name under which the new database is stored.

graphName

String

no

The name under which the graph is stored in the catalog.

Table 2. Results
Name Type Description

dbName

String

The name under which the new database is stored.

graphName

String

The name under which the graph is stored in the catalog.

createMillis

Integer

Milliseconds for creating the database.

3. Example

To demonstrate how to execute cypher statements on in-memory graphs we are going to create a simple social network graph. We will use this graph to create a new database which we will execute our statements on.

CREATE
  (alice:Person { name: 'Alice', age: 23 }),
  (bob:Person { name: 'Bob', age: 42 }),
  (carl:Person { name: 'Carl', age: 31 }),

  (alice)-[:KNOWS]->(bob),
  (bob)-[:KNOWS]->(alice),
  (alice)-[:KNOWS]->(carl)

We will now load a graph projection of the created graph via the graph create procedure:

Project Person nodes and KNOWS relationships:
CALL gds.graph.create(
  'social_network',
  'Person',
  'KNOWS'
)
YIELD
  graphName, nodeCount, relationshipCount
Table 3. Results
graph nodeCont relationshipCount

"social_network"

3

3

With a named graph loaded into the Neo4j Graph Data Science library, we can proceed to create the new database using the loaded graph as underlying data.

Create a new database gdsDb using our social_network graph:
CALL gds.alpha.create.cypherdb(
  'gdsDb',
  'social_network'
)

In order to verify that the new database was created successfully we can use the Neo4j database administration commands.

SHOW DATABASES
Table 4. Results
name address role requestedStatus currentStatus error default home

"neo4j"

"localhost:7687"

"standalone"

"online"

"online"

""

true

true

"system"

"localhost:7687"

"standalone"

"online"

"online"

""

false

false

"gdsDb"

"localhost:7687"

"standalone"

"online"

"online"

""

false

false

We can now switch to the newly created database.

:use gdsDb

Finally, we are set up to execute cypher queries on our in-memory graph.

MATCH (n:Person)-[:KNOWS]->(m:Person) RETURN n.age AS age1, m.age AS age2
Table 5. Results
age1 age2

23

42

42

23

23

31

We can see that the returned ages correspond to the structure of the original graph.