Node

ENDPOINTS

GET /v1/knowledge-graph/nodes/

GET /v1/knowledge-graph/nodes/{NODE_ID}

GET /v1/knowledge-graph/nodes/{NODE_ID}/similar

GET /v1/knowledge-graph/nodes/{NODE_ID}/related

Definition

A knowledge graph is a structure used to represent our knowledge about the world in terms of entities (called nodes) and the relationships (called edges) between them.

A Node object consists of its type and its static and dynamic attributes. Static attributes are key-value pairs that belong to the node itself and they follow a fixed, well-defined schema based on the node's type. In contrast, dynamic attributes are described by edges between the nodes which can represent any type of a relationship between them. An example of a simple knowledge graph is available in Figure 1.

Figure 1: Example of a knowledge graph with nodes of type Person in yellow, and other nodes in dark grey. Edges between the nodes describe their dynamic attributes (such as *place_of_birth* or *sex_or_gender*).

Schema

Static attributes follow a fixed schema which we model by a type inheritance tree. Hierarchy of our current node types is visualized in Figure 2. The tables describing the attribute fields for each type are available below.

Node

Top-level base type all other node types inherit from.

Name	Type	Description
id	string	Internal ID string used to uniquely identify the node.
custom_id	string	Custom ID a user or a data source can assign to the node. Can be null.
name	string	Name of the node used as a label.
description	string	Text used to describe the node in more detail. Can be null.

Person

Inherits from Node.

Name	Type	Description
date_of_birth	date	Date of birth (DD.MM.YYYY.) of the person. Can be null.
date_of_death	date	Date of death (DD.MM.YYYY.) of the person. Can be null.
mass	float	Mass of the person in kilograms (kg). Can be null.
height	float	Height of the person in meters (m). Can be null.

Asset

Inherits from Node.

The type does not declare any additional attributes.
Used as a base type for user-defined assets.

Subasset

Inherits from Node.

The type does not declare any additional attributes.
Used as a base type for user-defined subassets.

Relevance

In our knowledge graph, we also compute the relevance of each node. That information can be used for finding important nodes in the graph and sorting the nodes in listing endpoints. There are two types of node relevances: absolute and relative. Absolute relevance indicates how important the node is across the whole knowledge graph. On the other hand, relative relevance describes how important the node is with respect to another node.

To compute global node relevance, we use the PageRank algorithm whose score is available when using /v1/knowledge-graph/nodes/ endpoint.

For different types of relative node relevance, see Connectivity Analysis.

JSON Example

{
    "id": "5d2f9592-2514-46d4-8c86-3dacb542d71f",
    "custom_id": "Q22686",
    "name": "Donald Trump",
    "type": "person",
    "relevance": {
        "type": "pagerank",
        "value": 76.732
    }
},
{
    "id": "db73fe7c-e331-415f-b7e7-9dc3565adcec",
    "custom_id": "Q5",
    "name": "human",
    "type": "node",
    "relevance": {
        "type": "pagerank",
        "value": 67.5587
    }
},
{
    "id": "a23e4722-23ed-46aa-bd9c-026755125caf",
    "custom_id": "Q567",
    "name": "Angela Merkel",
    "type": "person",
    "relevance": {
        "type": "pagerank",
        "value": 58.0493
    }
},
...

Connectivity Analysis

Similar Nodes

Our /v1/knowledge-graph/nodes/{NODE_ID}/similar endpoint offers the functionality to find nodes similar to the query node with an ID of {NODE_ID}. Similar nodes always have the same type as the query node. The retrieved similar nodes are sorted by the type of relative relevance called similar.

JSON Example

Nodes similar to Michael Schumacher:

{
    "id": "7ae74959-f54e-4c69-98ab-832caac8d89b",
    "custom_id": "Q42311",
    "name": "Sebastian Vettel",
    "type": "person",
    "relevance": {
        "type": "similar",
        "value": 9
    }
},
{
    "id": "be1fd665-9361-4e2f-b504-78e61de609db",
    "custom_id": "Q9673",
    "name": "Lewis Hamilton",
    "type": "person",
    "relevance": {
        "type": "similar",
        "value": 9
    }
},
{
    "id": "3b359413-dbb6-4efd-94b5-cec431c5f214",
    "custom_id": "Q75825",
    "name": "Ralf Schumacher",
    "type": "person",
    "relevance": {
        "type": "similar",
        "value": 8
    }
},
...

By using /v1/knowledge-graph/nodes/{NODE_ID}/related endpoint, it is possible to obtain all related nodes of the query node with and ID of {NODE_ID}. The retrieved related nodes are sorted by the type of relative relevance called related.

JSON Example

Nodes related to Michael Schumacher:

{
    "id": "9b78f613-7bbb-48d8-9226-ac148a0c68ef",
    "custom_id": "Q183",
    "name": "Germany",
    "type": "node",
    "relevance": {
        "type": "related",
        "value": 2
    }
},
{
    "id": "76f46267-80f7-4d29-846d-3b99afb49597",
    "custom_id": "Q18119599",
    "name": "Mick Schumacher",
    "type": "person",
    "relevance": {
        "type": "related",
        "value": 2
    }
},
{
    "id": "c0726765-01ef-4ead-98b2-0841880c903f",
    "custom_id": "Q95171",
    "name": "Corinna Schumacher",
    "type": "person",
    "relevance": {
        "type": "related",
        "value": 2
    }
},
...

Attribute-based Filtering

Endpoints that list nodes support result filtering by nodes' attributes. Filtering is performed by applying a specific operator on a static attribute.

Both static and dynamic attributes support filtering by strict equality. This is done by an operator eq that is analogous to == in a majority of programming languages.

Additonally, static attributes of numeric (integer, float) or date type also support filtering with other conditional operators:

lt: Less than (analogous to <)
le: Less or equal than (analogous to <=)
gt: Greater than (analogous to >)
ge: Greater or equal than (analogous to >=)
ne: Not equal to (analogous to != or <>)
from: Alias for ge
to: Alias for le

To filter by an attribute <attribute_name> using the operator <operator> and the value <cmp_value> to compare against, pass an additional GET parameter in the following name-value form:

<attribute_name>.<operator>=<cmp_value>

For example, to list only women born before 1970 use the following GET parameters:

type=person&sex_or_gender=female&date_of_birth.year.lt=1970

Notice when comparing by strict equality (as for sex_or_gender in the example) the operator eq can be omitted.

Node

Definition

Schema

Node

Person

Asset

Subasset

Relevance

JSON Example

Connectivity Analysis

Similar Nodes

JSON Example

Related Nodes

JSON Example

Attribute-based Filtering