Knowledge graph
Every knowledge base has a knowledge graph: a network of nodes (the things the KBase knows about) joined by edges (the relationships between them). Nodes carry attributes holding values, and may carry an existence describing when the thing existed in time, which is read and written with the time tools. Nodes and edges are typed by a lineage drawn from a shared taxonomy of concepts.
The graph is built automatically as content is indexed, but these tools let an agent read it and curate it by hand.
Whole graph
Nodes
- CreateNode
- GetNodeCore
- GetGraphObject
- UpdateNode
- DeleteNode
- AnnotateNode
- AnnotateNodeFromUrl
- AnnotateNodeFromFile
Node attributes
Place
Edges
Gets the whole graph structure for a knowledge base.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
Returns
The graph as a set of nodes and edges in Cytoscape form, suitable for visualisation or traversal.
Gets the graph as it stood at a particular moment: only the nodes that existed on the given date, according to their existence data, are returned.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
iso8601date | string | An ISO 8601 Extended date, where negative years are BCE dates. |
Returns
The filtered graph, in the same form as GetGraph. An invalid or missing date fails with Invalid date.
Gets the locations recorded for the nodes of a knowledge base. If a date is supplied, only the locations of nodes that existed on that date, according to their existence data, are returned.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
iso8601date | string (optional) | An ISO 8601 Extended date, where negative years are BCE dates. Omit it to get every location. |
Returns
A list of locations, or an empty list if none have been set. An unparseable date fails with Invalid date format. For the locations of a single node, use GetNodeLocations.
CreateNode
destructiveCreates a new node in the graph of a knowledge base.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeName | string | The name of the node. |
lineage | string | The lineage that types the node. Find one with the lineage tools. |
Returns
The Id of the new node. An unrecognised lineage is rejected.
GetNodeCore
Try itGets the core information for a node — its name, lineage and identity — without its attributes.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node. |
Returns
The node's core record. An unknown node fails with Node not found.
GetGraphObject
Try itGets a complete graph object by its Id, including everything attached to it.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
objectId | string | The Id of the graph object. |
Returns
The complete graph object.
UpdateNode
destructiveRenames a node and/or changes the lineage that types it.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node to update. |
nodeName | string | The new name of the node. |
lineage | string | The new lineage of the node. |
Returns
true if the node was updated.
DeleteNode
destructiveDeletes a node from the graph.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node to delete. |
Returns
true if the node was deleted; an unknown KBase or node fails with KBase or Node not found.
AnnotateNode
destructiveAnnotates a node using a piece of text: the server reads the text and enriches the node with the attributes and relationships it finds there.
If the client supplies a progress token, progress updates are reported as MCP progress notifications while annotation runs.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node to annotate. |
text | string | The text to annotate the node with. |
linkedNodes | boolean | Whether related nodes found in the text should also be created and linked to this node. Required: pass false to annotate this node only. |
nodeTypes | string (optional) | Which kinds of related node to create when linkedNodes is true: real, abstract or both. |
Returns
The annotated graph object.
AnnotateNodeFromUrl
destructiveAs AnnotateNode, but the text is fetched from a web page.
If the client supplies a progress token, progress updates are reported as MCP progress notifications while annotation runs.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node to annotate. |
url | string | The URL whose content should be used. |
nodeTypes | string (optional) | Which kinds of related node to create and link: real, abstract, both, or none to annotate this node only. Defaults to none. |
Returns
The annotated graph object.
AnnotateNodeFromFile
destructiveAs AnnotateNode, but the text is taken from a PDF document held in file share or blob storage.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node to annotate. |
fileName | string | The file name of the document, which must be a PDF, for example handbook.pdf. |
blobUrl | string | The URL of the document in a file share, blob storage and so on. |
nodeTypes | string (optional) | Which kinds of related node to create and link: real, abstract, both, or none to annotate this node only. Defaults to none. |
Returns
The annotated graph object.
GetNodeAttributes
Try itGets all the attributes held by a node.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node. |
Returns
A list of attributes, each with its Id, name, lineage, datatype and value.
UpsertNodeAttribute
destructiveAdds an attribute to a node, or updates it if an attribute with that Id already exists ("upsert").
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node. |
attributeId | string | The Id of the new or existing attribute. |
attributeValue | string | The value of the attribute. |
attributeName | string | The name of the attribute. |
attributeLineage | string | The lineage that types the attribute. |
attributeDatatype | string | One of numeric, categorical, textual, sequence, temporal, duration or markdown. |
Returns
true if the attribute was written.
DeleteNodeAttribute
destructiveDeletes an attribute from a node.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node. |
attributeId | string | The Id of the attribute to delete. |
Returns
true if the attribute was deleted.
GetNodeLocations
Try itGets the location data recorded for a single node: where in the world the thing it represents is, or was.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node. |
Returns
A list of locations, each expressed as a fuzzy location, or an empty list if none have been set. An unknown KBase or node fails with Node or KBase not found. To get the locations of every node at once, use GetLocations.
UpdateNodeLocations
destructiveReplaces the locations held by a node with the ones supplied.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node. |
newLocations | array | The new locations for the node, in the same fuzzy location form as those returned by GetNodeLocations. |
Returns
true if the locations were updated; an unknown KBase or node fails with Node or KBase not found. Locations set here are what GetLocations reports on.
CreateEdge
destructiveCreates a new edge joining two existing nodes.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
sourceNodeId | string | The Id of the node the edge starts from. |
targetNodeId | string | The Id of the node the edge points to. |
edgeName | string | The name of the edge. |
lineage | string | The lineage that types the edge. |
Returns
The Id of the new edge.
GetEdgeCore
Try itGets the core information for an edge.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
edgeId | string | The Id of the edge. |
Returns
The edge record, including the nodes it connects. An unknown edge fails with Edge not found.
UpdateEdge
destructiveRenames an edge and/or changes the lineage that types it.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
edgeId | string | The Id of the edge to update. |
edgeName | string | The new name of the edge. |
lineage | string | The new lineage of the edge. |
Returns
true if the edge was updated.
DeleteEdge
destructiveDeletes an edge from the graph, leaving the nodes it joined in place.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
edgeId | string | The Id of the edge to delete. |
Returns
true if the edge was deleted; an unknown KBase or edge fails with KBase or Edge not found.