knowledgeGraphService

AMD: require(["esri/rest/knowledgeGraphService"], (knowledgeGraphService) => { /* code goes here */ });
ESM: import * as knowledgeGraphService from "@arcgis/core/rest/knowledgeGraphService.js";
Object: esri/rest/knowledgeGraphService
Since: ArcGIS Maps SDK for JavaScript 4.25
beta

A knowledge graph service is associated with several resources. One resource is a knowledge graph, which contains entities and relationships. Another resource is the data model that defines the entity types and relationship types in the graph. A third resource is the service definition which outlines the capabilities of the service. A knowledge graph service allows users to query both the knowledge graph and the data model. Entities and relationships can be added, updated or deleted from the knowledge graph using executeApplyEdits(). To visualize knowledge graph data on map, see knowledge graph layer.

Known Limitations

KnowledgeGraphService capabilities in version 4.26 of the SDK for Javascript are only supported against ArcGIS Enterprise version 11.1 and later. KnowledgeGraphService capabilities in version 4.25 of the SDK for Javascript are supported on ArcGIS Enterprise version 11.0 and earlier.

See also
Example
require([
 "esri/rest/knowledgeGraphService"
], (knowledgeGraphModule) => {
 var knowledgeGraph;
 // define url to knowledge graph service
 const url = "https://myHostName.domain.com/server/rest/services/Hosted/myServiceName/KnowledgeGraphServer";
 // fetch knowledge graph
 KnowledgeGraphModule.fetchKnowledgeGraph(url)
  .then((kg) => {
    // do something with result
    knowledgeGraph = kg;
    console.log(knowledgeGraph);
 });
})

Method Overview

Name Return Type Summary Object

Add, delete, or update entities and relationships in a knowledge graph service's graph resource.

knowledgeGraphService

Executes a query on knowledge graph service's graph resource using the Esri implementation of openCypher and returns the results.

knowledgeGraphService

Execute a streaming query on a knowledge graph service's graph resource.

knowledgeGraphService

Search the knowledge graph using a full-text index that is automatically built on the property values in the graph and returns the result.

knowledgeGraphService

Execute a streaming search on a knowledge graph service's graph resource.

knowledgeGraphService

Retrieves the knowledge graph service based on the URL provided.

knowledgeGraphService

Refreshes the data model of the knowledge graph.

knowledgeGraphService

Method Details

executeApplyEdits

Method
executeApplyEdits(graph, edits, requestOptions){Promise<GraphApplyEditsResult>}

Add, delete, or update entities and relationships in a knowledge graph service's graph resource. This operation does not allow adding or deleting properties for entity types or relationship types. However, users can update an entity or relationship to change its property values.

Note

  • The user must have sufficient privileges to edit content and editing must be enabled for the knowledge graph service for this operation to be successful.
Parameters

The knowledge graph associated with the service. See also ArcGIS REST APIs - Hosted Knowledge Graph Service.

Specifies the entities and relationships and their properties to add, update or delete.

requestOptions RequestOptions
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<GraphApplyEditsResult> When resolved, the result is a GraphApplyEditsResult.
Examples
// sample executeApplyEdits() to add a new entity to the `Supplier` entity type
const newEntity = new Entity({
  typeName: "Supplier",
  properties: {
    Name: "Supplier 5",
    EmployeeCount: 681
  }
});
KnowledgeGraphModule.executeApplyEdits(
  graph, {
      entityAdds: [newEntity]
    })
    .then((editResult) => {
      console.log("Graph Add Result", editResult);
    });
});
// Basic example results of adding one entity to the `Supplier` entity type
{
  editResults:[{
    adds:[
    {
      id: "{A1W5F4A8S-41F1-49A4-8412-ANIWN9906E88}",
      error: false
    }],
    deletes:[],
    typeName: "Supplier",
    updates:[]
  }],
  hasError: false,
  error: undefined
}
//update existing records
const updateEntity = new Entity({
  typeName: "Supplier",
  // update the EmployeeCount from 681 to 685
  properties: {
    Name: "Supplier 5",
    EmployeeCount: 685
  },
  id:"{A1W5F4A8S-41F1-49A4-8412-ANIWN9906E88}" //id of entity already in knowledge graph
});
const updateRelationship = new Relationship({
  typeName: "buys_part",
  properties: {
    quantity: 5000
  },
  // origin and destination entities must already exist in the graph
  originId: "{AN4E4G85-41F1-49A4-8412-CACCC9906E88}",
  destinationId: "{9D2D6AFD-41F1-49A4-8412-1DGR8E5D6S1G4}"
});
KnowledgeGraphModule.executeApplyEdits(
  graph, {
      entityUpdates: [updateEntity],
      relationshipUpdates: [updateRelationship]
    })
    .then((editResult) => {
      console.log("Graph Update Result", editResult);
    });
});
//delete existing records
KnowledgeGraphModule.executeApplyEdits(
  graph, {
      entityDeletes: [{
        typeName: "Supplier",
        ids: ["{AMGIE541G-41F1-49A4-8412-CACCC9906E88}", "{HNWIGHE15-WH52-2GE6-1A5W-A1F8W4FS3A1S5}"]
      },{
        typeName: "Part",
        ids: ["{FNIW4GF1-ANFW-49A4-ANW7-GNWIGHAF4S51FS}"]
      }],
      relationshipDeletes: [{
        typeName: "Buys_part",
        ids: ["{MH4E54G8E-MF4W-1842-2S44-15AF5W8F4S2W8}"]
      }],
      //delete all relationships connected to the deleted entities.
      options:{
        cascadeDelete: true
      }
    })
    .then((editResult) => {
      console.log("Graph Delete Result", editResult);
    });
});

executeQuery

Method
executeQuery(graph, queryArguments, requestOptions){Promise<GraphQueryResult>}

Executes a query on knowledge graph service's graph resource using the Esri implementation of openCypher and returns the results.

Parameters

The knowledge graph associated with the service. See also ArcGIS REST APIs - Hosted Knowledge Graph Service.

queryArguments GraphQuery

Defines the query to perform on the provided knowledge graph service.

requestOptions RequestOptions
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<GraphQueryResult> When resolved, the result is an GraphQueryResult.
Example
// typical use case
KnowledgeGraphModule.executeQuery(
 knowledgeGraph, //graph
 { // queryArguments
   openCypherQuery: "MATCH (n) RETURN n LIMIT 100", //query
  }).then((queryResult) => {
    // do something with the result
});

executeQueryStreaming

Method
executeQueryStreaming(graph, queryArguments, requestOptions){Promise<GraphQueryStreamingResult>}

Execute a streaming query on a knowledge graph service's graph resource. Streaming query returns a readable stream that must be read to access the returned graph data. Unlike executeQuery(), executeQueryStreaming() returns results in small chunks that can be processed immediately, without waiting for all results to be returned. Streaming query is faster and more efficient than executeQuery(). Streaming query also retrieves all matching records even if the total exceeds the maxRecordCount defined in the service without additional queries or pagination. Another benefit of streaming query is that the query is encoded which means that it is far smaller than a traditional HTTP GET or JSON POST body. This is especially important when trying to do a query on a very large argument, such as a large set of Ids or intersecting a complex geometry.

The entities and relationships in the graph are queried by sending an Esri implementation of openCypher query.

Parameters

The knowledge graph associated with the service. See also ArcGIS REST APIs - Hosted Knowledge Graph Service.

queryArguments GraphQueryStreaming

Defines the query to perform on the provided knowledge graph service. Optionally specify additional query parameters

requestOptions RequestOptions
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<GraphQueryStreamingResult> When resolved, the result is an GraphQueryStreamingResult.
Examples
// sample streaming query using bind parameters
// to search for entities with a the `name` property that matches a specific string
// or have their geometry within a bounding box.
// get all parts bought by each supplier.
// query returns both the supplier and the part it buys.
const query = `MATCH (s:Supplier)-[:buys_part]-(p:Part)
               WHERE s.name=$name OR esri.graph.ST_Intersects($geom, s.geometry)
               RETURN s,p`;

KnowledgeGraphModule.executeQueryStreaming(
  knowledgeGraph,
  {
    openCypherQuery: query,
    bindParameters: {
      name: "Supplier 5",
      //bounding box around the area of Washington DC, USA
      geom: new Polygon({
        rings: [
          [
            [38,-78],
            [39, -78],
            [39, -76],
            [-38, -76],
            [-38, -78],
          ],
       ],
    }),
  }
}).then((streamingQueryResult)=>{
  // streaming query returns a readableStream which must be read to access the returned graph data
  readStream(streamingQueryResult)
});
// a function to read the readable stream returned from the above query
const readStream = async (streamingQueryResult) => {
  let time = Date.now();
  let reader = streamingQueryResult.resultRowsStream.getReader();
  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) {
        console.log(`Completed database requests: ${(Date.now() - time) / 1000} seconds`);
        break;
      }
      console.log(`Chunk returned in: ${(Date.now() - time) / 1000} seconds`);
      // use the results
      // list the parts bought by each supplier
      let supplierParts = {};
      // each element of the result array will contain one supplier and one part it buys
      for (var v in value){
        let supplier = value[v][0].properties.Name
        let part = value [v][1].properties.Name
        if(!(supplier in supplierParts)){
          supplierParts[supplier] = [];
        }
        // collect parts by supplier that buys them
        supplierParts[supplier].push(part);
        console.log(supplierParts);
        // result printed to the console: {Supplier 1:[Part1], Supplier 3:[Part2, Part3]}
    }
  } catch (err) {
    if (err.name === "AbortError") {
      console.log("Request aborted as expected");
    } else {
      throw err;
    }
  }
};
// result stream from above query after it has been read
"Streaming chunk returned in: 0.082 seconds"
[
  [{
    "declaredClass": "esri.rest.knowledgeGraph.Entity",
    "properties": {
      "Name": "Supplier 1",
      "City": "Washington DC",
      "EmployeeCount": 31
    },
    "typeName": "Supplier",
    "id": "{57FDF2F3-34C8-48EF-9A3B-76ED9314C4D2}"
  },{
    "declaredClass": "esri.rest.knowledgeGraph.Entity",
    "properties": {
      "Part_ID": 695401,
      "Name": "Part1",
      "Minimum_quantity": 360
    },
    "typeName": "Part",
    "id": "{IWN51W4-1AW8-A2W6-1AW5F-1AW8F9F4W51AS}",
  }],
  [{
    "declaredClass": "esri.rest.knowledgeGraph.Entity",
    "properties": {
      "Name": "Supplier 2",
      "City": "Baltimore",
      "EmployeeCount": 53
    },
    "typeName": "Supplier",
    "id": "{1A4W8F5W-1WA8-5W6A-A1W8-A1W5F8W3S482A}"
  },{
    "declaredClass": "esri.rest.knowledgeGraph.Entity",
    "properties": {
      "Part_ID": 695401,
      "Name": "Part2",
      "Minimum_quantity": 2500
    },
    "typeName": "Part",
    "id": "{A1W5F8W4F-A1W8-1894-16A5-A86WF4A8SFWD}",
  }],
  [{
    "declaredClass": "esri.rest.knowledgeGraph.Entity",
    "properties": {
      "Name": "Supplier 2",
      "City": "Baltimore",
      "EmployeeCount": 53
    },
    "typeName": "Supplier",
    "id": "{1A4W8F5W-1WA8-5W6A-A1W8-L5H4G8RT1PK3}"
  },{
    "declaredClass": "esri.rest.knowledgeGraph.Entity",
    "properties": {
      "Part_ID": 695401,
      "Name": "Part3",
      "Minimum_quantity": 5000
    },
    "typeName": "Part",
    "id": "{PTJ51FT-KY4H-1GY5-G1Y8-G1Y5K49G8Y4GHJ}",
  }]
]
// aborting the query
// create instance of native browser abort controller
const controller = new AbortController();

// create query
KnowledgeGraphModule.executeQueryStreaming(
    knowledgeGraph,
    {
      openCypherQuery: "MATCH (n) RETURN n LIMIT 100",
    },
    {
      signal: controller.signal,
    }
  )
  .then((streamingQueryResult) => {
    readStream(streamingQueryResult);
  })
  // indicate that the stream was aborted
  .catch((err) => {
    if (err.name === "AbortError") {
      console.log("Request aborted as expected");
    }

// abort the query after half a second
setTimeout(() => {
  console.log("Sending abort signal");
  controller.abort();
}, 500);

executeSearch

Method
executeSearch(graph, searchArguments, requestOptions){Promise<GraphQueryResult>}

Search the knowledge graph using a full-text index that is automatically built on the property values in the graph and returns the result. Search accepts Lucene search syntax. Use the DataModel to see the indexed fields for each RelationshipType and EntityType.

Parameters

The knowledge graph associated with the service. See also ArcGIS REST APIs - Hosted Knowledge Graph Service.

searchArguments GraphSearch

Defines the free text search to run against a knowledge graph.

requestOptions RequestOptions
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<GraphQueryResult> When resolved, the result is a GraphQueryResult that contains all records matching the search. If there are no matches the result will be empty.
Examples
// typical use case
KnowledgeGraphModule.executeSearch(
 knowledgeGraph, //graph
 { // searchArguments
   searchQuery: "Sun", //search term
   typeCategoryFilter: "both" //search entities, relationships or both.
  }).then((searchResult) => {
    // do something with the result
   console.log(searchResult)
});
// sample search result
{
  "declaredClass": "esri.rest.knowledgeGraph.GraphQueryResult",
  "resultRows": [
    [
      {
        "declaredClass": "esri.rest.knowledgeGraph.Entity",
        "properties": {
          "shape": {
            "declaredClass": "esri.geometry.Point",
            "cache": {},
            "hasM": false,
            "hasZ": false,
            "latitude": 53.589000000000006,
            "longitude": -0.9633,
            "type": "point",
            "extent": null,
            "spatialReference": {
              "wkid": 4326
            },
            "x": -0.9633,
            "y": 53.589000000000006
          },
          "Name": "Suncommon",
          "Employee_Count": 400
        },
        "typeName": "Company",
        "id": "{WIPJ483T-U8UI-LLK9-YUI8-Y5YK8YGD88E9}",
      }
    ],
    [
       {
        "declaredClass": "esri.rest.Relationship.Relationship",
        "originID": "{44027400-4B48-4FF2-B526-E27FC17EC246}",
        "destinationID": "{CB0CF580-3899-491E-8F10-0AD1DA4EE49B}",
        "properties": {
          "orderDay": "Sunday",
          "quantity": 15000
        },
        "typeName": "buys_part",
        "id": "{ABCDEFG-0000-1111-2222-0AD1DA4EE49B}"
      }
    ]
  }

executeSearchStreaming

Method
executeSearchStreaming(graph, searchArguments, requestOptions){Promise<GraphQueryStreamingResult>}

Execute a streaming search on a knowledge graph service's graph resource. Streaming search returns a readable stream that must be read to access the returned data. Unlike executeSearch(), executeSearchStreaming() returns results in small chunks that can be processed immediately, without having to wait for all results to be returned. Streaming search is faster and more efficient than executeSearch(). Streaming search also retrieves all matching records even if the total exceeds the searchMaxRecordCount defined in the service without additional queries or pagination. Another benefit of streaming search is that the request is encoded which means that it is far smaller than a traditional HTTP GET or JSON POST body. This is especially important when trying to do a search on a very large argument, such as a large set of Ids.

Streaming search accepts Lucene search syntax. Streaming search uses a full-text index that is automatically built on the property values in the graph. Use the DataModel to see the indexed fields for each RelationshipType and EntityType.

Parameters

The knowledge graph associated with the service. See also ArcGIS REST APIs - Hosted Knowledge Graph Service.

searchArguments GraphSearchStreaming

Define the free text search to execute against the knowledge graph. Optionally specify additional search parameters.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<GraphQueryStreamingResult> When resolved, the result is a GraphQueryStreamingResult that contains all records matching the search. If there are no matches the result will be empty.
Examples
// example search for "solar"with additional parameters
KnowledgeGraphModule.executeSearchStreaming(
  knowledgeGraph,
  {
    searchQuery: "solar",
    typeCategoryFilter: "both",
    returnSearchContext: false,
    start: 1,
    num: 200, //return 200 records.
    namedTypesFilter: ["Company", "Supplier", "Part"],
    idsFilter: ["{G4E8G2S8D-2GS5-98S4-3S5D-S1DE7G45DS48}",
                     "{FNWI1G5W-1A5W-3A5W-8412-A1W5F4W8F7AS}",
                     "{9D2D6AFD-41F1-49A4-8412-CACCC9906E88}"]
  }
).then((streamingSearchResult)=>{
  // the result of a streaming search is a readableStream which requires decoding.
  readStream(streamingSearchResult)
})
// a function to read the readable stream returned from the above query
const readStream = async (streamingQueryResult) => {
  let time = Date.now();
  let reader = streamingQueryResult.resultRowsStream.getReader();
  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) {
        console.log(`Completed database requests: ${(Date.now() - time) / 1000} seconds`, value);
        break;
      }
      console.log(`Chunk returned in: ${(Date.now() - time) / 1000} seconds`, value)
    }
  } catch (err) {
    if (err.name === "AbortError") {
      console.log("Request aborted as expected");
    } else {
      throw err;
    }
  }
};
// sample result of streaming search result chunk read and printed to the console

"Streaming chunk returned in: 0.082 seconds"
[
  [{
    "declaredClass": "esri.rest.knowledgeGraph.Entity",
    "properties": {
      "Name": "Suncommon",
      "Employee_Count": 400,
      "energyType": "solar"
    },
    "typeName": "Company",
    "id": "{G4E8G2S8D-2GS5-98S4-3S5D-S1DE7G45DS48}"
  }],
  [{
    "declaredClass": "esri.rest.knowledgeGraph.Entity",
    "properties": {
      "Name": "Quality Solar Supply",
      "Supplier_code": "158B",
      "City": "New Orleans",
    },
    "typeName": "Supplier",
    "id": "{FNWI1G5W-1A5W-3A5W-8412-A1W5F4W8F7AS}"
  }],
  [{
    "declaredClass": "esri.rest.knowledgeGraph.Entity",
    "properties": {
      "Name": "Solar panel",
      "panel_type": "Polycrystalline",
      "price_per_unit": 400
    },
    "typeName": "Part",
    "id": "{9D2D6AFD-41F1-49A4-8412-CACCC9906E88}"
  }]
]

fetchKnowledgeGraph

Method
fetchKnowledgeGraph(url){Promise<KnowledgeGraph>}

Retrieves the knowledge graph service based on the URL provided.

Parameter
url String

URL to the ArcGIS Knowledge Server REST resource that represents a knowledge graph service.

Returns
Type Description
Promise<KnowledgeGraph> When resolved, the result is a KnowledgeGraph.
Example
// typical use case
const url = "https://myHostName.domain.com/server/rest/services/Hosted/myServiceName/KnowledgeGraphServer";

KnowledgeGraphModule.fetchKnowledgeGraph(url)
.then((kg) => {
    // do something with result
});

refreshDataModel

Method
refreshDataModel(graph)

Refreshes the data model of the knowledge graph.

Parameter

The knowledge graph associated with the service. See also ArcGIS REST APIs - Hosted Knowledge Graph Service.

Example
// typical use case
KnowledgeGraphModule.refreshDataModel(urlToKnowledgeGraph).then((newKG) => {
    // do something with result
});

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.