Query the contents of a knowledge graph

You can query a knowledge graph to find a subset of the entities and relationships it contains and identify how different entities are connected. See the following examples:

• From a knowledge graph representing the spread of an infectious disease, work with humans and animals associated through any relationship with a given facility.
• From a knowledge graph representing a manufacturing supply chain, work with any content associated with a specific part including suppliers, means of delivery, warehouses, and so on.
• From a knowledge graph representing an organization, work with devices of a given type, and list their properties, including the name of the responsible employee.
• From a knowledge graph representing tortoises and their habitats, identify habitats where the level of risk was established using information in a specific environmental impact assessment.

You can identify the subset of entities and relationships, or their properties, by querying the knowledge graph. Use openCypher query language to write openCypher queries to discover related entities and their properties and work with this restricted set of information in the knowledge graph, a map, or a link chart.

The Query view is a default view in every Knowledge Studio project that allows you to query the contents of the project's knowledge graph. The Query Contents (number 1 in the image below) lists the Query editor where you write new queries and the Stored Queries collection that are retained in the project when the project is saved. The query box (number 2 in the image below) is a multiline text box that allows you to format and run your openCypher query. The query Results (number 3 in the image below) are displayed in a table by default, which allows you to explore the properties of returned graph records (number 4 in the image below) and select records from your results. You can preview the results and your selections in the map or link chart previews and add or remove all results from your selection using the results toolbar (number 5 in the image below). The context toolbar (number 6 in the image below) provides tools specific to query, such as storing your query in your project for later use.

Query the investigation's knowledge graph

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

1. Click Query in the Investigation Contents pane to open the query view.

   The query view opens with the query box open and no results displayed. The query box is a multiline text box that allows you to format your openCypher query.

2. Type a query in the query box. Press Enter to move the pointer to a new line and continue typing.

   For example, a query such as MATCH (e) RETURN e would return all entities in the knowledge graph. This query works on any knowledge graph.

   Tip:

   If you don't know how many results will be returned from a query, add LIMIT 1000 to the end of your query to avoid unexpectedly returning tens of thousands of records, which may timeout your browser.

3. Click Run.

   The results of the query appear in the Results area. Entities and relationship records returned by the query are identified by the appropriate icons.

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.

1. Click in the query box.
2. Update the text of the existing openCypher query.

   For example, change the query to MATCH (p:Person)-[hv:HasVehicle]->(v:Vehicle) WHERE v.year < 2005 RETURN p, p.firstName, p.phoneNumber, hv, v, v.make, v.model, v.year to return all the Person entities that have the HasVehicle relationship to a Vehicle entity in which the year property of the Vehicle is earlier than 2005. The results will include values from the Person entity's firstName and phoneNumber properties, the HasVehicle relationship, and the Vehicle entity's make, model, and year properties.

   Press Enter to move the pointer or some of the query's text to a new line in the multiline text box. Use as many lines as needed for clarity.

   
3. Click Run to get new results.

   The results of the query appear in the Results section. Entities and relationships returned by the query are identified by the appropriate icons.

   
4. Optionally, click Clear to remove the text of the current query from the query box.

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.

1. Click Store as New Query in the query context toolbar.

   The new stored query modal appears.

   
2. Optionally:
   • Type a name for the query in the Title input area.
   • Type a description of the query in the Description text area. A description provides context for the query results without having to read the openCypher query.
3. Click Store.

   The query is stored under the Stored Queries section of the Query Contents pane.

4. Click the stored query to run the query and view the results.

   The stored query will run as soon as it is selected. The title and description of the query are provided above the results. The query box is hidden.

   
5. Click Show Query Box to show the openCypher query text in the query box.
6. Click in the query text box and modify the existing query.
7. Click Update Stored Query in the query context toolbar to update the stored query to reflect your changes.
8. Click the Options menu for this stored query in Query Contents.
9. Click Rename Item and Description to update the Title and Description text boxes of your query to reflect your changes.
10. Click Apply.
11. Optionally, click Delete in the Options menu for this stored query to remove the stored query from the project.

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.

1. Click an entity or a relationship in the results table to see it's properties.
2. Optionally, use Add Selection To to add this record to another content item.
3. Use the Add records to selection button in the Selection column to add all of the entities and relationships in that row to your selection.

   The entities and relationships in this row will be highlighted. Any instances of those entities and relationships that appear in other result rows will also be highlighted. The total number of selected records is displayed at the bottom of the table.

   
4. Optionally:
   • Press Ctrl while clicking an entity or relationship to add just that record from your selection.
   • Click Select All in the results menu to select all records returned from the query.
5. Use the Remove records from selection button in the Selection column to remove all of the entities and relationships in that row from your selection.
6. Optionally:
   • Press Ctrl while clicking an entity or relationship to remove just that record from your selection.
   • Click Clear Selection in the results menu to select all records returned from the query.
7. Use the Add Selection To in the query context toolbar to add your selected records to a link chart, map or data card.

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.

1. Click the Map view in the results menu to see a preview of the spatial entities returned by your query.
   
2. Click the Link Chart view in the results menu to see a preview of your query results visualized in a link chart.
   
3. Click the Table view in the results menu to return to the default results table.