Running Cypher queries

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.

Besides stream procedures, you can also use Cypher queries to inspect nodes and relationships in a graph.

The gds.ephemeral.database.create procedure creates an ephemeral Neo4j database that mirrors your in-memory graph. Once the database is created, you can run Cypher queries on it as you would on any Neo4j database.

1. Syntax

1.1. Creating an ephemeral database

CALL gds.ephemeral.database.create(
    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	The elapsed time to create the database in milliseconds.

1.2. Dropping an ephemeral database

CALL gds.ephemeral.database.drop(
    dbName: String
)
YIELD
    dbName: String,
    dropMillis: Integer

Table 3. Parameters
Name	Type	Optional	Description
dbName	String	no	The name of the database to drop.

Table 4. Results
Name	Type	Description
dbName	String	The name of the dropped database.
dropMillis	Integer	The elapsed time to drop the database in milliseconds.

2. Example

This example shows the creation of an ephemeral database from a simple social network graph and its usage with Cypher queries.

2.1. Setup

Here we create a Neo4j database and project it into memory:

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)

Project Person nodes and KNOWS relationships:

CALL gds.graph.project(
  'social_network',
  'Person',
  'KNOWS',
  { nodeProperties: 'age' }
)
YIELD
  graphName, nodeCount, relationshipCount

Next, we create an ephemeral database from the projected graph:

Create a new database gdsdb using our social_network graph:

CALL gds.ephemeral.database.create(
  'gdsdb',
  'social_network'
)

We can use the Neo4j SHOW DATABASES command to verify that the new database has been created successfully:

SHOW DATABASES

Table 5. 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

Finally, we switch to the newly created database to start using it:

:use gdsdb

2.2. Read query

We can now run a MATCH Cypher query on the in-memory database and check the results:

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

Table 6. Results
age1	age2
23	42
42	23
23	31

The returned properties correctly match those from the original graph.

It is important to note that the name property cannot be retrieved from the ephemeral database because it is not present in the projected graph. If you need to retrieve properties from the Neo4j database at the same time, you can use a composite database.

2.3. Cleanup

As described above, ephemeral databases are impermanent and are removed when the DBMS is shut down. There are two ways to drop an ephemeral database immediately:

Use an administrative command against the system database:
```
DROP DATABASE gdsdb
```
Use the gds.ephemeral.database.drop procedure:
```
CALL gds.ephemeral.database.drop('gdsdb')
```

In both cases, you need to switch to a different database before proceeding.

3. Limitations

Although it is possible to execute arbitrary Cypher queries on the ephemeral database, the database itself is not a plain Neo4j database. As such, not every aspect of Cypher is implemented.

The following operations are not supported:

Creating new nodes and adding node labels
Creating and updating relationships