Query the investigation's knowledge graph

You can query the knowledge graph's entities and relationships in an investigation using the Query view .

Write an openCypher query

openCypher queries are to graph databases what SQL queries are to relational databases. The basic structure of the query is to find, or match, entities and return those entities, where the entities you want to find are identified in parentheses. For example, the query MATCH (e) RETURN e returns entities of any type. The number of entities returned is only limited by the knowledge graph's configuration. To restrict the number of graph items returned, use a LIMIT expression. For example, the query MATCH (e) RETURN e LIMIT 5 will return five entities of any type.

The query can identify entities that are related using symbols that create an arrow. For example, the query MATCH (e1)-->(e2) RETURN e1,e2 will return pairs of entities, e1 and e2, where any type of relationship exists between the two entities and any path from entity e1 to entity e2 connects the entities. If the query was written with the arrow pointing in the other direction, paths would be considered starting from the origin entity e2, to the destination entity e1: MATCH (e1)<--(e2) RETURN e1,e2. The manner in which entities are related to each other is referred to as a pattern.

The query can identify specific relationships that should be considered in square brackets. For example, the query MATCH (e1)-[]->(e2) RETURN e1,e2 will return pairs of entities, e1 and e2, where a single relationship of any type connects the two entities. This query shows another way to represent the same queries illustrated above, and illustrates the preferred query syntax. The query can be amended to return the entire tuple describing the relationship by returning the origin entity, e1, the relationship, r, and the destination entity, e2, as follows: MATCH (e1)-[r]->(e2) RETURN e1,r,e2. Similar queries MATCH (e1)-[ ]->( )-[ ]->(e2) RETURN e1,e2 or MATCH (e1)-[*2]->(e2) RETURN e1,e2 will return pairs of entities that are connected by two relationships in the same direction. Queries can also identify patterns where relationships have different directions such as MATCH (e1)-[ ]->(e2)<-[ ]-(e3) RETURN e1,e2,e3.

The example queries above can be used with any knowledge graph.

You can constrain the query to consider specific relationship types and specific related entities by adding relationship types and entity types to the other facets of the query. For example, MATCH (p:Person)-[v:HasVehicle]->(e) RETURN p,v,e will return all Person entities, p, in which a HasVehicle relationship, v, connects the Person to another entity of any type, e. The variables p and v are assigned to the Person entities and HasVehicle relationships, respectively, so information about them can be returned by the query. Compared to the previous example, relationships in which a Pet or Document entity are the destination of a relationship aren't included in the results. Depending on the knowledge graph's data model, the destination entity, e, could be a generic Vehicle entity, or it could be one of a series of specific entity types such as Automobile, Motorcycle, Boat, Airplane, Commercial Vehicle, and so on.

Specific properties of entities and relationships can be included in the query results. For example, MATCH (p:Person)-[:HasVehicle]->(e) RETURN p,e.make,e.model,e.year will run the same query defined previously. However, instead of showing the destination entity itself, the results will show the values stored in several of its properties: the make, model, and year of the vehicle, respectively. In this example, a variable was not assigned for the specific relationship being considered by the query because the relationship's data is not included in the query results or evaluated elsewhere in the query.

Similarly, you can constrain the entities and relationships that are evaluated by specifying properties that define the entities and relationships of interest. The properties to consider are defined by adding a WHERE clause to the query. As with the examples above, variables must be assigned to reference specific information about entities and relationships in the WHERE clause. For example, in the following query, only Person entities with a specific lastName property value are evaluated; HasVehicle relationships are only considered if they have a NULL value in the endDate property; and related Vehicle entities are only considered if the year property has a value that is earlier than 1980: MATCH (p:Person)-[hv:HasVehicle]->(v:Vehicle) WHERE p.lastName = 'Doe' and hv.endDate IS NULL and v.year < 1980 RETURN p,p.firstName,v,v.make,v.year.

Instead of returning a series of individual entities and relationships, your query can return the complete path represented by a pattern. To do this, assign the pattern defined in the MATCH statement to a variable and return that variable. For example, the query MATCH path = (:Person)-[:HasVehicle]->(:Vehicle) RETURN path will return a list of paths for all entity and relationship combinations that satisfy the specified pattern. Each path will contain all parts of the matched pattern: the Person, HasVehicle relationship, and Vehicle. You do not need to assign variables to the individual parts of this pattern since they are not returned by the query.

Modify and update query results

You can retrieve a focused set of entities and relationships in a knowledge graph by evaluating specific graph item types and specific property values.

Store a query

You can store individual queries that you want to keep as part of your investigation. When you save your project your stored queries are saved in the project and listed in the Stored Queries section of the Query Contents pane.

Explore query results

An openCypher query can return a variety of results. When the query returns a list of entities or relationships, they are displayed in the results list with one entity or relationship per row. Values returned by the query appear in columns in the order they are listed in the query return statement.

An openCypher query may return results that show which entities have a given relationship to another entity. In this case, the results table will show one row for each triple where a triple consists of the origin entity, the relationship, and the target entity. For example, a query such as MATCH (p:Person)-[r]->(e) RETURN p,r,e would return a results list in which each row in the results table represents a person, a relationship between that persona and another entity, and the target entity of the relationship. In this case, the results table would have a column for the person titled Value 0, a column for the relationship titled Value 1, and a title for the target entity titled Value 2.

If instead, the query returns specific properties of entities or relationships, the results list will display those values in each column. For example, a query such as MATCH (p:Person)-[:HasVehicle]->(v) RETURN p,v,v.year will return the display name of the Person entity in the Value 0 column, the display name of the Vehicle entity in the Value 1 column, and the value of the Vehicle entity's year property in the Value 2 column. If an entity doesn't have a value for a specific property that is returned by a query, you will see (NULL) as a representation of the fact that there is no value to show.

The example below illustrates a query that returns a Person entity in which the person participates in a HasVehicle relationship with the vehicle. The query also returns the acquisitionDate property of the HasVehicle relationship, and the make property of the Vehicle entity.

Columns containing an entity or a relationship will show the display name for the graph item along with its icon. In the screenshot above, the Person entity returned appears in the Value 0 column. The acquisitionDate property of the HasVehicle relationship is displayed in the Value 1 column. The value for the make property of the Vehicle entity appears in the Value 2 column.

A third common type of query returns a path between one entity and another. A path contains all entities and relationships between the specified origin and destination entities. For example, a query such as MATCH path=(p:Person)-[r]->(e) RETURN path will return all of the paths to any entities connected to a Person entity by one relationship. The query results table will display the path in the Value 0 column.

Paths can include any number of entities and relationships. For example, a query such as MATCH path=(c:Company)-[r*2]-(v:Vehicle) RETURN path will return all paths between Company entities and Vehicle entities that are exactly two relationships away. Each path will contain the origin Company entity, each intermediary entity and relationship, and the destination Vehicle entity. The query results table will display the path in the Value 0 column. By default, it will just display the origin entity and destination entity in the path and the total number of records in the path. Click the Expand to view the full path result.

Paths can be returned as one element of a query result. For example, the same query can return the path and the name of the origin company and the year of the destination vehicle. MATCH path=(c:Company)-[r*2]-(v:Vehicle) RETURN path, c.name, v.year. The query results table will display the collapsed path in the Value 0 column, the Company entity's name property in the Value 1 column, and the Vehicle entity's year property in the Value 2 column.

All query results are displayed in the table view by default. In this view, you can select query results, and view the properties of any entity or relationship returned from the query.

Preview the results in a map or link chart

You can also use the query results map preview and query results link chart preview to preview the results of your query in a different visualization. Any selections made in the table view will be reflected in the map preview and link chart preview.