Data Organization

Annotations

Retrieve an annotation by id

AnnotationsAPI.retrieve(id: int) Annotation | None

Retrieve an annotation by id

Parameters

id (int) – id of the annotation to be retrieved

Returns

annotation requested

Return type

Annotation | None

Retrieve multiple annotations by id

AnnotationsAPI.retrieve_multiple(ids: Sequence[int]) AnnotationList

Retrieve annotations by IDs <https://developer.cognite.com/api#tag/Annotations/operation/annotationsByids>`_

Parameters

ids (Sequence[int]) – list of IDs to be retrieved

Returns

list of annotations

Return type

AnnotationList

List annotation

AnnotationsAPI.list(filter: AnnotationFilter | dict, limit: int | None = 25) AnnotationList

List annotations.

Note

Passing a filter with both ‘annotated_resource_type’ and ‘annotated_resource_ids’ is always required.

Parameters
  • filter (AnnotationFilter | dict) – Return annotations with parameter values that match what is specified.

  • limit (int | None) – Maximum number of annotations to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.

Returns

list of annotations

Return type

AnnotationList

Example

List all annotations for the file with id=123:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import AnnotationFilter
>>> client = CogniteClient()
>>> flt = AnnotationFilter(annotated_resource_type="file", annotated_resource_ids=[{"id": 123}])
>>> res = client.annotations.list(flt, limit=None)

Create an annotation

AnnotationsAPI.create(annotations: Annotation | AnnotationWrite) Annotation
AnnotationsAPI.create(annotations: Sequence[Annotation | AnnotationWrite]) AnnotationList

Create annotations

Parameters

annotations (Annotation | AnnotationWrite | Sequence[Annotation | AnnotationWrite]) – Annotation(s) to create

Returns

Created annotation(s)

Return type

Annotation | AnnotationList

Suggest an annotation

AnnotationsAPI.suggest(annotations: Annotation) Annotation
AnnotationsAPI.suggest(annotations: Sequence[Annotation]) AnnotationList

Suggest annotations

Parameters

annotations (Annotation | Sequence[Annotation]) – annotation(s) to suggest. They must have status set to “suggested”.

Returns

suggested annotation(s)

Return type

Annotation | AnnotationList

Update annotations

AnnotationsAPI.update(item: Annotation | AnnotationWrite | AnnotationUpdate) Annotation
AnnotationsAPI.update(item: Sequence[Annotation | AnnotationWrite | AnnotationUpdate]) AnnotationList

Update annotations

Parameters

item (Annotation | AnnotationWrite | AnnotationUpdate | Sequence[Annotation | AnnotationWrite | AnnotationUpdate]) – Annotation or list of annotations to update (or patch or list of patches to apply)

Returns

No description.

Return type

Annotation | AnnotationList

Delete annotations

AnnotationsAPI.delete(id: int | Sequence[int]) None

Delete annotations

Parameters

id (int | Sequence[int]) – ID or list of IDs to be deleted

Annotations Data classes

class cognite.client.data_classes.annotations.Annotation(annotation_type: str, data: dict, status: str, creating_app: str, creating_app_version: str, creating_user: str | None, annotated_resource_type: str, annotated_resource_id: int | None = None, id: int | None = None, created_time: int | None = None, last_updated_time: int | None = None, cognite_client: CogniteClient | None = None)

Bases: AnnotationCore

Representation of an annotation in CDF. This is the reading version of the Annotation class. It is never to be used when creating new annotations.

Parameters
  • annotation_type (str) – The type of the annotation. This uniquely decides what the structure of the ‘data’ block will be.

  • data (dict) – The annotation information. The format of this object is decided by and validated against the ‘annotation_type’ attribute.

  • status (str) – The status of the annotation, e.g. “suggested”, “approved”, “rejected”.

  • creating_app (str) – The name of the app from which this annotation was created.

  • creating_app_version (str) – The version of the app that created this annotation. Must be a valid semantic versioning (SemVer) string.

  • creating_user (str | None) – (str, optional): A username, or email, or name. This is not checked nor enforced. If the value is None, it means the annotation was created by a service.

  • annotated_resource_type (str) – Type name of the CDF resource that is annotated, e.g. “file”.

  • annotated_resource_id (int | None) – The internal ID of the annotated resource.

  • id (int | None) – A server-generated ID for the object.

  • created_time (int | None) – The timestamp for when the annotation was created, in milliseconds since epoch.

  • last_updated_time (int | None) – The timestamp for when the annotation was last updated, in milliseconds since epoch.

  • cognite_client (CogniteClient | None) – The client to associate with this object.

as_write() AnnotationWrite

Returns this Annotation in its writing version.

class cognite.client.data_classes.annotations.AnnotationCore(annotation_type: str, data: dict, status: str, creating_app: str, creating_app_version: str, creating_user: str | None, annotated_resource_type: str, annotated_resource_id: int | None = None)

Bases: WriteableCogniteResource[AnnotationWrite], ABC

Representation of an annotation in CDF.

Parameters
  • annotation_type (str) – The type of the annotation. This uniquely decides what the structure of the ‘data’ block will be.

  • data (dict) – The annotation information. The format of this object is decided by and validated against the ‘annotation_type’ attribute.

  • status (str) – The status of the annotation, e.g. “suggested”, “approved”, “rejected”.

  • creating_app (str) – The name of the app from which this annotation was created.

  • creating_app_version (str) – The version of the app that created this annotation. Must be a valid semantic versioning (SemVer) string.

  • creating_user (str | None) – (str, optional): A username, or email, or name. This is not checked nor enforced. If the value is None, it means the annotation was created by a service.

  • annotated_resource_type (str) – Type name of the CDF resource that is annotated, e.g. “file”.

  • annotated_resource_id (int | None) – The internal ID of the annotated resource.

dump(camel_case: bool = True) dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

class cognite.client.data_classes.annotations.AnnotationFilter(annotated_resource_type: str, annotated_resource_ids: list[dict[str, int]], status: str | None = None, creating_user: str | None = '', creating_app: str | None = None, creating_app_version: str | None = None, annotation_type: str | None = None, data: dict[str, Any] | None = None)

Bases: AnnotationReverseLookupFilter

Filter on annotations with various criteria

Parameters
  • annotated_resource_type (str) – The type of the CDF resource that is annotated, e.g. “file”.

  • annotated_resource_ids (list[dict[str, int]]) – List of ids of the annotated CDF resources to filter in. Example format: [{“id”: 1234}, {“id”: “4567”}]. Must contain at least one item.

  • status (str | None) – Status of annotations to filter for, e.g. “suggested”, “approved”, “rejected”.

  • creating_user (str | None) – Name of the user who created the annotations to filter for. Can be set explicitly to “None” to filter for annotations created by a service.

  • creating_app (str | None) – Name of the app from which the annotations to filter for where created.

  • creating_app_version (str | None) – Version of the app from which the annotations to filter for were created.

  • annotation_type (str | None) – Type name of the annotations.

  • data (dict[str, Any] | None) – The annotation data to filter by. Example format: {“label”: “cat”, “confidence”: 0.9}

class cognite.client.data_classes.annotations.AnnotationList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[AnnotationWrite, Annotation]

as_write() AnnotationWriteList

Returns this AnnotationList in its writing version.

class cognite.client.data_classes.annotations.AnnotationReverseLookupFilter(annotated_resource_type: str, status: str | None = None, creating_user: str | None = '', creating_app: str | None = None, creating_app_version: str | None = None, annotation_type: str | None = None, data: dict[str, Any] | None = None)

Bases: CogniteFilter

Filter on annotations with various criteria

Parameters
  • annotated_resource_type (str) – The type of the CDF resource that is annotated, e.g. “file”.

  • status (str | None) – Status of annotations to filter for, e.g. “suggested”, “approved”, “rejected”.

  • creating_user (str | None) – Name of the user who created the annotations to filter for. Can be set explicitly to “None” to filter for annotations created by a service.

  • creating_app (str | None) – Name of the app from which the annotations to filter for where created.

  • creating_app_version (str | None) – Version of the app from which the annotations to filter for were created.

  • annotation_type (str | None) – Type name of the annotations.

  • data (dict[str, Any] | None) – The annotation data to filter by. Example format: {“label”: “cat”, “confidence”: 0.9}

dump(camel_case: bool = True) dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

class cognite.client.data_classes.annotations.AnnotationUpdate(id: int)

Bases: CogniteUpdate

Changes applied to annotation

Parameters

id (int) – A server-generated ID for the object.

class cognite.client.data_classes.annotations.AnnotationWrite(annotation_type: AnnotationType, data: dict, status: Literal['suggested', 'approved', 'rejected'], creating_app: str, creating_app_version: str, creating_user: str | None, annotated_resource_type: Literal['file', 'threedmodel'], annotated_resource_id: int)

Bases: AnnotationCore

Representation of an annotation in CDF. This is the writing version of the Annotation class. It is used when creating new annotations.

Parameters
  • annotation_type (AnnotationType) – The type of the annotation. This uniquely decides what the structure of the ‘data’ block will be.

  • data (dict) – The annotation information. The format of this object is decided by and validated against the ‘annotation_type’ attribute.

  • status (Literal["suggested", "approved", "rejected"]) – The status of the annotation, e.g. “suggested”, “approved”, “rejected”.

  • creating_app (str) – The name of the app from which this annotation was created.

  • creating_app_version (str) – The version of the app that created this annotation. Must be a valid semantic versioning (SemVer) string.

  • creating_user (str | None) – A username, or email, or name. This is not checked nor enforced. If the value is None, it means the annotation was created by a service.

  • annotated_resource_type (Literal["file", "threedmodel"]) – Type name of the CDF resource that is annotated, e.g. “file”.

  • annotated_resource_id (int) – The internal ID of the annotated resource.

as_write() AnnotationWrite

Returns this AnnotationWrite.

class cognite.client.data_classes.annotations.AnnotationWriteList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[AnnotationWrite]

Data sets

Retrieve an data set by id

DataSetsAPI.retrieve(id: int | None = None, external_id: str | None = None) DataSet | None

Retrieve a single data set by id.

Parameters
  • id (int | None) – ID

  • external_id (str | None) – External ID

Returns

Requested data set or None if it does not exist.

Return type

DataSet | None

Examples

Get data set by id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.data_sets.retrieve(id=1)

Get data set by external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.data_sets.retrieve(external_id="1")

Retrieve multiple data sets by id

DataSetsAPI.retrieve_multiple(ids: Sequence[int] | None = None, external_ids: SequenceNotStr[str] | None = None, ignore_unknown_ids: bool = False) DataSetList

Retrieve multiple data sets by id.

Parameters
  • ids (Sequence[int] | None) – IDs

  • external_ids (SequenceNotStr[str] | None) – External IDs

  • ignore_unknown_ids (bool) – Ignore IDs and external IDs that are not found rather than throw an exception.

Returns

The requested data sets.

Return type

DataSetList

Examples

Get data sets by id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.data_sets.retrieve_multiple(ids=[1, 2, 3])

Get data sets by external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.data_sets.retrieve_multiple(external_ids=["abc", "def"], ignore_unknown_ids=True)

List data sets

DataSetsAPI.list(metadata: dict[str, str] | None = None, created_time: dict[str, Any] | TimestampRange | None = None, last_updated_time: dict[str, Any] | TimestampRange | None = None, external_id_prefix: str | None = None, write_protected: bool | None = None, limit: int | None = 25) DataSetList

List data sets

Parameters
  • metadata (dict[str, str] | None) – Custom, application-specific metadata. String key -> String value.

  • created_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps.

  • last_updated_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps.

  • external_id_prefix (str | None) – Filter by this (case-sensitive) prefix for the external ID.

  • write_protected (bool | None) – Specify whether the filtered data sets are write-protected, or not. Set to True to only list write-protected data sets.

  • limit (int | None) – Maximum number of data sets to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.

Returns

List of requested data sets

Return type

DataSetList

Examples

List data sets and filter on write_protected:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> data_sets_list = client.data_sets.list(limit=5, write_protected=False)

Iterate over data sets:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> for data_set in client.data_sets:
...     data_set # do something with the data_set

Iterate over chunks of data sets to reduce memory load:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> for data_set_list in client.data_sets(chunk_size=2500):
...     data_set_list # do something with the list

Aggregate data sets

DataSetsAPI.aggregate(filter: DataSetFilter | dict | None = None) list[CountAggregate]

Aggregate data sets

Parameters

filter (DataSetFilter | dict | None) – Filter on data set filter with exact match

Returns

List of data set aggregates

Return type

list[CountAggregate]

Examples

Aggregate data_sets:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> aggregate_protected = client.data_sets.aggregate(filter={"write_protected": True})

Create data sets

DataSetsAPI.create(data_set: Sequence[DataSet] | Sequence[DataSetWrite]) DataSetList
DataSetsAPI.create(data_set: DataSet | DataSetWrite) DataSet

Create one or more data sets.

Parameters

data_set (DataSet | DataSetWrite | Sequence[DataSet] | Sequence[DataSetWrite]) – Union[DataSet, Sequence[DataSet]]: Data set or list of data sets to create.

Returns

Created data set(s)

Return type

DataSet | DataSetList

Examples

Create new data sets:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import DataSetWrite
>>> client = CogniteClient()
>>> data_sets = [DataSetWrite(name="1st level"), DataSetWrite(name="2nd level")]
>>> res = client.data_sets.create(data_sets)

Delete data sets

This functionality is not yet available in the API.

Update data sets

DataSetsAPI.update(item: DataSet | DataSetWrite | DataSetUpdate) DataSet
DataSetsAPI.update(item: Sequence[DataSet | DataSetWrite | DataSetUpdate]) DataSetList

Update one or more data sets

Parameters

item (DataSet | DataSetWrite | DataSetUpdate | Sequence[DataSet | DataSetWrite | DataSetUpdate]) – Data set(s) to update

Returns

Updated data set(s)

Return type

DataSet | DataSetList

Examples

Update a data set that you have fetched. This will perform a full update of the data set:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> data_set = client.data_sets.retrieve(id=1)
>>> data_set.description = "New description"
>>> res = client.data_sets.update(data_set)

Perform a partial update on a data set, updating the description and removing a field from metadata:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import DataSetUpdate
>>> client = CogniteClient()
>>> my_update = DataSetUpdate(id=1).description.set("New description").metadata.remove(["key"])
>>> res = client.data_sets.update(my_update)

Data Sets Data classes

class cognite.client.data_classes.data_sets.DataSet(external_id: str | None = None, name: str | None = None, description: str | None = None, metadata: dict[str, str] | None = None, write_protected: bool | None = None, id: int | None = None, created_time: int | None = None, last_updated_time: int | None = None, cognite_client: CogniteClient | None = None)

Bases: DataSetCore

Data sets let you document and track data lineage, ensure data integrity, and allow 3rd parties to write their insights securely back to a Cognite Data Fusion (CDF) project. This is the read version of the DataSet, which is used when retrieving from CDF.

Parameters
  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • name (str | None) – The name of the data set.

  • description (str | None) – The description of the data set.

  • metadata (dict[str, str] | None) – Custom, application-specific metadata. String key -> String value. Limits: Maximum length of key is 128 bytes, value 10240 bytes, up to 256 key-value pairs, of total size at most 10240.

  • write_protected (bool | None) – To write data to a write-protected data set, you need to be a member of a group that has the “datasets:owner” action for the data set. To learn more about write-protected data sets, follow this [guide](/cdf/data_governance/concepts/datasets/#write-protection)

  • id (int | None) – A server-generated ID for the object.

  • created_time (int | None) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

  • last_updated_time (int | None) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

  • cognite_client (CogniteClient | None) – The client to associate with this object.

class cognite.client.data_classes.data_sets.DataSetCore(external_id: str | None = None, name: str | None = None, description: str | None = None, metadata: dict[str, str] | None = None, write_protected: bool | None = None)

Bases: WriteableCogniteResource[DataSetWrite]

Data sets let you document and track data lineage, ensure data integrity, and allow 3rd parties to write their insights securely back to a Cognite Data Fusion (CDF) project. This is the read version of the DataSet, which is used when retrieving from CDF.

Parameters
  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • name (str | None) – The name of the data set.

  • description (str | None) – The description of the data set.

  • metadata (dict[str, str] | None) – Custom, application-specific metadata. String key -> String value. Limits: Maximum length of key is 128 bytes, value 10240 bytes, up to 256 key-value pairs, of total size at most 10240.

  • write_protected (bool | None) – To write data to a write-protected data set, you need to be a member of a group that has the “datasets:owner” action for the data set. To learn more about write-protected data sets, follow this [guide](/cdf/data_governance/concepts/datasets/#write-protection)

class cognite.client.data_classes.data_sets.DataSetFilter(metadata: dict[str, str] | None = None, created_time: dict[str, Any] | TimestampRange | None = None, last_updated_time: dict[str, Any] | TimestampRange | None = None, external_id_prefix: str | None = None, write_protected: bool | None = None)

Bases: CogniteFilter

Filter on data sets with strict matching.

Parameters
  • metadata (dict[str, str] | None) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 128 bytes, value 10240 bytes, up to 256 key-value pairs, of total size at most 10240.

  • created_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps.

  • last_updated_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps.

  • external_id_prefix (str | None) – Filter by this (case-sensitive) prefix for the external ID.

  • write_protected (bool | None) – No description.

dump(camel_case: bool = True) dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

class cognite.client.data_classes.data_sets.DataSetList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[DataSetWrite, DataSet], IdTransformerMixin

class cognite.client.data_classes.data_sets.DataSetUpdate(id: int | None = None, external_id: str | None = None)

Bases: CogniteUpdate

Update applied to single data set

Parameters
  • id (int) – A server-generated ID for the object.

  • external_id (str) – The external ID provided by the client. Must be unique for the resource type.

class cognite.client.data_classes.data_sets.DataSetWrite(external_id: str | None = None, name: str | None = None, description: str | None = None, metadata: dict[str, str] | None = None, write_protected: bool | None = None)

Bases: DataSetCore

Data sets let you document and track data lineage, ensure data integrity, and allow 3rd parties to write their insights securely back to a Cognite Data Fusion (CDF) project. This is the read version of the DataSet, which is used when retrieving from CDF.

Parameters
  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • name (str | None) – The name of the data set.

  • description (str | None) – The description of the data set.

  • metadata (dict[str, str] | None) – Custom, application-specific metadata. String key -> String value. Limits: Maximum length of key is 128 bytes, value 10240 bytes, up to 256 key-value pairs, of total size at most 10240.

  • write_protected (bool | None) – To write data to a write-protected data set, you need to be a member of a group that has the “datasets:owner” action for the data set. To learn more about write-protected data sets, follow this [guide](/cdf/data_governance/concepts/datasets/#write-protection)

as_write() DataSetWrite

Returns this DataSetWrite instance.

class cognite.client.data_classes.data_sets.DataSetWriteList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[DataSetWrite], ExternalIDTransformerMixin

Labels

List labels

LabelsAPI.list(name: str | None = None, external_id_prefix: str | None = None, data_set_ids: int | Sequence[int] | None = None, data_set_external_ids: str | SequenceNotStr[str] | None = None, limit: int | None = 25) LabelDefinitionList

List Labels

Parameters
  • name (str | None) – returns the label definitions matching that name

  • external_id_prefix (str | None) – filter label definitions with external ids starting with the prefix specified

  • data_set_ids (int | Sequence[int] | None) – return only labels in the data sets with this id / these ids.

  • data_set_external_ids (str | SequenceNotStr[str] | None) – return only labels in the data sets with this external id / these external ids.

  • limit (int | None) – Maximum number of label definitions to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.

Returns

List of requested Labels

Return type

LabelDefinitionList

Examples

List Labels and filter on name:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> label_list = client.labels.list(limit=5, name="Pump")

Iterate over label definitions:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> for label in client.labels:
...     label # do something with the label definition

Iterate over chunks of label definitions to reduce memory load:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> for label_list in client.labels(chunk_size=2500):
...     label_list # do something with the type definitions

Create a label

LabelsAPI.create(label: LabelDefinition | LabelDefinitionWrite) LabelDefinition
LabelsAPI.create(label: Sequence[LabelDefinition | LabelDefinitionWrite]) LabelDefinitionList

Create one or more label definitions.

Parameters

label (LabelDefinition | LabelDefinitionWrite | Sequence[LabelDefinition | LabelDefinitionWrite]) – The label definition(s) to create.

Returns

Created label definition(s)

Return type

LabelDefinition | LabelDefinitionList

Raises

TypeError – Function input ‘label’ is of the wrong type

Examples

Create new label definitions:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import LabelDefinitionWrite
>>> client = CogniteClient()
>>> labels = [LabelDefinitionWrite(external_id="ROTATING_EQUIPMENT", name="Rotating equipment"), LabelDefinitionWrite(external_id="PUMP", name="pump")]
>>> res = client.labels.create(labels)

Delete labels

LabelsAPI.delete(external_id: str | SequenceNotStr[str] | None = None) None

Delete one or more label definitions

Parameters

external_id (str | SequenceNotStr[str] | None) – One or more label external ids

Examples

Delete label definitions by external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.labels.delete(external_id=["big_pump", "small_pump"])

Labels Data classes

class cognite.client.data_classes.labels.Label(external_id: str | None = None, **_: Any)

Bases: CogniteObject

A label assigned to a resource.

Parameters
  • external_id (str | None) – The external id to the attached label.

  • **_ (Any) – No description.

class cognite.client.data_classes.labels.LabelDefinition(external_id: str | None = None, name: str | None = None, description: str | None = None, created_time: int | None = None, data_set_id: int | None = None, cognite_client: CogniteClient | None = None)

Bases: LabelDefinitionCore

A label definition is a globally defined label that can later be attached to resources (e.g., assets). For example, can you define a “Pump” label definition and attach that label to your pump assets. This is the reading version of the LabelDefinition class. It is used when retrieving existing label definitions.

Parameters
  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • name (str | None) – Name of the label.

  • description (str | None) – Description of the label.

  • created_time (int | None) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

  • data_set_id (int | None) – The id of the dataset this label belongs to.

  • cognite_client (CogniteClient | None) – The client to associate with this object.

as_write() LabelDefinitionWrite

Returns this LabelDefinition in its writing version.

class cognite.client.data_classes.labels.LabelDefinitionCore(external_id: str | None = None, name: str | None = None, description: str | None = None, data_set_id: int | None = None)

Bases: WriteableCogniteResource[LabelDefinitionWrite], ABC

A label definition is a globally defined label that can later be attached to resources (e.g., assets). For example, can you define a “Pump” label definition and attach that label to your pump assets. This is the parent for the reading and writing versions.

Parameters
  • external_id (str | None) – The external ID provided by the client. Must be unique for the resource type.

  • name (str | None) – Name of the label.

  • description (str | None) – Description of the label.

  • data_set_id (int | None) – The id of the dataset this label belongs to.

class cognite.client.data_classes.labels.LabelDefinitionFilter(name: str | None = None, external_id_prefix: str | None = None, data_set_ids: list[dict[str, Any]] | None = None, cognite_client: CogniteClient | None = None)

Bases: CogniteFilter

Filter on labels definitions with strict matching.

Parameters
  • name (str | None) – Returns the label definitions matching that name.

  • external_id_prefix (str | None) – filter label definitions with external ids starting with the prefix specified

  • data_set_ids (list[dict[str, Any]] | None) – Only include labels that belong to these datasets.

  • cognite_client (CogniteClient | None) – The client to associate with this object.

class cognite.client.data_classes.labels.LabelDefinitionList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[LabelDefinitionWrite, LabelDefinition], ExternalIDTransformerMixin

as_write() LabelDefinitionWriteList

Returns this LabelDefinitionList in its writing version.

class cognite.client.data_classes.labels.LabelDefinitionWrite(external_id: str, name: str, description: str | None = None, data_set_id: int | None = None)

Bases: LabelDefinitionCore

A label definition is a globally defined label that can later be attached to resources (e.g., assets). For example, can you define a “Pump” label definition and attach that label to your pump assets. This is the writing version of the LabelDefinition class. It is used when creating new label definitions.

Parameters
  • external_id (str) – The external ID provided by the client. Must be unique for the resource type.

  • name (str) – Name of the label.

  • description (str | None) – Description of the label.

  • data_set_id (int | None) – The id of the dataset this label belongs to.

as_write() LabelDefinitionWrite

Returns this LabelDefinitionWrite instance.

class cognite.client.data_classes.labels.LabelDefinitionWriteList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[LabelDefinitionWrite], ExternalIDTransformerMixin

class cognite.client.data_classes.labels.LabelFilter(contains_any: list[str] | None = None, contains_all: list[str] | None = None, cognite_client: CogniteClient | None = None)

Bases: CogniteFilter

Return only the resource matching the specified label constraints.

Parameters
  • contains_any (list[str] | None) – The resource item contains at least one of the listed labels. The labels are defined by a list of external ids.

  • contains_all (list[str] | None) – The resource item contains all the listed labels. The labels are defined by a list of external ids.

  • cognite_client (CogniteClient | None) – The client to associate with this object.

Examples

List only resources marked as a PUMP and VERIFIED:

>>> from cognite.client.data_classes import LabelFilter
>>> my_label_filter = LabelFilter(contains_all=["PUMP", "VERIFIED"])

List only resources marked as a PUMP or as a VALVE:

>>> from cognite.client.data_classes import LabelFilter
>>> my_label_filter = LabelFilter(contains_any=["PUMP", "VALVE"])
dump(camel_case: bool = True) dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

Relationships

Retrieve a relationship by external id

RelationshipsAPI.retrieve(external_id: str, fetch_resources: bool = False) Relationship | None

Retrieve a single relationship by external id.

Parameters
  • external_id (str) – External ID

  • fetch_resources (bool) – if true, will try to return the full resources referenced by the relationship in the source and target fields.

Returns

Requested relationship or None if it does not exist.

Return type

Relationship | None

Examples

Get relationship by external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.relationships.retrieve(external_id="1")

Retrieve multiple relationships by external id

RelationshipsAPI.retrieve_multiple(external_ids: SequenceNotStr[str], fetch_resources: bool = False, ignore_unknown_ids: bool = False) RelationshipList

Retrieve multiple relationships by external id.

Parameters
  • external_ids (SequenceNotStr[str]) – External IDs

  • fetch_resources (bool) – if true, will try to return the full resources referenced by the relationship in the source and target fields.

  • ignore_unknown_ids (bool) – Ignore IDs and external IDs that are not found rather than throw an exception.

Returns

The requested relationships.

Return type

RelationshipList

Examples

Get relationships by external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.relationships.retrieve_multiple(external_ids=["abc", "def"])

List relationships

RelationshipsAPI.list(source_external_ids: SequenceNotStr[str] | None = None, source_types: SequenceNotStr[str] | None = None, target_external_ids: SequenceNotStr[str] | None = None, target_types: SequenceNotStr[str] | None = None, data_set_ids: int | Sequence[int] | None = None, data_set_external_ids: str | SequenceNotStr[str] | None = None, start_time: dict[str, int] | None = None, end_time: dict[str, int] | None = None, confidence: dict[str, int] | None = None, last_updated_time: dict[str, int] | None = None, created_time: dict[str, int] | None = None, active_at_time: dict[str, int] | None = None, labels: LabelFilter | None = None, limit: int | None = 25, partitions: int | None = None, fetch_resources: bool = False) RelationshipList

Lists relationships stored in the project based on a query filter given in the payload of this request. Up to 1000 relationships can be retrieved in one operation.

Parameters
  • source_external_ids (SequenceNotStr[str] | None) – Include relationships that have any of these values in their source External Id field

  • source_types (SequenceNotStr[str] | None) – Include relationships that have any of these values in their source Type field

  • target_external_ids (SequenceNotStr[str] | None) – Include relationships that have any of these values in their target External Id field

  • target_types (SequenceNotStr[str] | None) – Include relationships that have any of these values in their target Type field

  • data_set_ids (int | Sequence[int] | None) – Return only relationships in the specified data set(s) with this id / these ids.

  • data_set_external_ids (str | SequenceNotStr[str] | None) – Return only relationships in the specified data set(s) with this external id / these external ids.

  • start_time (dict[str, int] | None) – Range between two timestamps, minimum and maximum milliseconds (inclusive)

  • end_time (dict[str, int] | None) – Range between two timestamps, minimum and maximum milliseconds (inclusive)

  • confidence (dict[str, int] | None) – Range to filter the field for (inclusive).

  • last_updated_time (dict[str, int] | None) – Range to filter the field for (inclusive).

  • created_time (dict[str, int] | None) – Range to filter the field for (inclusive).

  • active_at_time (dict[str, int] | None) – Limits results to those active at any point within the given time range, i.e. if there is any overlap in the intervals [activeAtTime.min, activeAtTime.max] and [startTime, endTime], where both intervals are inclusive. If a relationship does not have a startTime, it is regarded as active from the beginning of time by this filter. If it does not have an endTime is will be regarded as active until the end of time. Similarly, if a min is not supplied to the filter, the min will be implicitly set to the beginning of time, and if a max is not supplied, the max will be implicitly set to the end of time.

  • labels (LabelFilter | None) – Return only the resource matching the specified label constraints.

  • limit (int | None) – Maximum number of relationships to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.

  • partitions (int | None) – Retrieve relationships in parallel using this number of workers. Also requires limit=None to be passed.

  • fetch_resources (bool) – if true, will try to return the full resources referenced by the relationship in the source and target fields.

Returns

List of requested relationships

Return type

RelationshipList

Examples

List relationships:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> relationship_list = client.relationships.list(limit=5)

Iterate over relationships:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> for relationship in client.relationships:
...     relationship # do something with the relationship

Create a relationship

RelationshipsAPI.create(relationship: Relationship | RelationshipWrite) Relationship
RelationshipsAPI.create(relationship: Sequence[Relationship | RelationshipWrite]) RelationshipList

Create one or more relationships.

Parameters

relationship (Relationship | RelationshipWrite | Sequence[Relationship | RelationshipWrite]) – Relationship or list of relationships to create.

Returns

Created relationship(s)

Return type

Relationship | RelationshipList

Note

  • The source_type and target_type field in the Relationship(s) can be any string among “Asset”, “TimeSeries”, “File”, “Event”, “Sequence”;

  • Do not provide the value for the source and target arguments of the Relationship class, only source_external_id / source_type and target_external_id / target_type. These (source and target) are used as part of fetching actual resources specified in other fields.

Examples

Create a new relationship specifying object type and external id for source and target:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import Relationship
>>> client = CogniteClient()
>>> flowrel1 = Relationship(
...     external_id="flow_1",
...     source_external_id="source_ext_id",
...     source_type="asset",
...     target_external_id="target_ext_id",
...     target_type="event",
...     confidence=0.1,
...     data_set_id=1234
... )
>>> flowrel2 = Relationship(
...     external_id="flow_2",
...     source_external_id="source_ext_id",
...     source_type="asset",
...     target_external_id="target_ext_id",
...     target_type="event",
...     confidence=0.1,
...     data_set_id=1234
... )
>>> res = client.relationships.create([flowrel1,flowrel2])

Update relationships

RelationshipsAPI.update(item: Relationship | RelationshipWrite | RelationshipUpdate) Relationship
RelationshipsAPI.update(item: Sequence[Relationship | RelationshipWrite | RelationshipUpdate]) RelationshipList

Update one or more relationships Currently, a full replacement of labels on a relationship is not supported (only partial add/remove updates). See the example below on how to perform partial labels update.

Parameters

item (Relationship | RelationshipWrite | RelationshipUpdate | Sequence[Relationship | RelationshipWrite | RelationshipUpdate]) – Relationship(s) to update

Returns

Updated relationship(s)

Return type

Relationship | RelationshipList

Examples

Update a data set that you have fetched. This will perform a full update of the data set:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> rel = client.relationships.retrieve(external_id="flow1")
>>> rel.confidence = 0.75
>>> res = client.relationships.update(rel)

Perform a partial update on a relationship, setting a source_external_id and a confidence:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import RelationshipUpdate
>>> client = CogniteClient()
>>> my_update = RelationshipUpdate(external_id="flow_1").source_external_id.set("alternate_source").confidence.set(0.97)
>>> res1 = client.relationships.update(my_update)
>>> # Remove an already set optional field like so
>>> another_update = RelationshipUpdate(external_id="flow_1").confidence.set(None)
>>> res2 = client.relationships.update(another_update)

Attach labels to a relationship:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import RelationshipUpdate
>>> client = CogniteClient()
>>> my_update = RelationshipUpdate(external_id="flow_1").labels.add(["PUMP", "VERIFIED"])
>>> res = client.relationships.update(my_update)

Detach a single label from a relationship:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import RelationshipUpdate
>>> client = CogniteClient()
>>> my_update = RelationshipUpdate(external_id="flow_1").labels.remove("PUMP")
>>> res = client.relationships.update(my_update)

Upsert relationships

RelationshipsAPI.upsert(item: Sequence[Relationship | RelationshipWrite], mode: Literal['patch', 'replace'] = 'patch') RelationshipList
RelationshipsAPI.upsert(item: Relationship | RelationshipWrite, mode: Literal['patch', 'replace'] = 'patch') Relationship
Upsert relationships, i.e., update if it exists, and create if it does not exist.

Note this is a convenience method that handles the upserting for you by first calling update on all items, and if any of them fail because they do not exist, it will create them instead.

For more details, see Upsert.

Parameters
  • item (Relationship | RelationshipWrite | Sequence[Relationship | RelationshipWrite]) – Relationship or list of relationships to upsert.

  • mode (Literal["patch", "replace"]) – Whether to patch or replace in the case the relationships are existing. If you set ‘patch’, the call will only update fields with non-null values (default). Setting ‘replace’ will unset any fields that are not specified.

Returns

The upserted relationship(s).

Return type

Relationship | RelationshipList

Examples

Upsert for relationships:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import Relationship
>>> client = CogniteClient()
>>> existing_relationship = client.relationships.retrieve(id=1)
>>> existing_relationship.description = "New description"
>>> new_relationship = Relationship(external_id="new_relationship", source_external_id="new_source")
>>> res = client.relationships.upsert([existing_relationship, new_relationship], mode="replace")

Delete relationships

RelationshipsAPI.delete(external_id: str | SequenceNotStr[str], ignore_unknown_ids: bool = False) None

Delete one or more relationships.

Parameters
  • external_id (str | SequenceNotStr[str]) – External ID or list of external ids

  • ignore_unknown_ids (bool) – Ignore external IDs that are not found rather than throw an exception.

Examples

Delete relationships by external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.relationships.delete(external_id=["a","b"])

Relationship Data classes

class cognite.client.data_classes.relationships.Relationship(external_id: str | None = None, source_external_id: str | None = None, source_type: str | None = None, source: Asset | TimeSeries | FileMetadata | Sequence | Event | dict | None = None, target_external_id: str | None = None, target_type: str | None = None, target: Asset | TimeSeries | FileMetadata | Sequence | Event | dict | None = None, start_time: int | None = None, end_time: int | None = None, confidence: float | None = None, data_set_id: int | None = None, labels: SequenceNotStr[Label | str | LabelDefinition | dict] | None = None, created_time: int | None = None, last_updated_time: int | None = None, cognite_client: CogniteClient | None = None)

Bases: RelationshipCore

Representation of a relationship in CDF, consists of a source and a target and some additional parameters. This is the reading version of the relationship class, it is used when retrieving from CDF.

Parameters
  • external_id (str | None) – External id of the relationship, must be unique within the project.

  • source_external_id (str | None) – External id of the CDF resource that constitutes the relationship source.

  • source_type (str | None) – The CDF resource type of the relationship source. Must be one of the specified values.

  • source (Asset | TimeSeries | FileMetadata | Sequence | Event | dict | None) – The full resource referenced by the source_external_id and source_type fields.

  • target_external_id (str | None) – External id of the CDF resource that constitutes the relationship target.

  • target_type (str | None) – The CDF resource type of the relationship target. Must be one of the specified values.

  • target (Asset | TimeSeries | FileMetadata | Sequence | Event | dict | None) – The full resource referenced by the target_external_id and target_type fields.

  • start_time (int | None) – Time, in milliseconds since Jan. 1, 1970, when the relationship became active. If there is no startTime, relationship is active from the beginning of time until endTime.

  • end_time (int | None) – Time, in milliseconds since Jan. 1, 1970, when the relationship became inactive. If there is no endTime, relationship is active from startTime until the present or any point in the future. If endTime and startTime are set, then endTime must be strictly greater than startTime.

  • confidence (float | None) – Confidence value of the existence of this relationship. Generated relationships should provide a realistic score on the likelihood of the existence of the relationship. Relationships without a confidence value can be interpreted at the discretion of each project.

  • data_set_id (int | None) – The id of the dataset this relationship belongs to.

  • labels (SequenceNotStr[Label | str | LabelDefinition | dict] | None) – A list of the labels associated with this resource item.

  • created_time (int | None) – Time, in milliseconds since Jan. 1, 1970, when this relationship was created in CDF.

  • last_updated_time (int | None) – Time, in milliseconds since Jan. 1, 1970, when this relationship was last updated in CDF.

  • cognite_client (CogniteClient | None) – The client to associate with this object.

as_write() RelationshipWrite

Returns this Relationship in its writing version.

dump(camel_case: bool = True) dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

class cognite.client.data_classes.relationships.RelationshipCore(external_id: str | None = None, source_external_id: str | None = None, source_type: str | None = None, target_external_id: str | None = None, target_type: str | None = None, start_time: int | None = None, end_time: int | None = None, confidence: float | None = None, data_set_id: int | None = None, labels: list[Label] | None = None)

Bases: WriteableCogniteResource[RelationshipWrite], ABC

Representation of a relationship in CDF, consists of a source and a target and some additional parameters.

Parameters
  • external_id (str | None) – External id of the relationship, must be unique within the project.

  • source_external_id (str | None) – External id of the CDF resource that constitutes the relationship source.

  • source_type (str | None) – The CDF resource type of the relationship source. Must be one of the specified values.

  • target_external_id (str | None) – External id of the CDF resource that constitutes the relationship target.

  • target_type (str | None) – The CDF resource type of the relationship target. Must be one of the specified values.

  • start_time (int | None) – Time, in milliseconds since Jan. 1, 1970, when the relationship became active. If there is no startTime, relationship is active from the beginning of time until endTime.

  • end_time (int | None) – Time, in milliseconds since Jan. 1, 1970, when the relationship became inactive. If there is no endTime, relationship is active from startTime until the present or any point in the future. If endTime and startTime are set, then endTime must be strictly greater than startTime.

  • confidence (float | None) – Confidence value of the existence of this relationship. Generated relationships should provide a realistic score on the likelihood of the existence of the relationship. Relationships without a confidence value can be interpreted at the discretion of each project.

  • data_set_id (int | None) – The id of the dataset this relationship belongs to.

  • labels (list[Label] | None) – A list of the labels associated with this resource item.

dump(camel_case: bool = True) dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

class cognite.client.data_classes.relationships.RelationshipFilter(source_external_ids: SequenceNotStr[str] | None = None, source_types: SequenceNotStr[str] | None = None, target_external_ids: SequenceNotStr[str] | None = None, target_types: SequenceNotStr[str] | None = None, data_set_ids: Sequence[dict[str, Any]] | None = None, start_time: dict[str, int] | None = None, end_time: dict[str, int] | None = None, confidence: dict[str, int] | None = None, last_updated_time: dict[str, int] | None = None, created_time: dict[str, int] | None = None, active_at_time: dict[str, int] | None = None, labels: LabelFilter | None = None)

Bases: CogniteFilter

Filter on relationships with exact match. Multiple filter elements in one property, e.g. sourceExternalIds: [ “a”, “b” ], will return all relationships where the sourceExternalId field is either a or b. Filters in multiple properties will return the relationships that match all criteria. If the filter is not specified it default to an empty filter.

Parameters
  • source_external_ids (SequenceNotStr[str] | None) – Include relationships that have any of these values in their sourceExternalId field

  • source_types (SequenceNotStr[str] | None) – Include relationships that have any of these values in their sourceType field

  • target_external_ids (SequenceNotStr[str] | None) – Include relationships that have any of these values in their targetExternalId field

  • target_types (SequenceNotStr[str] | None) – Include relationships that have any of these values in their targetType field

  • data_set_ids (Sequence[dict[str, Any]] | None) – Either one of internalId (int) or externalId (str)

  • start_time (dict[str, int] | None) – Range between two timestamps, minimum and maximum milliseconds (inclusive)

  • end_time (dict[str, int] | None) – Range between two timestamps, minimum and maximum milliseconds (inclusive)

  • confidence (dict[str, int] | None) – Range to filter the field for (inclusive).

  • last_updated_time (dict[str, int] | None) – Range to filter the field for (inclusive).

  • created_time (dict[str, int] | None) – Range to filter the field for (inclusive).

  • active_at_time (dict[str, int] | None) – Limits results to those active at any point within the given time range, i.e. if there is any overlap in the intervals [activeAtTime.min, activeAtTime.max] and [startTime, endTime], where both intervals are inclusive. If a relationship does not have a startTime, it is regarded as active from the beginning of time by this filter. If it does not have an endTime is will be regarded as active until the end of time. Similarly, if a min is not supplied to the filter, the min will be implicitly set to the beginning of time, and if a max is not supplied, the max will be implicitly set to the end of time.

  • labels (LabelFilter | None) – Return only the resource matching the specified label constraints.

dump(camel_case: bool = True) dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

class cognite.client.data_classes.relationships.RelationshipList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[RelationshipWrite, Relationship], ExternalIDTransformerMixin

as_write() RelationshipWriteList

Returns this RelationshipList in its writing version.

class cognite.client.data_classes.relationships.RelationshipUpdate(external_id: str)

Bases: CogniteUpdate

Update applied to a single relationship

Parameters

external_id (str) – The external ID provided by the client. Must be unique for the resource type.

class cognite.client.data_classes.relationships.RelationshipWrite(external_id: str, source_external_id: str, source_type: RelationshipType, target_external_id: str, target_type: RelationshipType, start_time: int | None = None, end_time: int | None = None, confidence: float | None = None, data_set_id: int | None = None, labels: SequenceNotStr[Label | str | LabelDefinitionWrite | dict] | None = None)

Bases: RelationshipCore

Representation of a relationship in CDF, consists of a source and a target and some additional parameters. This is the writing version of the relationship class, and is used when creating new relationships.

Parameters
  • external_id (str) – External id of the relationship, must be unique within the project.

  • source_external_id (str) – External id of the CDF resource that constitutes the relationship source.

  • source_type (RelationshipType) – The CDF resource type of the relationship source. Must be one of the specified values.

  • target_external_id (str) – External id of the CDF resource that constitutes the relationship target.

  • target_type (RelationshipType) – The CDF resource type of the relationship target. Must be one of the specified values.

  • start_time (int | None) – Time, in milliseconds since Jan. 1, 1970, when the relationship became active. If there is no startTime, relationship is active from the beginning of time until endTime.

  • end_time (int | None) – Time, in milliseconds since Jan. 1, 1970, when the relationship became inactive. If there is no endTime, relationship is active from startTime until the present or any point in the future. If endTime and startTime are set, then endTime must be strictly greater than startTime.

  • confidence (float | None) – Confidence value of the existence of this relationship. Generated relationships should provide a realistic score on the likelihood of the existence of the relationship. Relationships without a confidence value can be interpreted at the discretion of each project.

  • data_set_id (int | None) – The id of the dataset this relationship belongs to.

  • labels (SequenceNotStr[Label | str | LabelDefinitionWrite | dict] | None) – A list of the labels associated with this resource item.

as_write() RelationshipWrite

Returns this RelationshipWrite instance.

class cognite.client.data_classes.relationships.RelationshipWriteList(resources: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[RelationshipWrite], ExternalIDTransformerMixin