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. Provenance records can be used and provenance records can optionally be included in the query results. 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.

Query the investigation's content

You can query the knowledge graph's entities and relationships in an investigation. You can optionally include provenance records in the query results.

1. Open an investigation and browse its content.
2. At the top of the investigation view, click in the search text box or press Ctrl+F, and click Query, if necessary.

   The expanded query window appears. This is a multiline query text box that allows you to format your openCypher query.

3. Type a query in the search text 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, to the maximum number of permitted. This query works with any knowledge graph.

   

4. Optionally, check Include Provenance to include provenance records that satisfy the query in the results.
5. Click Apply.

   The results of the query appear in the investigation view. Entities, relationships, and provenance records returned by the query are identified by the appropriate icons. The query is added to the history that appears at the bottom of the expanded query window.

6. Resize the expanded query window by dragging the divider between the window and the contents list.

   You can also use the buttons on the divider to use all the space for either the expanded query window or the contents list.

   

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.

Tailor a query to a specific knowledge graph by referencing the entity types, relationship types, and properties defined in its data model. Include the name of a specific entity type in your query to constrain the graph items that are considered. For example, the query MATCH (e1:Person)-[r]->(e2) RETURN e1,r,e2 will return all Person entities, e1, in which any relationship, r, connects the Person to another entity, e2, which can be an entity of any type. Compared to the previous example, relationships in which a Pet, Vehicle, or Document entity is the origin of a relationship aren't included in the results.

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.

You can learn more about the openCypher query language using a document provided by openCypher Implementers Group. ArcGIS Knowledge does not support all aspects of the openCypher query language. For example, queries can't be used to update the knowledge graph, only to return values.

In ArcGIS Pro, you can learn about openCypher by seeing the queries that retrieve data from a knowledge graph to build histograms. In the Search and Filter pane, on the Histogram tab , click the Settings button , and click Send query to Query tab. The query used to retrieve data for the current set of histograms appears in the Query text box.

Learn more about openCypher queries

Modify and update query results

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

1. Click in the expanded query window or press Ctrl+F.
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 Apply to get new results.

   The results of the query appear in the investigation. Entities and relationships returned by the query are identified by the appropriate icons. The query is added to the history that appears at the bottom of the expanded query window.

   

4. Click Clear to remove the text of the current query from the expanded query window.

   The three most recent queries that were performed are listed at the bottom of the expanded query window. The results of the most recent query are not removed.

5. Rerun or remove queries from your query history.
   1. Click a query in the list to run it again.

      

      The selected query appears in the query text box, runs automatically, and the results appear in the investigation.

   2. Click the Remove From History button for a specific query in the list to remove it from the history.

      

      The specified query is removed from the list. Your query history is updated to show the three most recent queries.

Save a query

As you write, revise, and run queries, a history of your queries is maintained. However, your entire query history is not saved with the project. You can save individual queries that you want to keep as part of your investigation.

1. Click the Query drop-down arrow and click <New Query>.
2. Click in the query text box and type a new query or modify an existing query.
3. Click Apply.

   The results of the query appear in the investigation.

   

4. Click Save at the top of the expanded query window.

   The Save query as dialog box appears.

5. Browse to the Investigations project container, to your investigation, to the Collections folder, and to the Queries folder. Type a name for the query in the Name text box and click Save.

   

   The query is saved in the Queries folder in your investigation. Your saved query is automatically selected in the Query drop-down list.

   

6. Click in the query text box and modify the existing query.
7. Click Save at the top of the expanded query window to update the saved query to reflect your changes.
8. Click in the query text box and modify the existing query.
9. Click Save As at the top of the expanded query window to save your changes as a new query.
10. Browse to the Investigations project container, to your investigation, to the Collections folder, and to the Queries folder. Type a name for the query in the Name text box and click Save.
11. Click the Project tab on the ribbon and click Save to save your investigation and the queries in the project.
12. Run a saved query.
    • Click a saved query in the investigation's Contents pane.
    • Click the Query drop-down list and click a saved query.

    The saved query appears in the query text box and is run automatically. The query results appear in the investigation.

    

Query a knowledge graph in the Search And Filter pane

The Search and Filter pane can be used with an investigation view to query its contents, with a map to query the contents of a knowledge graph layer, or with a link chart to query the entities and relationships it describes.

1. Open the Search and Filter pane using one of the following methods:

   From an investigation	On the Investigation tab on the ribbon, in the Search group, click Search And Filter .
   From a map	Click a knowledge graph layer in the map's Contents pane. Click the Knowledge Graph Layer contextual tab. In the Search group, click the Search And Filter button .
   From a link chart	On the Link Chart tab on the ribbon, in the Search group, click Search And Filter .

   The Search and Filter pane appears.

2. Click the Source drop-down list and click the investigation, map layer, or link chart whose knowledge graph you want to query.
3. Click the Query tab .

   When you pair an open investigation, map layer, or link chart with the Search and Filter pane, all queries are evaluated against the entire knowledge graph associated with the paired view. A message appears to remind you the query is not limited to the content available in the paired view.

   

4. Define a new query in the Query text box.

   • Type an openCypher query.

     

   • Click the Query drop-down arrow and click a saved query.

     

5. Optionally, check Include Provenance to include provenance records that satisfy the query in the results.
6. Click Apply.

   The results of the query appear in the Results list.

Tip:

Knowledge graphs can represent many entities and relationships. The busy indicator at the bottom of the Search and Filter pane shows the results list is being generated. When ArcGIS Pro is finished, the busy indicator stops and you see a Refresh Results button . If it takes too long to return the results of your query, you can stop building the results list by clicking the busy indicator.

By default, the Search and Filter pane may be too narrow to explore the results of the query. You can undock the pane to widen it without affecting the arrangement of other views and panes in the main ArcGIS Pro application window.

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 labeled as indicated in the query itself.

An openCypher query may return results that show which entities have a given relationship to another entity. In this case, the results list will have one line 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 result represents a person, a relationship between that person and another entity, and the target entity of the relationship. In this case, the results list would have a column for the person titled p, a column for the relationship titled r, and a column for the target entity titled e.

If instead, the query returns specific properties of entities or relationships, the results list will display those values in appropriately named columns as determined by the query. For example, a query such as MATCH (p:Person)-[ :HasVehicle]->(v) RETURN p,v,v.year will return the display name for the Person entity in column p, the display name of the Vehicle entity in column v, and the value of the Vehicle entity's year property in the columns v.year. If an entity doesn't have a value for a specific property that is returned by a query, you will see the value 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 p column. The acquisitionDate property of the HasVehicle relationship is displayed in the hv.acquisitionDate column. The value for the make property of the Vehicle entity appears in the v.make column.

If you query a knowledge graph from an investigation, use the details panel to view properties of the selected entity or relationship. From the details panel, you can explore other relationships and related entities that are not included in the query results.

If you query a knowledge graph from the Search and Filter pane, use the Histogram tab to summarize and filter the results. The title at the top of the tab is changed to Histogram - Query to indicate the charts presented represent the content returned by the query on the Query instead of the content from the paired view. Also, because the query is evaluated against the view's knowledge graph, a message appears indicating the histograms may include content not available from the paired view.

From either an investigation or the Search and Filter pane, you can select the entities or relationships of interest and right-click a selected graph item. Use the available options to add the selected graph items to a new or existing map or link chart for further analysis. Alternatively, select the corresponding items in an existing investigation, map, or link chart.