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

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[str, Any] | None = None) → list[CountAggregate]

Aggregate data sets

Parameters: filter (DataSetFilter | dict[str, Any] | 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

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.

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)

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.

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

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.

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

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

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]

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