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. 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
Node attributes
Time
Edges
GetGraph
read-onlyGets 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.
GetFilteredGraph
read-onlyGets 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.
GetTimeLine
read-onlyGets the timeline of a knowledge base: the set of existences recorded for its nodes.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
Returns
A list of existences, or an empty list if none have been set.
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
Gets 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
Gets 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.
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. |
Returns
The annotated graph object.
AnnotateNodeFromUrl
destructiveAs AnnotateNode, but the text is fetched from a web page.
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. |
Returns
The annotated graph object.
GetNodeAttributes
Gets 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.
GetNodeExistence
Gets the temporal existence data for a node: when the thing it represents began, ended, or occurred.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node. |
Returns
The node's existence, expressed as a fuzzy time.
UpdateExistence
destructiveSets the temporal existence data for a node. Supply between one and four ISO 8601 Extended dates (a negative year means BCE):
| Dates given | Meaning |
|---|---|
| one | an event — a single point in time |
| two | an interval — a start and an end |
| three | a fuzzy event |
| four | a fuzzy interval |
Each date may be given a precision: the tolerance of that date in seconds. Leave a
precision at 0.0 for an exact date.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node. |
iso8601Date1 | string | The first date. |
iso8601Date2 | string (optional) | The second date. |
iso8601Date3 | string (optional) | The third date. |
iso8601Date4 | string (optional) | The fourth date. |
precision1 | number (optional) | Tolerance of the first date in seconds. Default 0.0. |
precision2 | number (optional) | Tolerance of the second date in seconds. Default 0.0. |
precision3 | number (optional) | Tolerance of the third date in seconds. Default 0.0. |
precision4 | number (optional) | Tolerance of the fourth date in seconds. Default 0.0. |
Returns
true if the existence was updated. Existence data set here is what GetFilteredGraph and GetTimeLine report 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
Gets 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.