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 with each other. 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.

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.

Write an openCypher query

openCypher queries are to graph databases what SQL queries are to relational databases. For a basic example, consider a graph describing a company's products and the facilities where they are created. The automobile company has facilities that are entities, identified by the variable f; the models of vehicles it produces are entities, m; and, there is a relationship HasModel between the facility and the models it produces, hm.

• To find the first ten entities of the type Model, you can use a query such as MATCH (m:Model) RETURN m LIMIT 10.
• To discover which models are associated with which facilities, you can match the entities through the HasModel relationship with a query such as MATCH (f:Facility)-[ :HasModel]->(m) RETURN f,m.
• Your query can return specific properties of an entity or a relationship in addition to or instead of its display name. For example, to return the model of car as well as the model's category property, you could use a query such as MATCH (f:Facility)-[ :HasModel]->(m) RETURN f,m,m.category.

You can learn more about the openCypher query language using a document provided by Amazon. 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.

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.

Query the investigation's content

You can explore a smaller set of entities and relationships in an investigation by querying its content within the investigation view.

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.

   The search control appears.

   

3. Click Query Mode at the bottom of the search control.

   The hint in the search text box changes to Run graph query on knowledge graph, the Expand Query Window button appears, and Search Mode appears at the bottom of the search control.

   

4. Type a openCypher query in the search text box.

   For example, a query such as MATCH (p:Person)-->(v:Vehicle) RETURN p, v would return all the Person entities that have any sort of relationship to a Vehicle entity, and return the Person entity and the Vehicle entity in the results.

5. Press Enter.

   The results of the query appear in the investigation view.

   

6. Click in the query text box to modify the query and type your changes.

   For example, change the query to MATCH (p:Person)-[hv:HasVehicle]->(v:Vehicle) RETURN p, hv, v to return all the Person entities that have the HasVehicle relationship to a Vehicle entity, and return the Person entity, the HasVehicle relationship, and the Vehicle entity in the results.

   

7. Press Enter to run the modified query.

   The results of the updated query appear in the investigation view. Entities and relationships returned by the query are identified by the appropriate icons.

   

8. If you need more room to write a longer openCypher query, click the Expand Query Window button .

   The current query opens in a larger, multiline query text box instead of being directly in the one-line text box at the top of the control.

   

9. Type your changes to the query using as many lines as needed for clarity.

   For example, change the query to MATCH (p:Person)-[hv:HasVehicle]->(v:Vehicle) WHERE hv.acquisitionDate = NULL RETURN p, hv, v, v.make, v.model, v.year to return all the Person entities that have the HasVehicle relationship to a Vehicle entity where the acquisitionDate property of the HasVehicle relationship has a NULL value. Return the same entities and relationships as previously, but also include values from the Vehicle entity's make, model, and year properties in the results.

   The results of the updated query appear in the investigation view. Entities and relationships returned by the query are identified by the appropriate icons.

   

10. Click the Run Query button .

    When you use the expanded query window, pressing Enter will move the pointer to a new line in the multiline text box instead of running the query.

    The results of the query appear in the investigation view.

    

11. Click the Reset Search button in the query text box to clear the query and remove the results of the query.

    The graph items that were previously listed in the investigation view appear again.

12. When the query text box is empty, click in the query text box to open the query control and list the three most recent queries. Click a query in the list to run it again.

    

    The selected query is run and the results of the query appear in the investigation.

13. Click the Reset Search button in the query text box to clear the query from the query text box and remove its results from the investigation. Click in the empty query text box to open the query control, and 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.

14. If you no longer need the multiline query text box, click the Collapse Query Window button to the right of the query text box.

    When you modify a query, it will be updated directly in the query text box on one line. Press Enter to run an updated query.

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:
   • On the Investigation tab on the ribbon, in the Search group, click Search And Filter .
   • 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 .
   • 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. Type an openCypher query in the Query text box.
5. 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

A 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.

A openCypher query might 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 where 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 and a Vehicle entity, where the person participates in a HasVehicle relationship with the vehicle. The query also returns the acquisitionDate property of the HasVehicle relationship, and the make, model, and year properties of the Vehicle entity. If a property doesn't have a value, the text null appears in a column.

Columns containing an entity or a relationship , will show the display name for the graph item along with its icon. In the screen shot above, the Person and Vehicle properties returned appear in the p and v columns, respectively. The acquisitionDate property of the HasVehicle relationship is displayed in the hv.acquisitionDate column. Values for the make, model, and year properties of the Vehicle entities appear in v.make, v.model, and v.year columns, respectively.

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.