Working with KnowledgeGraphLayer

Getting Started

Knowledge graphs allow you to model real-world systems that contain both spatial and nonspatial entities--such as people, places and things--and the relationships that connect them, allowing you to leverage both spatial and nonspatial tools in your analysis. A knowledge graph allows you work with a graph network. Both entities and relationships are objects in the graph data structure and can have associated properties. Entity types can be defined with or without spatial information. Spatial entities can be connected to nonspatial entities, but when knowledge graph data is added to a map only spatial entities are drawn. To visualize both spatial and nonspatial data and how they are connected, see link charts.

A KnowledgeGraphLayer is a composite layer that represents a knowledge graph service on a map. The layer contains sublayers for each entity type and relationship type contained in the KnowledgeGraphLayer.

The sample dataset contains observations of bumble bees made at locations around the United States. Each observation was made and verified by users and is of a specific species of bumble bee.

How it works

To create a KnowledgeGraphLayer from a knowledge graph service, set the url property to the REST endpoint of the service. A KnowledgeGraphLayer also optionally takes an inclusion definition. The inclusion definition specifies a set of entity or relationship types and/or specific entities and relationships to be included in the layer. This sample illustrates how to use an inclusion definition to only include the research grade Observations in the layer. These specific observations are determined by first querying the knowledge graph to get just the observations who's property quality_grade is "research". See KnowledgeGraphLayer.inclusionModeDefinition for more on inclusion lists. The inclusionModeDefinition is optional. If excluded, all entity and relationship types will be included as sublayers. All spatial entity types will be drawn on the map. Any non spatial entity types and all relationship types will be included as table sublayers and will not be drawn on the map.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
//Define an inclusion list that limits the layer to the results returned from the query. An inclusion definition is an optional configuration property
// that initializes the layer with an explicitly defined subset of records.
 let members = new Map();
let memberslist = new Map();
for (const result of results.resultRows) {
      //for each result, add the returned record ids to a map by their entity type or relationship type
      for (const index in result) {
        const record = result[index];
        if (!memberslist.has(record.typeName)) {
          memberslist.set(record.typeName, { useAllData: false, members: new Map() });
        }
        memberslist.get(record.typeName).members.set(record.id, { id: record.id });
      }
    }

    //only create a sublayer for the specified named types.
    const inclusionDef = {
      //only generate sublayer for the entity types and relationship types of records returned in the query
      generateAllSublayers: false,
      namedTypeDefinitions: memberslist
};

//create the layer
//the inclusionModeDefinition is an optional property for layer construction. If not defined, all records in the graph will be included.
//Any non spatial entity types and all relationship types will be included as table sublayers and will not be drawn on the map
const kgLayer = new KnowledgeGraphLayer({
    url: url,
    inclusionModeDefinition: inclusionDef //optional
});

Knowledge graph layers are generated with default symbology and labels. You can optionally enable popups and or apply specific configurations to individual sublayers once the layer is loaded.

1
2
3
4
5
6
7
//Once the layer has loaded, you can enable popups or change the configuration of a specific sublayer.
//This is optional
await kgLayer.load()
kgLayer.layers.forEach((sublayer) => {
    sublayer.popupTemplate = sublayer.createPopupTemplate();
});
map.add(kgLayer);