Core data model - Cognite Docs

Cognite’s core data model—CogniteCore—offers standardized building blocks for industrial data, forming the basis for more specialized models. It’s available from the cdf_cdm system space. The core data model uses two methods to define properties: core features and core concepts:

The core features are sets of properties that are available for many concepts.
The core concepts have properties that are specific to a single concept.

Each core feature and core concept comes with a matching container and view. The exceptions are stateless concepts, which only have a view and no container. The containers have efficient indexes and constraints and can be used at scale out-of-the-box. The views combine the properties of the core features and the core concepts. The core data model can be extended, currently via GraphQL. For example, Cognite’s industrial data models extend the core data model to meet common, industry-specific needs.

Access control

In addition to the dataModelInstancesAcl capabilities to read/write the instances, users of the core data model need the following capabilities:

dataModelsAcl.READ to cdf_cdm to read the core data model schema.
dataModelsAcl.READ to cdf_extraction_extensions to read properties set by Cognite extractors.
dataModelInstancesAcl.READ to cdf_cdm_units to use units.

For more information, see Control access to a graph.

Core features

This section collects commonly used properties, with common definitions. If a core concept uses a different definition, or narrows the scope of, an otherwise common property, it will be called out in the section that defines the core concept.

CogniteDescribable

The CogniteDescribable core feature has properties to create names and descriptions for concepts.

Property	Type	Description
name	String	The name of the instance.
description	String	The description of the instance.
tags	List of strings	A list of tags for the instance. Max: 1000
aliases	List of strings	Alternative names for the instance.

CogniteSourceable

The CogniteSourceable core feature has properties to represent how the source information in concepts is stored.

Property	Type	Description
sourceId	String	The identifier in the source system.
sourceContext	String	The context of the `sourceId`. For systems where the `sourceId` is globally unique, leave `sourceContext` empty.
source	Direct relation to a source system	A direct relation to a source system instance.
sourceCreatedTime	Timestamp	The time the instance was created in the source system (if available).
sourceUpdatedTime	Timestamp	The time the instance was updated in the source system (if available).
sourceCreatedUser	String	The user ID for the user who created the instance in the source system. It may or may not be the same as the CDF user ID.
sourceUpdatedUser	String	The user ID for the user who updated the instance in the source system. It may or may not be the same as the CDF user ID.

CogniteSourceSystem

The CogniteSourceSystem core feature has properties to represent the source system where the information is stored.

Property	Type	Description
version	String	The version identifier for the source system.
manufacturer	String	The manufacturer of the source system.

The following core features are also available for this core feature: CogniteDescribable

CogniteSchedulable

The CogniteSchedulable core feature has properties to represent start and end times for a concept, for example an activity.

Property	Type	Description
startTime	Timestamp	The start time of an activity (or similar).
endTime	Timestamp	The end time of an activity (or similar).
scheduledStartTime	Timestamp	The planned start time of an activity (or similar).
scheduledEndTime	Timestamp	The planned end time of an activity (or similar).

CogniteVisualizable

The CogniteVisualizable core feature has properties to enable a standard display of objects and to represent a reference to a 3D resource.

Property	Type	Description
object3D	Direct relation to Cognite3DObject	The related Cognite3DObject instance representing the 3D resource.

Core concepts

CogniteUnit

The CogniteUnit concept has properties to represent a single unit of measurement, for example Ampere.

Property	Type	Description
symbol	String	The symbol for the unit of measurement.
quantity	Enum	The physical quantity the unit measures.
source	String	The source of the unit specification.
sourceReference	String	A reference to the source of the unit specification. Typically, a URL to a standard, or to documentation of the source.

The following core features are also available for this concept: CogniteDescribable

CogniteAsset

The CogniteAsset concept has properties to represent systems that support industrial functions or processes. Assets are often called “functional locations”. You can structure assets hierarchically according to your organization’s criteria. For example, an asset can represent a water pump that’s part of a larger pump station asset at a clarification plant asset.

Property	Type	Description
parent	Direct relation	A direct relation to the parent of the asset.
children	Reverse direct relation	A virtual reverse relation to assets with this asset as their parent. It is resolved at query time and isn’t stored or materialized in the container.
root	Direct relation	An automatically updated reference to the top-level asset of the hierarchy.
path	List of direct relations	An automatically updated ordered list of this asset’s ancestors, starting with the root asset. Enables subtree filtering to find all assets under a parent.
pathLastUpdatedTime	Timestamp	The last time `path` was updated for this asset.
equipment	Reverse direct relation list to CogniteEquipment	An automatically updated list of equipment related to the asset.
timeSeries	Reverse direct relation list to CogniteTimeseries	An automatically updated list of time series related to the asset.
assetClass	Direct relation to CogniteAssetClass	Specifies the class of the asset, for example Pump or Heat exchanger.
type	Direct relation to CogniteAssetType	Specifies the type of the asset, for example Centrifugal pump or Air cooled heat exchanger.
activities	Reverse direct relation list to CogniteActivity	An automatically updated list of activities related to the asset.
files	Reverse direct relation list to CogniteFile	An automatically updated list of files related to the asset.

For hierarchies, root, path, and pathLastUpdatedTime are system-maintained hierarchy properties. children is a virtual reverse relation, so its behavior differs from these fields. Depending on your SDK-generated model classes, children might not be available as a standard typed property.

Any path values longer than 100 are truncated to the first 100 items. Assets with more than 100 ancestors in the hierarchy will not get a complete path.

The following core features are also available for this concept: CogniteDescribable, CogniteSourceable, CogniteVisualizable

CogniteAssetClass

The CogniteAssetClass concept has properties to represent the class of an asset, for example Pump or Heat exchanger.

Property	Type	Description
code	String	A unique identifier for the class of asset.
standard	String	A text string to specify which standard the class is from.

The following core features are also available for this concept: CogniteDescribable

CogniteAssetType

The CogniteAssetType concept has properties to represent the type of an asset, for example Centrifugal pump or Air cooled heat exchanger.

Property	Type	Description
code	String	A unique identifier for the type of asset.
standard	String	A text string to specify which standard the type is from.
assetClass	Direct relation to CogniteAssetClass	Specifies the class the type belongs to.

The following core features are also available for this concept: CogniteDescribable

CogniteEquipment

The CogniteEquipment concept has properties to represent physical supplies or devices. Example: a pump or a valve.

Property	Type	Description
asset	Direct relation to CogniteAsset	The asset the equipment is related to.
activities	Reverse direct relation list to CogniteActivity	An automatically updated list of activities related to the equipment.
timeSeries	Reverse direct relation list to CogniteTimeseries	An automatically updated list of time series related to the equipment.
serialNumber	String	The serial number of the equipment.
manufacturer	String	The manufacturer of the equipment.
equipmentType	Direct relation to CogniteEquipmentType	Specifies the type of the equipment.
files	List of direct relations to CogniteFile	A list of files the equipment relates to. For example, documentation and data sheet that belong to this equipment.

The following core features are also available for this concept: CogniteDescribable, CogniteSourceable

CogniteEquipmentType

The CogniteEquipmentType concept has properties to represent types of equipment, for example centrifugal pumps.

Property	Type	Description
code	String	A unique identifier for the type of equipment.
equipmentClass	String	The class of equipment.
standard	String	An identifier for the standard this equipment type is sourced from, for example, ISO14224.
standardReference	String	A reference to the source of the equipment standard.

The following core features are also available for this concept: CogniteDescribable

CogniteFile

The CogniteFile concept has properties to represent files.

Property	Type	Description
asset	List of direct relations to CogniteAssets	A list of assets this file is related to.
equipment	Reverse direct relation list to CogniteEquipment	An automatically updated list of equipment this file is related to.
mimeType	String	The MIME type of the file.
directory	String	Contains the path elements from the source (if the source system has a file system hierarchy or similar).
isUploaded	Boolean	Specifies if the file content has been uploaded to Cognite Data Fusion or not.
uploadedTime	Timestamp	The time the file upload completed.
category	Direct relation to CogniteFileCategory	Specifies the detected category the file belongs to.

The following core features are also available for this concept: CogniteDescribable, CogniteSourceable

CogniteFileCategory

The CogniteFileCategory concept has properties to represent the categories of files as determined by contextualization or categorization.

Property	Type	Description
code	String	An identifier for the category, for example, `AA` for Accounting (from Norsok.)
standard	String	The name of the standard the category originates from, for example `Norsok`.
standardReference	String	A reference to the source of the category standard.

The following common properties are also available for this concept: CogniteDescribable

CogniteActivity

The CogniteActivity concept has properties to represent activities. Activities typically happen over a period and have a start and end time.

Property	Type	Description
assets	List of direct relations to CogniteAsset	A list of assets this activity is related to.
equipment	List of direct relations to CogniteEquipment	A list of equipment this activity is related to.
timeSeries	List of direct relations to CogniteTimeseries	A list of time series this activity is related to.

The following core features are also available for this concept: CogniteDescribable, CogniteSourceable, CogniteSchedulable

CogniteTimeSeries

The CogniteTimeSeries concept has properties to represent a series of data points in time order, for example the temperature readings from a water pump.

Property	Type	Description
isStep	Boolean	Specifies whether the time series is a step time series or not.
type	Enum	Specifies the data type of the data points. Valid values: `numeric`, `string`, `state`.
sourceUnit	String	The unit specified in the source system.
unit	Direct relation to CogniteUnit	The unit of the time series.
stateSet	Direct relation to CogniteStateSet	The state set for state time series. Defines the valid states (integer, string pairs) for the time series. Only applicable when type is `state`.
assets	List of direct relations to related CogniteAsset	A list of assets the time series is related to.
equipment	List of direct relations to CogniteEquipment	A list of equipment the time series is related to.
activities	Reverse list of direct relations to CogniteActivity (and subtypes)	An automatically updated list of activities the time series is related to.

The following core features are also available for this concept: CogniteDescribable, CogniteSourceable

CogniteStateSet

The CogniteStateSet concept has properties to represent a set of valid states for state time series. Each state consists of a numeric value (integer) and a string value pair, for example [(0, "OFF"), (1, "ON")].

Property	Type	Description
states	List of state value pairs	A list of valid states. Each state contains `numericValue` (32-bit integer) and `stringValue` (up to 255 UTF-8 characters). Maximum 100 states.

State constraints:

Both numeric and string values must be unique within a state set.
Numeric values must be between -2,147,483,648 and 2,147,483,647.
String values can be up to 255 UTF-8 characters.

The following core features are also available for this concept: CogniteDescribable

CogniteAnnotation

The CogniteAnnotation concept has properties to represent annotations from contextualization results or links.

Property	Type	Description
confidence	float64	The confidence that this is a good match.
status	Enum	The status of the annotation. Valid values: `Suggested`, `Approved`, and `Rejected`.

The following core features are also available for this concept: CogniteDescribable, CogniteSourceable

CogniteDiagramAnnotation

The CogniteDiagramAnnotation concept has properties to represent an annotation for a diagram.

Property	Type	Description
startNodePageNumber	int64	The number of the page on which the annotation is located in the `startNode` file. The first page has number 1.
endNodePageNumber	int64	The number of the page on which the annotation is located in the `endNode` file if an `endNode` is present. The first page has number 1.
startNodeXMin	float64	A value between [0,1]. The minimum abscissa of the bounding box (left edge). Must be strictly less than `startNodeXMax`.
startNodeXMax	float64	A value between [0,1]. The maximum abscissa of the bounding box (right edge). Must be strictly more than `startNodeXMin`.
startNodeYMin	float64	A value between [0,1]. The minimum ordinate of the bounding box (bottom edge). Must be strictly less than `startNodeYMax`.
startNodeYMax	float64	A value between [0,1]. The maximum ordinate of the bounding box (top edge). Must be strictly more than `startNodeYMin`.
startNodeText	String	The text extracted from within the bounding box on the `startNode`.
endNodeXMin	float64	A value between [0,1]. The minimum abscissa of the bounding box (left edge). Must be strictly less than `endNodeXMax`. Only applicable if an `endNode` is defined.
endNodeXMax	float64	A value between [0,1]. The maximum abscissa of the bounding box (right edge). Must be strictly more than `endNodeXMin`. Only applicable if an `endNode` is defined.
endNodeYMin	float64	A value between [0,1]. The minimum ordinate of the bounding box (bottom edge). Must be strictly less than `endNodeYMax`. Only applicable if an `endNode` is defined.
endNodeYMax	float64	A value between [0,1]. The maximum ordinate of the bounding box (top edge). Must be strictly more than `endNodeYMin`. Only applicable if an `endNode` is defined.
endNodeText	String	The text extracted from within the bounding box on the `endNode`. Only applicable if an `endNode` is defined.

The following core features are also available for this concept: CogniteDescribable, CogniteSourceable, CogniteAnnotation

3D concepts

Cognite3DTransformation

Defines a comprehensive 3D transformation, which positions an object in 3D space using translation, rotation (Euler angles), and scale.

Property	Type	Description
translationX	Float	Displacement along the X-axis.
translationY	Float	Displacement along the Y-axis.
translationZ	Float	Displacement along the Z-axis.
eulerRotationX	Float	Rotation around the X-axis (radians).
eulerRotationY	Float	Rotation around the Y-axis (radians).
eulerRotationZ	Float	Rotation around the Z-axis (radians).
scaleX	Float	Scale factor along the X-axis.
scaleY	Float	Scale factor along the Y-axis.
scaleZ	Float	Scale factor along the Z-axis.

CogniteCubeMap

Defines the cube map projections surrounding a 3D entity, such as Cognite360Image.

Property	Type	Description
front	Direct relation to a CogniteFile	A direct relation to a file holding the front projection of the cube map.
back	Direct relation to a CogniteFile	A direct relation to a file holding the back projection of the cube map.
left	Direct relation to a CogniteFile	A direct relation to a file holding the left projection of the cube map.
right	Direct relation to a CogniteFile	A direct relation to a file holding the right projection of the cube map.
top	Direct relation to a CogniteFile	A direct relation to a file holding the top projection of the cube map.
bottom	Direct relation to a CogniteFile	A direct relation to a file holding the bottom projection of the cube map.

Base 3D concepts

Cognite3DModel

Groups 3D data into a single model entity.

Property	Type	Description
type	Enum	The 3D model type. Valid values: `CAD`, `PointCloud`, or `Image360`.
thumbnail	Direct relation to CogniteFile	Thumbnail image for the 3D model.

The following core feature is also available for this concept: CogniteDescribable.

Cognite3DRevision

Represents revision data for 3D models. Typically accessed through CognitePointCloudRevision, Cognite360ImageCollection, or CogniteCADRevision.

Property	Type	Description
status	Enum	The status of the revision. Valid values: `Queued`, `Processing`, `Done`, or `Failed`.
published	Boolean	Specifies if the revision is published or not.
type	Enum	The type of 3D model this is a revision of. Valid values: `CAD`, `PointCloud`, or `Image360`.
model3D	Direct relation to Cognite3DModel	The 3D model this is a revision of.
sourceFile	Direct relation to CogniteFile	The source file used to create this revision.

Cognite3DObject

Represents the virtual position of a physical object, connecting an asset to one or more 3D resources.

Property	Type	Description
asset	Reverse direct relation to CogniteAsset	The asset referencing this 3D object.
cadNodes	Reverse direct relation list to CogniteCADNode	A list of maximum 1000 CAD nodes representing the connected asset.
pointCloudVolumes	Reverse direct relation list to CognitePointCloudVolume	A list of maximum 1000 point cloud volumes representing the connected asset.
images360	Edge	Edge connection to Cognite360Image annotations representing the connected CogniteAsset.
xMin	Float	Lowest X value in the bounding box.
xMax	Float	Highest X value in the bounding box.
yMin	Float	Lowest Y value in the bounding box.
yMax	Float	Highest Y value in the bounding box.
zMin	Float	Lowest Z value in the bounding box.
zMax	Float	Highest Z value in the bounding box.

The following core feature is also available for this concept: CogniteDescribable.

Cognite3DGroup

Groups related 3D entities together.

Property	Type	Description
groupType	Enum	The type of group. Valid value: `Station360`

CAD

CogniteCADModel (view)

This view filters Cognite3DModel where type equals CAD. It’s used for navigating across CogniteCADModel instances.

Property	Type	Description
revisions	Reverse direct relation list to CogniteCADRevision	A list of revisions for this CAD model.

This view inherits properties from the Cognite3DModel concept. The following core feature is also available: CogniteDescribable.

CogniteCADRevision

Represents revision data for CAD models.

Property	Type	Description
revisionId	int64	3D API revision identifier for this CAD model.
model3D	Direct relation to CogniteCADModel	A direct relation to a CogniteCADModel instance.

This concept extends Cognite3DRevision.

CogniteCADNode

Represents contextualized nodes from a CAD model.

Property	Type	Description
object3D	Direct relation to Cognite3DObject	Direct relation to the 3D object grouping for this node.
model3D	Direct relation to Cognite3DModel	Direct relation to Cognite3DModel (CogniteCADModel in view version).
cadNodeReference	String	Reference to a node within a CAD model.
revisions	List of direct relations to Cognite3DRevision	Direct relations to revision instances which this `CogniteCADNode` exists in.
treeIndexes	List of int64	Tree indexes in the same order as revisions. Used by Reveal and similar applications to map from `CogniteCADNode` to a tree index entry in the backing 3D model.
subTreeSizes	List of int64	Subtree sizes in the same order as revisions. Used by Reveal and similar applications to determine how many nodes exist below this node in the hierarchy.

The following core feature is also available for this concept: CogniteDescribable.

360° images

Cognite360ImageModel (view)

This view filters Cognite3DModel where type equals Image360. It’s used for navigating across Cognite360ImageModel instances.

Property	Type	Description
collections	Reverse direct relation list to Cognite360ImageCollection	List of image collections for this model.

This view inherits properties from the Cognite3DModel concept. The following core feature is also available: CogniteDescribable.

Cognite360ImageCollection (view)

This view represents a logical collection of Cognite360Image instances. It filters Cognite3DRevision where type equals Image360.

Property	Type	Description
model3D	Direct relation to Cognite360ImageModel	A direct relation to a `Cognite360ImageModel` instance.

This view inherits properties from the Cognite3DRevision concept. The following core feature is also available: CogniteDescribable.

Cognite360Image

Represents a 360° image capture.

Property	Type	Description
collection360	Direct relation to Cognite360ImageCollection	Direct relation to the image collection this image belongs to.
station360	Direct relation to Cognite3DGroup	Direct relation to the Cognite3DGroup instance that groups different `Cognite360Image` instances to the same station.
takenAt	Timestamp	The time when the 6 photos were taken.

This concept includes properties from the following 3D concepts: Cognite3DTransformation, CogniteCubeMap.

Cognite360ImageStation (view)

This view groups images across collections to create a visual scan history. It filters Cognite3DGroup where groupType equals Station360.

Property	Type	Description
groupType	Enum	The type of group. Valid value: `Station360`

This view inherits properties from the Cognite3DGroup concept. The following core feature is also available: CogniteDescribable.

Cognite360ImageAnnotation

This concept defines edges connecting Cognite360Image to Cognite3DObject. The status is always approved.

Property	Type	Description
polygon	List of floats	A list of floats representing the polygon. The format depends on `formatVersion`.
formatVersion	String	The storage format version for the polygon.

This concept extends CogniteAnnotation. The following core features are also available: CogniteDescribable, CogniteSourceable.

Point cloud

CognitePointCloudModel (view)

This view filters Cognite3DModel where type equals PointCloud. It’s used for navigating across CognitePointCloudModel instances.

Property	Type	Description
revisions	Reverse direct relation list to CognitePointCloudRevision	A list of revisions for this point cloud model.

This view inherits properties from the Cognite3DModel concept. The following core feature is also available: CogniteDescribable.

CognitePointCloudRevision

Represents revision data for point cloud models.

Property	Type	Description
revisionId	int64	Revision identifier of the point cloud model.
model3D	Direct relation to CognitePointCloudModel	A direct relation to a CognitePointCloudModel instance.

This concept extends Cognite3DRevision.

CognitePointCloudVolume

Defines a volume within a point cloud.

Property	Type	Description
object3D	Direct relation to Cognite3DObject	Relation to the 3D object grouping for this volume.
model3D	Direct relation to Cognite3DModel	Relation to the parent model.
volumeReferences	List of strings	Volume metric hashes for 3D data storage access.
revisions	List of direct relations to Cognite3DRevision	Relations to revisions containing this volume.
volumeType	Enum	The type of volume. Valid values: `Cylinder` or `Box`.
volume	List of floats	9 floats defining the volume coordinates.
formatVersion	String	Version of the `volume` field format.

The following core feature is also available for this concept: CogniteDescribable.

​Access control

​Core features

​CogniteDescribable

​CogniteSourceable

​CogniteSourceSystem

​CogniteSchedulable

​CogniteVisualizable

​Core concepts

​CogniteUnit

​CogniteAsset

​CogniteAssetClass

​CogniteAssetType

​CogniteEquipment

​CogniteEquipmentType

​CogniteFile

​CogniteFileCategory

​CogniteActivity

​CogniteTimeSeries

​CogniteStateSet

​CogniteAnnotation

​CogniteDiagramAnnotation

​3D concepts

​Cognite3DTransformation

​CogniteCubeMap

​Base 3D concepts

​Cognite3DModel

​Cognite3DRevision

​Cognite3DObject

​Cognite3DGroup

​CAD

​CogniteCADModel (view)

​CogniteCADRevision

​CogniteCADNode

​360° images

​Cognite360ImageModel (view)

​Cognite360ImageCollection (view)

​Cognite360Image

​Cognite360ImageStation (view)

​Cognite360ImageAnnotation

​Point cloud

​CognitePointCloudModel (view)

​CognitePointCloudRevision

​CognitePointCloudVolume

Access control

Core features

CogniteDescribable

CogniteSourceable

CogniteSourceSystem

CogniteSchedulable

CogniteVisualizable

Core concepts

CogniteUnit

CogniteAsset

CogniteAssetClass

CogniteAssetType

CogniteEquipment

CogniteEquipmentType

CogniteFile

CogniteFileCategory

CogniteActivity

CogniteTimeSeries

CogniteStateSet

CogniteAnnotation

CogniteDiagramAnnotation

3D concepts

Cognite3DTransformation

CogniteCubeMap

Base 3D concepts

Cognite3DModel

Cognite3DRevision

Cognite3DObject

Cognite3DGroup

CAD

CogniteCADModel (view)

CogniteCADRevision

CogniteCADNode

360° images

Cognite360ImageModel (view)

Cognite360ImageCollection (view)

Cognite360Image

Cognite360ImageStation (view)

Cognite360ImageAnnotation

Point cloud

CognitePointCloudModel (view)

CognitePointCloudRevision

CognitePointCloudVolume