Cypher on GDS graph

This feature is in the alpha tier. For more information on feature tiers, see API Tiers.

This feature is not available in AuraDS
This feature requires Neo4j Enterprise Edition.

Exploring projected 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 a projected 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 projected 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:

  • Some writes will fail

    • Creating new nodes and adding node labels

    • Everything related to relationships

2. Create database 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 projected 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 project procedure:

Project Person nodes and KNOWS relationships:
CALL gds.graph.project(
  'social_network',
  'Person',
  'KNOWS',
  { nodeProperties: 'age' }
)
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.

4. Dropping a GDS database

As described above, in-memory GDS databases are impermanent and will be removed when the DBMS is shut down. If we need to drop the GDS database earlier, there are 2 ways to achieve this: 1. Using an administrative cypher command against the system database (DROP DATABASE <db-name>) 2. Using the gds.alpha.drop.cypherdb procedure

4.1. Drop database syntax

CALL gds.alpha.drop.cypherdb(
    dbName: String
)
YIELD
    dbName: String,
    dropMillis: Integer