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.

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 an investigation.
2. 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. Access the Data tab from the Knowledge Graph Layer tab on the ribbon. 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.

3. Click the Dataset drop-down list and click the name of the investigation, map, or link chart you want to query.
   • Click the name of the investigation in your project to explore the portion of the knowledge graph that currently appears in the investigation's contents list. For example, if the Person entity is currently selected in the investigation's Contents pane and the first 1,000 entities are listed, the histogram will represent content associated with the 1,000 Person entities only. If the investigation is named Investigation, the entry in the Dataset drop-down list would be Investigation.
   • Click the name of the knowledge graph layer on the map to explore the portion of the knowledge graph that currently appears on the map. For example, if the map only includes Person, Pet, and Veterinarian entities and the HasPet and HasPatient relationships, only these entity types and relationship types on the map are represented by the histograms. If the map is named Map and the knowledge graph layer on the map is named MyKnowledgeGraph, the entry in the Dataset drop-down list would be Map - MyKnowledgeGraph.
   • Click the name of the link chart to explore the portion of the knowledge graph that currently appears on the link chart. For example, if the link chart only includes a queried set of Person and Vehicle entities and the HasVehicle relationship, only the specific entities and relationships on the link chart are represented by the histograms. If the link chart is named Link Chart, the entry in the Dataset drop-down list would be Link Chart.
   • If you want to explore the entire knowledge graph that is referenced by the investigation, the knowledge graph layer on a map, or the link chart, click the entry corresponding to the view or map layer followed by Knowledge Graph. For example, if the map is named Map and the knowledge graph layer on the map is named MyKnowledgeGraph, the entry in the Dataset drop-down list corresponding to the entire knowledge graph would be Map - MyKnowledgeGraph.- Knowledge Graph.
4. Click the Query tab .
5. Type a openCypher query into the Query text box.
6. Click Apply.

   The results of the query appear in the Results list.

Tip:

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

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.

You can add entities and relationships returned by a query to a map or link chart for further analysis.