The Graph Search feature allows you to use OpenCypher (GQL) declarative query language to perform deep graph queries with complex constraints and aggregations, and to choose the format in which you would like your results to appear.
Access is via the Graph Search link in the main menu or the button in nav bar:
Writing queries
A cypher query describes a pattern or a series of patterns made up of nodes and edges in a graph. In Data Graphs, we build patterns from concept and relationship types, and return all paths through the graph that match that pattern.
The query editor allows you to write (or paste) a query manually into the UI:
Alternatively the model-aware query builder tool allows you to compose a query through a series of steps.
At every stage, selections made in the builder tool will update the contents of the query editor. And likewise, manual changes to the editor will update the builder tool.
Building a query
Generating a pattern
The first step is to define the concept and relationships types we would like to include in the query’s path pattern, along with its direction.
Let’s use the Data Graphs Media Graph sample project as an example. We can find the director of each movie by describing a path from Movie to Person via the director property on Movie.
- Select Movie as the first Concept Type
- Select director as the Relationship Type
- Select Person as the second Concept Type
This generates the following query:
The results show a list of all possible paths from movies to directors. These are two paths:
Expanding a query
From this basis we can expand the query by either extending the pattern or by creating another pattern.
- Extending the pattern
In the media graph example, we might want to know the country where each movie was made as well as its director.
Because we want to extend the pattern from the Movie rather than the Person, we need to change the pattern so that Movie is the “fulcrum”.
- Reset the values in the tool
- Switch the direction of the pattern to point upwards
- Select Movie as the origin Concept Type
- Select country as the Relationship Type
- Select Country as the target Concept Type
To add each movie’s director to the pattern:
- Click Extend Path
- Select director as the Relationship Type
- Select Person as the Concept Type
The query is updated as follows:
And the paths now show the country and director of each movie:
What if we also wanted to know about members of the cast of each movie? With the pattern as it is, we can’t extend it. Instead we build another one.
- Adding additional patterns
As we are interested in the value of cast which is a property of Movie, the new path will be a branch from Movie. To set this up:
- Click on the branch symbol next to Movie
- Select cast as the Relationship Type
- Select Person as the target Concept Type
The paths now include cast members:
This might be useful if the cast property contained only one value. But more often than not, cast will contain multiple values and it would be useful to be able to organize the results more efficiently.
Organizing results
The Result Format section allows you to change the way your results are displayed. The default selection is List of Paths as we have already seen:
Selecting List of Concepts & Relationships displays the latest results as follows:
Selecting Table of Properties allows us to view results as a table, and with this setting we will be able to list the cast members more efficiently.
In order to display the results of the existing query in a table, we have to indicate the property we are interested in for each column. Setting these as follows...
... displays the table:
For more meaningful column names, we can rewrite and reorder the return value in the query:
RETURN movie1.title as Movie, person1.name as Director, person2.name as CastMember, country1.name as Country
Aggregating results
We can generate standard aggregations of any of our returned values. For example, we can select collect(distinct__) on person1 and person2:
This will collect all the directors and cast members into a single entry for each movie:
If we then change the aggregation on person2.name to count(distinct__), we can just show the number of cast members in each move.
In this case it might be useful to sort the results by the number of cast members. This we can set at the bottom of the panel under Result Order, eg:
Adding constraints
Adding a constraint to the query filters the results to the value of a selected property.
In the Constraints section of the query builder tool, you can choose the variable, the operator and the value of a constraint. To return only movies made in France, for example:
- Click add constraints
- Select country1 and then name as constraining property
- Leave the operator as Equals
- Select Literal Value
- Type “France” as the matching value
Each constraint adds a corresponding WHERE clause to the query:
Combining constraints with boolean logic
We can combine constraints by adding an item or a group. To show movies made in either France or the USA:
- Click Add Item
- Switch the group type from AND to ANY by clicking on AND.
- Select country1 and then name as constraining property
- Leave the operator as Equals
- Select Literal Value
- Type “United States of America” as the matching value
Exporting Results
We can export Graph Search results by clicking the Export Results button at the top of the page. Depending on the way results are formatted in the query builder, they can be downloaded in either CSV or JSON Lines format.
After exporting, the file will be available for download immediately:
You can also download it at a later date from the project’s Exports page.
