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:
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: 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¶ -
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: 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]¶ -
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]¶ -
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]¶ -
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¶ -
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: 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: 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¶ -
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: 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.