Set up and query composite databases
Graph set-up
The following set-up is required to recreate the examples on this page:
movies2022
CREATE DATABASE movies2022
cineasts
CREATE COMPOSITE DATABASE cineasts
cineasts
.latest
for a local database in a composite databaseCREATE ALIAS `cineasts`.`latest`
FOR DATABASE movies2022
cineasts
.upcoming
for a remote database in a composite databaseCREATE ALIAS `cineasts`.`upcoming`
FOR DATABASE upcoming
AT 'neo4j+s://location:7687'
USER neo4j
PASSWORD 'password'
For more information about composite databases and database aliases in composite databases, see Concepts, and Managing database aliases in composite databases.
Graph selection
Queries submitted to a composite database may contain several USE
clauses that direct different parts of the query to different constituent graphs.
Each constituent graph is named after the alias that introduces it into the Composite database.
Query a single graph
USE cineasts.latest
MATCH (movie:Movie)
RETURN movie.title AS title
The USE
clause at the beginning of the query selects the cineasts.latest
graph for all the subsequent clauses.
MATCH
is performed on that graph.
Query multiple graphs
USE cineasts.latest
MATCH (movie:Movie)
RETURN movie.title AS title
UNION
USE cineasts.upcoming
MATCH (movie:Movie)
RETURN movie.title AS title
The first part of the UNION
query selects the cineasts.latest
graph and the second part selects the cineasts.upcoming
graph.
Dynamic graph access
Queries can also select constituent graphs dynamically, using the form USE graph.byName(graphName)
.
UNWIND ['cineasts.latest', 'cineasts.upcoming'] AS graphName
CALL {
USE graph.byName(graphName)
MATCH (movie:Movie)
RETURN movie
}
RETURN movie.title AS title
In the example above, the part of the query accessing graph data, MATCH (movie:Movie)
, is wrapped in a sub-query with a dynamic USE
clause.
UNWIND
is used to get the names of our graphs, each on one row.
The CALL {}
sub-query executes once per input row.
In this case, once selecting cineasts.latest
, and once selecting cineasts.upcoming
.
Listing graphs
The built-in function graph.names()
returns a list containing the names of all constituent graphs on the current Composite database.
graph.names()
functionUNWIND graph.names() AS graphName
RETURN graphName
+---------------------+ | graphName | +---------------------+ | "cineasts.latest" | | "cineasts.upcoming" | +---------------------+
The names returned by this function can be used for dynamic graph access.
UNWIND graph.names() AS graphName
CALL {
USE graph.byName(graphName)
MATCH (movie:Movie)
RETURN movie
}
RETURN movie.title
Query result aggregation
UNWIND graph.names() AS graphName
CALL {
USE graph.byName(graphName)
MATCH (movie:Movie)
RETURN movie.released AS released
}
RETURN min(released) AS earliest
The sub-query returns the released
property of each movie, from each constituent graph.
The RETURN
at the end of the main query aggregates across the full result to calculate the global minimum.
Correlated subqueries
This query finds all movies in cineasts.upcoming
that are to be released in the same month as the longest movie in cineasts.latest
.
CALL {
USE cineasts.latest
MATCH (movie:Movie)
RETURN movie.releasedMonth AS monthOfLongest
ORDER BY movie.runningTime DESC
LIMIT 1
}
CALL {
USE cineasts.upcoming
WITH monthOfLongest
MATCH (movie:Movie)
WHERE movie.releasedMonth = monthOfLongest
RETURN movie
}
RETURN movie
The first part of the query finds the movie with the longest running time from cineasts.latest
, and returns its release month.
The second part of the query finds all movies in cineasts.upcoming
that fulfill our condition and returns them.
The sub-query imports the monthOfLongest
variable using WITH monthOfLongest
, to make it accessible.
Updates
Composite database queries can perform updates to constituent graphs.
USE cineasts.upcoming
CREATE (:Movie {title: 'Dune: Part Two'})
Updates can only be performed on a single constituent graph per transaction. |
UNWIND graph.names() AS graphName
CALL {
USE graph.byName(graphName)
CREATE (:Movie {title: 'The Flash'})
}
Writing to more than one database per transaction is not allowed.
Limitations
Queries on Composite databases have a few limitations.
Graph accessing operations
Consider a Composite database query:
UNWIND graph.names() AS graphName
CALL {
USE graph.byName(graphName)
MATCH (movie:Movie)
RETURN movie
}
RETURN movie
Here the outer clauses, i.e. the UNWIND
, the CALL
itself, and the final RETURN
, appear in the root scope of the query, without a specifically chosen graph.
Clauses or expressions in scopes where no graph has been specified must not be graph-accessing.
The following Composite database query is invalid because [p=(movie)-→() | p] AS paths
is a graph-accessing operation in the root scope of the query:
UNWIND graph.names() AS graphName
CALL {
USE graph.byName(graphName)
MATCH (movie:Movie)
RETURN movie
}
RETURN [p=(movie)-->() | p] AS paths
See examples of graph-accessing operations:
-
RETURN 1 + 2 AS number
-
WITH node.property AS val
Nested USE
clauses
An inner scope must use the same graph as its outer scope:
USE cineasts.latest
MATCH (n)
CALL {
USE cineasts.upcoming
MATCH (m)
RETURN m
}
RETURN n, m
Nested subqueries must use the same graph as their parent query. Attempted to access graph cineasts.upcoming " USE cineasts.upcoming" ^
Sub-queries without a USE
clause can be nested.
They inherit the specified graph from the outer scope.
CALL {
USE cineasts.upcoming
CALL {
MATCH (m:Movie)
RETURN m
}
RETURN m
}
RETURN m
Cypher runtime
When a query is submitted to a Composite database, different parts of the query may run using different runtimes. Clauses or expressions in scopes where no graph has been specified run using the slotted runtime. Parts of the query directed to different constituent graphs are run using the default runtime for that graph, or respect the submitted Cypher query options if specified.
Built-in graph functions
Graph functions are located in the namespace graph
.
The following table describes these functions:
Function | Explanation |
---|---|
|
Provides a list of names of all constituent graphs on the current Composite database. |
|
Used with the |
|
Returns a map containing the properties associated with the given graph. |
For more information, see Graph functions in the Cypher Manual.