Skip to main content

Constructing a graph

This article outlines how to use spaces and instances to construct an industrial knowledge graph.


A space can contain both schemas and instances. It is an efficient resource to help organize your graph. It functions as a namespace, and lets you choose identifiers without interference from other spaces. Also, it serves as a scope for governance and access control facilitating a structured approach to data management.


The term instance is an umbrella term for nodes and edges. Every instance has a set of core properties, and many of the properties apply to both nodes and edges:

spaceWhich space the node/edge belongs to.xx
externalIdThe identifier of the node/edge.xx
typeA direct relation pointing to the type node/edge.xx
startNodeA direct relation pointing to the start node.x
endNodeA direct relation pointing to the end node.x
createdTimeWhen the node/edge was created.xx
lastUpdatedTimeWhen the node was last updated.xx
versionA number incremented every time the instance is modified.xx

Edges depend on their associated start and end nodes. When a node is deleted, any edges connected to it are also removed.

Edges can span spaces. They reside in a specific space but can link to nodes in other spaces.

External IDs

Every instance is assigned an external ID that must be unique within a space. A fully qualified external ID consists of both the space and the external ID, for example: {"space": "mySpace", "externalId": "myNode"}. You can also use the short form: ["mySpace", "myNode"].

The maximum length of an external ID is 255 characters, and null bytes are not allowed within the ID.

Direct relations vs. edges

You can express relationships to nodes using edges or a special type of property called a direct relation. A direct relation is a property holding a reference to a node, and is similar to a foreign key in relational models. Edges and direct relations have different characteristics:

Direct relationsEdges
Can have properties of their own.NoYes
Can be traversed recursively.NoYes
Can restrict which container the target node must have data in.YesNo
Cheap, supporting a large number of direct relations with minimal overhead.YesNo
Relatively costly, making direct relations a consideration for large quantities, as they count toward instance limits.NoYes
Can enforce that a set of edges form a tree or a Directed Acyclic Graph (DAG).NoYes

Type nodes

In your graph, nodes can represent anything from physical entities to abstract concepts like a comment or the type of a physical entity. Every instance has a type property, a direct relation pointing to the node that defines its intended type.

For example, a node representing a physical pump can have the type property pointing to a "Pump" node. Or an edge representing a pipe can have the type property pointing to a "FlowsTo" node.

As type systems grow in size and complexity, the importance of organization and governance increases. To manage type systems effectively, we recommend that you organize them in dedicated spaces within your graph. In the example graph below, the type nodes are in a dedicated types space. Depending on the complexity of your type system, you may want to consider organizing them across multiple spaces.


You can't delete a type node when it has instances pointing to it.

Example knowledge graph

This example illustrates what a small knowledge graph could look like. It displays nodes, direct relations, and edges to represent a pump directing liquid through pipes into a set of valves and where someone has added a comment about the pump:

Simplified view

Here's a simplified view of the above graph, displaying only the nodes and edges: