Space
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. Spaces serve as a scope for governance and access control facilitating a structured approach to data management. You can use CDF user groups and capabilities to define who has access to read from and write to a space. You can, for example, create a data model in a protected space to prevent it from being changed, and then create instances in a space where users can read and write to the data. To delete a space, you have to remove all schema resources assigned to it first.Instance
The term instance is an umbrella term for nodes and edges.- Nodes can represent anything, for example, real-world objects like pumps.
- Edges describe relationships between nodes.
| Property | Description | Node | Edge |
|---|---|---|---|
| space | Which space the node/edge belongs to. | x | x |
| externalId | The identifier of the node/edge. | x | x |
| type | A direct relation pointing to the type node/edge. | x | x |
| startNode | A direct relation pointing to the start node. | x | |
| endNode | A direct relation pointing to the end node. | x | |
| createdTime | When the node/edge was created. | x | x |
| lastUpdatedTime | When the node/edge was last updated. | x | x |
| version | A number incremented every time the instance is modified. | x | x |
Update requests that don’t update any instance properties don’t increment the
version or lastUpdatedTime of the instance.Edges depend on their associated start and end nodes. When a node is deleted, any edges connected to it are also removed.
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 or list of nodes, and is similar to a foreign key in relational models. Edges and direct relations have different characteristics:| Direct relations | Edges | |
|---|---|---|
| Can have properties of their own. | No | Yes |
| Can be traversed recursively. | No | Yes |
| Can restrict which container the target node must have data in. | Yes | No |
| Cheap, supporting a large number of direct relations with minimal overhead. | Yes | No |
| Relatively costly, making direct relations a consideration for large quantities, as they count toward instance limits. | No | Yes |
| Can enforce that a set of edges form a tree or a Directed Acyclic Graph (DAG). | No | Yes |
| Can traverse reverse direction of one-to-many relationships.* | No | Yes |
CogniteActivity has a property assets which is a list of direct relations to CogniteAsset.
To find all activities that have a specific asset, you can’t create a query that starts from the asset(s). Instead, you have to query all activities and filter on the asset(s) you want. If the relation was modeled as an edge, you could find all activities by traversing the edge from the asset(s).
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 atype
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.