Data Organization¶

Annotations¶

Retrieve an annotation by id¶

AnnotationsAPI.retrieve(id: int) → Optional[cognite.client.data_classes.annotations.Annotation]¶

Retrieve an annotation by id

Parameters:	id (int) – id of the annotation to be retrieved
Returns:	annotation requested
Return type:	Annotation

Retrieve multiple annotations by id¶

AnnotationsAPI.retrieve_multiple(ids: Sequence[int]) → cognite.client.data_classes.annotations.AnnotationList¶

Retrieve annotations by IDs

Parameters:	(Sequence[int]] (ids) – list of IDs to be retrieved
Returns:	list of annotations
Return type:	AnnotationList

List annotation¶

AnnotationsAPI.list(filter: Union[cognite.client.data_classes.annotations.AnnotationFilter, Dict[KT, VT]], limit: int = 25) → cognite.client.data_classes.annotations.AnnotationList¶

List annotations.

Parameters:	limit (int) – Maximum number of annotations to return. Defaults to 25. filter (AnnotationFilter) – Return annotations with parameter values that matches what is specified. Note that annotated_resource_type and annotated_resource_ids are always required.
Returns:	list of annotations
Return type:	AnnotationList

Create an annotation¶

AnnotationsAPI.create(annotations: Union[cognite.client.data_classes.annotations.Annotation, Sequence[cognite.client.data_classes.annotations.Annotation]]) → Union[cognite.client.data_classes.annotations.Annotation, cognite.client.data_classes.annotations.AnnotationList]¶

Create annotations

Parameters:	annotations (Union[Annotation, Sequence[Annotation]]) – annotation(s) to create
Returns:	created annotation(s)
Return type:	Union[Annotation, AnnotationList]

Suggest an annotation¶

AnnotationsAPI.suggest(annotations: Union[cognite.client.data_classes.annotations.Annotation, Sequence[cognite.client.data_classes.annotations.Annotation]]) → Union[cognite.client.data_classes.annotations.Annotation, cognite.client.data_classes.annotations.AnnotationList]¶

Suggest annotations

Parameters:	annotations (Union[Annotation, Sequence[Annotation]]) – annotation(s) to suggest. They must have status set to “suggested”.
Returns:	suggested annotation(s)
Return type:	Union[Annotation, AnnotationList]

Update annotations¶

AnnotationsAPI.update(item: Union[cognite.client.data_classes.annotations.Annotation, cognite.client.data_classes.annotations.AnnotationUpdate, Sequence[Union[cognite.client.data_classes.annotations.Annotation, cognite.client.data_classes.annotations.AnnotationUpdate]]]) → Union[cognite.client.data_classes.annotations.Annotation, cognite.client.data_classes.annotations.AnnotationList]¶

Update annotations

Parameters:	item (Union[Annotation, AnnotationUpdate, Sequence[Union[Annotation, AnnotationUpdate]]]) – Annotation or list of annotations to update (or patch or list of patches to apply)

Delete annotations¶

AnnotationsAPI.delete(id: Union[int, Sequence[int]]) → None¶

Delete annotations

Parameters:	id (Union[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: Optional[str], annotated_resource_type: str, annotated_resource_id: Optional[int] = None)¶

Bases: cognite.client.data_classes._base.CogniteResource

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”.
annotated_resource_type (str) – Type name of the CDF resource that is annotated, e.g. “file”.
annotated_resource_id (int, optional) – The internal ID of the annotated resource.
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, 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.
id (int, optional) – A server-generated id for the object. Read-only.
created_time (int, optional) – Time when this annotation was created in CDF. The time is measured in milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds. Read-only.
last_updated_time (int, optional) – Time when this annotation was last updated in CDF. The time is measured in milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds. Read-only.
cognite_client (CogniteClient, optional) – The client to associate with this object. Read-only.

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
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: Optional[str] = None, creating_user: Optional[str] = '', creating_app: Optional[str] = None, creating_app_version: Optional[str] = None, annotation_type: Optional[str] = None, data: Optional[Dict[str, Any]] = None)¶

Bases: cognite.client.data_classes._base.CogniteFilter

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, Any]]) – 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, optional) – Status of annotations to filter for, e.g. “suggested”, “approved”, “rejected”.
creating_user (str, optional) – 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, optional) – Name of the app from which the annotations to filter for where created.
creating_app_version (str, optional) – Version of the app from which the annotations to filter for were created.
annotation_type (str, optional) – Type name of the annotations.
data (Dict[str, Any], optional) – The annotation data to filter by. Example format: {“label”: “cat”, “confidence”: 0.9}

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

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

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

Bases: cognite.client.data_classes._base.CogniteUpdate

Changes applied to annotation

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

Data sets¶

Retrieve an data set by id¶

DataSetsAPI.retrieve(id: Optional[int] = None, external_id: Optional[str] = None) → Optional[cognite.client.data_classes.data_sets.DataSet]¶

Retrieve a single data set by id.

Parameters:	id (int, optional) – ID external_id (str, optional) – External ID
Returns:	Requested data set or None if it does not exist.
Return type:	Optional[DataSet]

Examples

Get data set by id:

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

Get data set by external id:

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

Retrieve multiple data sets by id¶

DataSetsAPI.retrieve_multiple(ids: Optional[Sequence[int]] = None, external_ids: Optional[Sequence[str]] = None, ignore_unknown_ids: bool = False) → cognite.client.data_classes.data_sets.DataSetList¶

Retrieve multiple data sets by id.

Parameters:	ids (Sequence[int], optional) – IDs external_ids (Sequence[str], optional) – 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
>>> c = CogniteClient()
>>> res = c.data_sets.retrieve_multiple(ids=[1, 2, 3])

Get data sets by external id:

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

List data sets¶

DataSetsAPI.list(metadata: Optional[Dict[str, str]] = None, created_time: Union[Dict[str, Any], cognite.client.data_classes.shared.TimestampRange, None] = None, last_updated_time: Union[Dict[str, Any], cognite.client.data_classes.shared.TimestampRange, None] = None, external_id_prefix: Optional[str] = None, write_protected: Optional[bool] = None, limit: int = 25) → cognite.client.data_classes.data_sets.DataSetList¶

List data sets

Parameters:	metadata (Dict[str, str]) – Custom, application-specific metadata. String key -> String value. created_time (Union[Dict[str, Any], TimestampRange]) – Range between two timestamps. last_updated_time (Union[Dict[str, Any], TimestampRange]) – Range between two timestamps. external_id_prefix (str) – Filter by this (case-sensitive) prefix for the external ID. write_protected (bool) – Specify whether the filtered data sets are write-protected, or not. Set to True to only list write-protected data sets. limit (int, optional) – 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
>>> c = CogniteClient()
>>> data_sets_list = c.data_sets.list(limit=5, write_protected=False)

Iterate over data sets:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for data_set in c.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
>>> c = CogniteClient()
>>> for data_set_list in c.data_sets(chunk_size=2500):
...     data_set_list # do something with the list

Aggregate data sets¶

DataSetsAPI.aggregate(filter: Union[cognite.client.data_classes.data_sets.DataSetFilter, Dict[KT, VT], None] = None) → List[cognite.client.data_classes.data_sets.DataSetAggregate]¶

Aggregate data sets

Parameters:	filter (Union[DataSetFilter, Dict]) – Filter on data set filter with exact match
Returns:	List of data set aggregates
Return type:	List[DataSetAggregate]

Examples

Aggregate data_sets:

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

Create data sets¶

DataSetsAPI.create(data_set: Union[cognite.client.data_classes.data_sets.DataSet, Sequence[cognite.client.data_classes.data_sets.DataSet]]) → Union[cognite.client.data_classes.data_sets.DataSet, cognite.client.data_classes.data_sets.DataSetList]¶

Create one or more data sets.

Parameters:	data_set – Union[DataSet, Sequence[DataSet]]: Data set or list of data sets to create.
Returns:	Created data set(s)
Return type:	Union[DataSet, DataSetList]

Examples

Create new data sets:

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

Delete data sets¶

This functionality is not yet available in the API.

Update data sets¶

DataSetsAPI.update(item: Union[cognite.client.data_classes.data_sets.DataSet, cognite.client.data_classes.data_sets.DataSetUpdate, Sequence[Union[cognite.client.data_classes.data_sets.DataSet, cognite.client.data_classes.data_sets.DataSetUpdate]]]) → Union[cognite.client.data_classes.data_sets.DataSet, cognite.client.data_classes.data_sets.DataSetList]¶

Update one or more data sets

Parameters:	item – Union[DataSet, DataSetUpdate, Sequence[Union[DataSet, DataSetUpdate]]]: Data set(s) to update
Returns:	Updated data set(s)
Return type:	Union[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
>>> c = CogniteClient()
>>> data_set = c.data_sets.retrieve(id=1)
>>> data_set.description = "New description"
>>> res = c.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
>>> c = CogniteClient()
>>> my_update = DataSetUpdate(id=1).description.set("New description").metadata.remove(["key"])
>>> res = c.data_sets.update(my_update)

Data Sets Data classes¶

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

Bases: cognite.client.data_classes._base.CogniteResource

No description.

Parameters:

external_id (str) – The external ID provided by the client. Must be unique for the resource type.
name (str) – The name of the data set.
description (str) – The description of the data set.
metadata (Dict[str, str]) – 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) – 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) – A server-generated ID for the object.
created_time (int) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
last_updated_time (int) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
cognite_client (CogniteClient) – The client to associate with this object.

class cognite.client.data_classes.data_sets.DataSetAggregate(count: Optional[int] = None, **kwargs)¶

Bases: dict

Aggregation group of data sets

Parameters:	count (int) – Size of the aggregation group

class cognite.client.data_classes.data_sets.DataSetFilter(metadata: Dict[str, str] = None, created_time: Union[Dict[str, Any], TimestampRange] = None, last_updated_time: Union[Dict[str, Any], TimestampRange] = None, external_id_prefix: str = None, write_protected: bool = None, cognite_client: CogniteClient = None)¶

Bases: cognite.client.data_classes._base.CogniteFilter

Filter on data sets with strict matching.

Parameters:

metadata (Dict[str, str]) – 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 (Union[Dict[str, Any], TimestampRange]) – Range between two timestamps.
last_updated_time (Union[Dict[str, Any], TimestampRange]) – Range between two timestamps.
external_id_prefix (str) – Filter by this (case-sensitive) prefix for the external ID.
write_protected (bool) – No description.
cognite_client (CogniteClient) – The client to associate with this object.

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

class cognite.client.data_classes.data_sets.DataSetUpdate(id: Optional[int] = None, external_id: Optional[str] = None)¶

Bases: cognite.client.data_classes._base.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.

Labels¶

List labels¶

LabelsAPI.list(name: Optional[str] = None, external_id_prefix: Optional[str] = None, data_set_ids: Union[int, Sequence[int], None] = None, data_set_external_ids: Union[str, Sequence[str], None] = None, limit: int = 25) → cognite.client.data_classes.labels.LabelDefinitionList¶

List Labels

Parameters:	name (str) – returns the label definitions matching that name data_set_ids (Union[int, Sequence[int]]) – return only labels in the data sets with this id / these ids. data_set_external_ids (Union[str, Sequence[str]]) – return only labels in the data sets with this external id / these external ids. external_id_prefix (str) – filter label definitions with external ids starting with the prefix specified limit (int, optional) – Maximum number of label definitions to return.
Returns:	List of requested Labels
Return type:	LabelDefinitionList

Examples

List Labels and filter on name:

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

Iterate over label definitions:

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

Iterate over chunks of label definitions to reduce memory load:

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

Create a label¶

LabelsAPI.create(label: Union[cognite.client.data_classes.labels.LabelDefinition, Sequence[cognite.client.data_classes.labels.LabelDefinition]]) → Union[cognite.client.data_classes.labels.LabelDefinition, cognite.client.data_classes.labels.LabelDefinitionList]¶

Create one or more label definitions.

Parameters:	Label (Union[LabelDefinition, Sequence[LabelDefinition]]) – label definition or a list of label definitions to create.
Returns:	Created label definition(s)
Return type:	Union[LabelDefinition, LabelDefinitionList]

Examples

Create new label definitions:

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

Delete labels¶

LabelsAPI.delete(external_id: Union[str, Sequence[str], None] = None) → None¶

Delete one or more label definitions

Parameters:	external_id (Union[str, Sequence[str]]) – One or more label external ids
Returns:	None

Examples

Delete label definitions by external id:

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

Labels Data classes¶

class cognite.client.data_classes.labels.Label(external_id: Optional[str] = None, **kwargs)¶

Bases: dict

A label assigned to a resource.

Parameters:	external_id (str) – The external id to the attached label.

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

Bases: cognite.client.data_classes._base.CogniteResource

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.

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) – Description of the label.
created_time (int) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
data_set_id (int) – The id of the dataset this label belongs to.
cognite_client (CogniteClient) – The client to associate with this object.

class cognite.client.data_classes.labels.LabelDefinitionFilter(name: str = None, external_id_prefix: str = None, data_set_ids: List[Dict[str, Any]] = None, cognite_client: CogniteClient = None)¶

Bases: cognite.client.data_classes._base.CogniteFilter

Filter on labels definitions with strict matching.

Parameters:	name (str) – Returns the label definitions matching that name. external_id_prefix (str) – filter label definitions with external ids starting with the prefix specified data_set_ids (List[Dict[str, Any]]) – Only include labels that belong to these datasets. cognite_client (CogniteClient) – The client to associate with this object.

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

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

Bases: dict, cognite.client.data_classes._base.CogniteFilter

Return only the resource matching the specified label constraints.

Parameters:	contains_any (List[str]) – 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]) – The resource item contains all the listed labels. The labels are defined by a list of external ids. cognite_client (CogniteClient) – 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 = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
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) → Optional[cognite.client.data_classes.relationships.Relationship]¶

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:	Optional[Relationship]

Examples

Get relationship by external id:

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

Retrieve multiple relationships by external id¶

RelationshipsAPI.retrieve_multiple(external_ids: Sequence[str], fetch_resources: bool = False) → cognite.client.data_classes.relationships.RelationshipList¶

Retrieve multiple relationships by external id.

Parameters:	external_ids (Sequence[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.
Returns:	The requested relationships.
Return type:	RelationshipList

Examples

Get relationships by external id:

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

List relationships¶

RelationshipsAPI.list(source_external_ids: Optional[Sequence[str]] = None, source_types: Optional[Sequence[str]] = None, target_external_ids: Optional[Sequence[str]] = None, target_types: Optional[Sequence[str]] = None, data_set_ids: Union[int, Sequence[int], None] = None, data_set_external_ids: Union[str, Sequence[str], None] = None, start_time: Optional[Dict[str, int]] = None, end_time: Optional[Dict[str, int]] = None, confidence: Optional[Dict[str, int]] = None, last_updated_time: Optional[Dict[str, int]] = None, created_time: Optional[Dict[str, int]] = None, active_at_time: Optional[Dict[str, int]] = None, labels: Optional[cognite.client.data_classes.labels.LabelFilter] = None, limit: int = 100, partitions: Optional[int] = None, fetch_resources: bool = False) → cognite.client.data_classes.relationships.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 (Sequence[str]) – Include relationships that have any of these values in their source External Id field source_types (Sequence[str]) – Include relationships that have any of these values in their source Type field target_external_ids (Sequence[str]) – Include relationships that have any of these values in their target External Id field target_types (Sequence[str]) – Include relationships that have any of these values in their target Type field data_set_ids (Union[int, Sequence[int]]) – Return only relationships in the specified data set(s) with this id / these ids. data_set_external_ids (Union[str, Sequence[str]]) – Return only relationships in the specified data set(s) with this external id / these external ids. start_time (Dict[str, int]) – Range between two timestamps, minimum and maximum milli seconds (inclusive) end_time (Dict[str, int]) – Range between two timestamps, minimum and maximum milli seconds (inclusive) confidence (Dict[str, int]) – Range to filter the field for (inclusive). last_updated_time (Dict[str, Any]) – Range to filter the field for (inclusive). created_time (Dict[str, int]) – Range to filter the field for (inclusive). active_at_time (Dict[str, int]) – 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 begining 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) – Return only the resource matching the specified label constraints. limit (int) – Maximum number of relationships to return. Defaults to 100. Set to -1, float(“inf”) or None to return all items. partitions (int) – 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
>>> c = CogniteClient()
>>> relationship_list = c.relationships.list(limit=5)

Iterate over relationships:

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

Create a relationship¶

RelationshipsAPI.create(relationship: Union[cognite.client.data_classes.relationships.Relationship, Sequence[cognite.client.data_classes.relationships.Relationship]]) → Union[cognite.client.data_classes.relationships.Relationship, cognite.client.data_classes.relationships.RelationshipList]¶

Create one or more relationships.

Parameters:	relationship (Union[Relationship, Sequence[Relationship]]) – Relationship or list of relationships to create.
Returns:	Created relationship(s)
Return type:	Union[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
>>> c = 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 = c.relationships.create([flowrel1,flowrel2])

Update relationships¶

RelationshipsAPI.update(item: Union[cognite.client.data_classes.relationships.Relationship, cognite.client.data_classes.relationships.RelationshipUpdate, Sequence[Union[cognite.client.data_classes.relationships.Relationship, cognite.client.data_classes.relationships.RelationshipUpdate]]]) → Union[cognite.client.data_classes.relationships.Relationship, cognite.client.data_classes.relationships.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 (Union[Relationship, RelationshipUpdate, Sequence[Union[Relationship, RelationshipUpdate]]]) – Relationship(s) to update
Returns:	Updated relationship(s)
Return type:	Union[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
>>> c = CogniteClient()
>>> rel = c.relationships.retrieve(external_id="flow1")
>>> rel.confidence = 0.75
>>> res = c.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
>>> c = CogniteClient()
>>> my_update = RelationshipUpdate(external_id="flow_1").source_external_id.set("alternate_source").confidence.set(0.97)
>>> res1 = c.relationships.update(my_update)
>>> # Remove an already set optional field like so
>>> another_update = RelationshipUpdate(external_id="flow_1").confidence.set(None)
>>> res2 = c.relationships.update(another_update)

Attach labels to a relationship:

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

Detach a single label from a relationship:

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

Delete relationships¶

RelationshipsAPI.delete(external_id: Union[str, Sequence[str]], ignore_unknown_ids: bool = False) → None¶

Delete one or more relationships.

Parameters:	external_id (Union[str, Sequence[str]]) – External ID or list of external ids ignore_unknown_ids (bool) – Ignore external IDs that are not found rather than throw an exception.
Returns:	None

Examples

Delete relationships by external id:

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

Relationship Data classes¶

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

Bases: cognite.client.data_classes._base.CogniteResource

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

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 (str) – The CDF resource type of the relationship source. Must be one of the specified values.
source (Union[Asset, TimeSeries, FileMetadata, Event, Sequence, Dict]) – The full resource referenced by the source_external_id and source_type fields.
target_external_id (str) – External id of the CDF resource that constitutes the relationship target.
target_type (str) – The CDF resource type of the relationship target. Must be one of the specified values.
target (Union[Asset, TimeSeries, FileMetadata, Event, Sequence, Dict]) – The full resource referenced by the target_external_id and target_type fields.
start_time (int) – 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) – 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) – 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) – The id of the dataset this relationship belongs to.
labels (SequenceType[Label]) – A list of the labels associated with this resource item.
created_time (int) – Time, in milliseconds since Jan. 1, 1970, when this relationship was created in CDF.
last_updated_time (int) – Time, in milliseconds since Jan. 1, 1970, when this relationship was last updated in CDF.
cognite_client (CogniteClient) – The client to associate with this object.

class cognite.client.data_classes.relationships.RelationshipFilter(source_external_ids: SequenceType[str] = None, source_types: SequenceType[str] = None, target_external_ids: SequenceType[str] = None, target_types: SequenceType[str] = None, data_set_ids: SequenceType[Dict[str, Any]] = None, start_time: Dict[str, int] = None, end_time: Dict[str, int] = None, confidence: Dict[str, int] = None, last_updated_time: Dict[str, int] = None, created_time: Dict[str, int] = None, active_at_time: Dict[str, int] = None, labels: LabelFilter = None, cognite_client: CogniteClient = None)¶

Bases: cognite.client.data_classes._base.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 (Sequence[str]) – Include relationships that have any of these values in their sourceExternalId field
source_types (Sequence[str]) – Include relationships that have any of these values in their sourceType field
target_external_ids (Sequence[str]) – Include relationships that have any of these values in their targetExternalId field
target_types (Sequence[str]) – Include relationships that have any of these values in their targetType field
data_set_ids (Sequence[Dict[str, Any]]) – Either one of internalId (int) or externalId (str)
start_time (Dict[str, int]) – Range between two timestamps, minimum and maximum milliseconds (inclusive)
end_time (Dict[str, int]) – Range between two timestamps, minimum and maximum milliseconds (inclusive)
confidence (Dict[str, int]) – Range to filter the field for (inclusive).
last_updated_time (Dict[str, Any]) – Range to filter the field for (inclusive).
created_time (Dict[str, int]) – Range to filter the field for (inclusive).
active_at_time (Dict[str, int]) – 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 begining 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) – Return only the resource matching the specified label constraints.
cognite_client (CogniteClient) – The client to associate with this object.

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
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)¶: Bases: cognite.client.data_classes._base.CogniteResourceList

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

Bases: cognite.client.data_classes._base.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.