Time
Every node in a knowledge graph may carry an existence: the span of time during which the thing it represents existed, or the moment at which it happened. An existence is expressed as a fuzzy time, built from one to four ISO 8601 Extended dates (a negative year means BCE), each with an optional precision — the tolerance of that date, in seconds.
These tools read and write that temporal data, and turn dates written in ordinary prose into it. Existence data is what the time-aware graph tools GetFilteredGraph and GetLocations filter on.
Whole knowledge base
Node existence
Reading dates from text
Gets 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.
GetNodeExistence
Try itGets 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. An unknown KBase or node fails with Node or KBase not found.
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.
UpdateExistenceFromFuzzyTime
destructiveSets the temporal existence data for a node from a ready-made fuzzy time, in the form returned by GetNodeExistence or ExtractExistenceFromText. Use it to copy an existence from one node to another, or to store one that has just been read out of a piece of text; to set an existence from plain dates use UpdateExistence instead.
Parameters
| Name | Type | Description |
|---|---|---|
indexId | string | The Id of the KBase. |
nodeId | string | The Id of the node. |
newExistence | object | The new existence for the node, as a fuzzy time. |
Returns
true if the existence was updated; an unknown KBase or node fails with Node or KBase not found.
Reads the dates out of a piece of ordinary prose — "from 1642 until the spring of 1651", "on the morning of 6 June 1944" — and returns them as a fuzzy time. Nothing is stored: pass the result to UpdateExistenceFromFuzzyTime to record it against a node.
Parameters
| Name | Type | Description |
|---|---|---|
text | string | The text to extract the existence data from. |
IsEvent | boolean | Whether the text describes an event, happening at a single moment, rather than something that existed over an interval. |
Returns
The existence found in the text, as a fuzzy time. Text the server cannot read a date from fails with Error extracting existence data from text.