Quickstart

Authenticate

The preferred way to authenticate against the Cognite API is by setting the COGNITE_API_KEY environment variable. All examples in this documentation require that the variable has been set.

$ export COGNITE_API_KEY = <your-api-key>

You can also pass your API key directly to the CogniteClient.

>>> from cognite.client import CogniteClient
>>> c = CogniteClient(api_key="<your-api-key>", client_name="<your-client-name>")

Instantiate a new client

Use this code to instantiate a client and get your login status. CDF returns an object with attributes that describe which project and service account your API key belongs to. The client_name is an user-defined string intended to give the client a unique identifier. You can provide the client_name through the COGNITE_CLIENT_NAME environment variable or by passing it directly to the CogniteClient constructor. All examples in this documentation assume that COGNITE_CLIENT_NAME has been set.

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> status = c.login.status()

Read more about the CogniteClient and the functionality it exposes below.

Discover time series

For the next examples, you will need to supply ids for the time series that you want to retrieve. You can find some ids by listing the available time series. Limits for listing resources default to 25, so the following code will return the first 25 time series resources.

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> ts_list = c.time_series.list(include_metadata=False)

Plot time series

There are several ways of plotting a time series you have fetched from the API. The easiest is to call .plot() on the returned TimeSeries or TimeSeriesList objects. By default, this plots the raw data points for the last 24 hours. If there are no data points for the last 24 hours, plot will throw an exception.

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> my_time_series = c.time_series.retrieve(id=<time-series-id>)
>>> my_time_series.plot()

You can also pass arguments to the .plot() method to change the start, end, aggregates, and granularity of the request.

>>> my_time_series.plot(start="365d-ago", end="now", aggregates=["average"], granularity="1d")

The Datapoints and DatapointsList objects that are returned when you fetch data points, also have .plot() methods you can use to plot the data.

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> my_datapoints = c.datapoints.retrieve(
...                     id=[<time-series-ids>],
...                     start="10d-ago",
...                     end="now",
...                     aggregates=["max"],
...                     granularity="1h"
...                 )
>>> my_datapoints.plot()

Note

To use the .plot() functionality you need to install matplotlib.

Create an asset hierarchy

CDF organizes digital information about the physical world. Assets are digital representations of physical objects or groups of objects, and assets are organized into an asset hierarchy. For example, an asset can represent a water pump which is part of a subsystem on an oil platform.

At the top of an asset hierarchy is a root asset (e.g., the oil platform). Each project can have multiple root assets. All assets have a name and a parent asset. No assets with the same parent can have the same name.

To create a root asset (an asset without a parent), omit the parent ID when you post the asset to the API. To make an asset a child of an existing asset, you must specify a parent ID.

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import Asset
>>> c = CogniteClient()
>>> my_asset = Asset(name="my first asset", parent_id=123)
>>> c.assets.create(my_asset)

To post an entire asset hierarchy, you can describe the relations within your asset hierarchy using the external_id and parent_external_id attributes on the Asset object. You can post an arbitrary number of assets, and the SDK will split the request into multiple requests and create the assets in the correct order

This example shows how to post a three levels deep asset hierarchy consisting of three assets.

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import Asset
>>> c = CogniteClient()
>>> root = Asset(name="root", external_id="1")
>>> child = Asset(name="child", external_id="2", parent_external_id="1")
>>> descendant = Asset(name="descendant", external_id="3", parent_external_id="2")
>>> c.assets.create([root, child, descendant])

Wrap the .create() call in a try-except to get information if posting the assets fails:

  • Which assets were posted. (The request yielded a 201.)
  • Which assets may have been posted. (The request yielded 5xx.)
  • Which assets were not posted. (The request yielded 4xx, or was a descendant of another asset which may or may not have been posted.)
>>> from cognite.client.exceptions import CogniteAPIError
>>> try:
...     c.create([root, child, descendant])
>>> except CogniteAPIError as e:
...     assets_posted = e.successful
...     assets_may_have_been_posted = e.unknown
...     assets_not_posted = e.failed

Settings

Client configuration

You can pass configuration arguments directly to the CogniteClient constructor, for example to configure the base url of your requests and additional headers. For a list of all configuration arguments, see the CogniteClient class definition.

Environment configuration

You can set default configurations with these environment variables:

# Can be overrided by Client Configuration
$ export COGNITE_API_KEY = <your-api-key>
$ export COGNITE_PROJECT = <your-default-project>
$ export COGNITE_BASE_URL = http://<host>:<port>
$ export COGNITE_CLIENT_NAME = <user-defined-client-or-app-name>
$ export COGNITE_MAX_WORKERS = <number-of-workers>
$ export COGNITE_TIMEOUT = <num-of-seconds>

# Global Configuration
$ export COGNITE_DISABLE_PYPI_VERSION_CHECK = "1"
$ export COGNITE_DISABLE_GZIP = "1"
$ export COGNITE_MAX_RETRIES = <number-of-retries>
$ export COGNITE_MAX_RETRY_BACKOFF = <number-of-seconds>
$ export COGNITE_MAX_CONNECTION_POOL_SIZE = <number-of-connections-in-pool>
$ export COGNITE_STATUS_FORCELIST = "429,502,503"

Concurrency and connection pooling

This library does not expose API limits to the user. If your request exceeds API limits, the SDK splits your request into chunks and performs the sub-requests in parallel. To control how many concurrent requests you send to the API, you can either pass the max_workers attribute when you instantiate the CogniteClient or set the COGNITE_MAX_WORKERS environment variable.

If you are working with multiple instances of CogniteClient, all instances will share the same connection pool. If you have several instances, you can increase the max connection pool size to reuse connections if you are performing a large amount of concurrent requests. You can increase the max connection pool size by setting the COGNITE_MAX_CONNECTION_POOL_SIZE environment variable.

Extensions and core library

Pandas integration

The SDK is tightly integrated with the pandas library. You can use the .to_pandas() method on pretty much any object and get a pandas data frame describing the data.

This is particularly useful when you are working with time series data and with tabular data from the Raw API.

Matplotlib integration

You can use the .plot() method on any time series or data points result that the SDK returns. The method takes keyword arguments which are passed on to the underlying matplotlib plot function, allowing you to configure for example the size and layout of your plots.

You need to install the matplotlib package manually:

$ pip install matplotlib

cognite-sdk vs. cognite-sdk-core

If your application doesn’t require the functionality from the pandas or numpy dependencies, you should install the cognite-sdk-core library.

The two libraries are exactly the same, except that cognite-sdk-core does not specify pandas or numpy as dependencies. This means that cognite-sdk-core only has a subset of the features available through the cognite-sdk package. If you attempt to use functionality that cognite-sdk-core does not support, a CogniteImportError is raised.

API

CogniteClient

class cognite.client.CogniteClient(api_key: str = None, project: str = None, client_name: str = None, base_url: str = None, max_workers: int = None, headers: Dict[str, str] = None, timeout: int = None, debug: bool = False)

Main entrypoint into Cognite Python SDK.

All services are made available through this object. See examples below.

Parameters:
  • api_key (str) – API key
  • project (str) – Project. Defaults to project of given API key.
  • client_name (str) – A user-defined name for the client. Used to identify number of unique applications/scripts running on top of CDF.
  • base_url (str) – Base url to send requests to. Defaults to “https://api.cognitedata.com
  • max_workers (int) – Max number of workers to spawn when parallelizing data fetching. Defaults to 10.
  • headers (Dict) – Additional headers to add to all requests.
  • timeout (int) – Timeout on requests sent to the api. Defaults to 30 seconds.
  • debug (bool) – Configures logger to log extra request details to stderr.
get(url: str, params: Dict[str, Any] = None, headers: Dict[str, Any] = None)

Perform a GET request to an arbitrary path in the API.

post(url: str, json: Dict[str, Any], params: Dict[str, Any] = None, headers: Dict[str, Any] = None)

Perform a POST request to an arbitrary path in the API.

put(url: str, json: Dict[str, Any] = None, headers: Dict[str, Any] = None)

Perform a PUT request to an arbitrary path in the API.

delete(url: str, params: Dict[str, Any] = None, headers: Dict[str, Any] = None)

Perform a DELETE request to an arbitrary path in the API.

version

Returns the current SDK version.

Returns:The current SDK version
Return type:str
config

Returns a config object containing the configuration for the current client.

Returns:The configuration object.
Return type:ClientConfig

Authentication

Get login status

LoginAPI.status() → cognite.client.data_classes.login.LoginStatus

Check login status

Returns:The login status of the current api key.
Return type:LoginStatus

Examples

Check the current login status and get the project:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> login_status = c.login.status()
>>> project = login_status.project

Data classes

class cognite.client.data_classes.login.LoginStatus(user: str, project: str, logged_in: bool, project_id: str, api_key_id: int)

Bases: cognite.client.data_classes._base.CogniteResponse

Current login status

Parameters:
  • user (str) – Current user
  • logged_in (bool) – Is user logged in
  • project (str) – Current project
  • project_id (str) – Current project id
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]
to_pandas()

Assets

Retrieve an asset by id

AssetsAPI.retrieve(id: Optional[int] = None, external_id: Optional[str] = None) → Optional[cognite.client.data_classes.assets.Asset]

Retrieve a single asset by id.

Parameters:
  • id (int, optional) – ID
  • external_id (str, optional) – External ID
Returns:

Requested asset or None if it does not exist.

Return type:

Optional[Asset]

Examples

Get asset by id:

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

Get asset by external id:

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

Retrieve multiple assets by id

AssetsAPI.retrieve_multiple(ids: Optional[List[int]] = None, external_ids: Optional[List[str]] = None) → cognite.client.data_classes.assets.AssetList

Retrieve multiple assets by id.

Parameters:
  • ids (List[int], optional) – IDs
  • external_ids (List[str], optional) – External IDs
Returns:

The requested assets.

Return type:

AssetList

Examples

Get assets by id:

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

Get assets by external id:

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

Retrieve an asset subtree

AssetsAPI.retrieve_subtree(id: int = None, external_id: str = None, depth: int = None) → cognite.client.data_classes.assets.AssetList

Retrieve the subtree for this asset up to a specified depth.

Parameters:
  • id (int) – Id of the root asset in the subtree.
  • external_id (str) – External id of the root asset in the subtree.
  • depth (int) – Retrieve assets up to this depth below the root asset in the subtree. Omit to get the entire subtree.
Returns:

The requested assets.

Return type:

AssetList

List assets

AssetsAPI.list(name: str = None, parent_ids: List[int] = None, root_ids: List[Dict[str, Any]] = None, metadata: Dict[str, Any] = None, source: str = None, created_time: Dict[str, Any] = None, last_updated_time: Dict[str, Any] = None, root: bool = None, external_id_prefix: str = None, limit: int = 25) → cognite.client.data_classes.assets.AssetList

List assets

Parameters:
  • name (str) – Name of asset. Often referred to as tag.
  • parent_ids (List[int]) – List of parent ids to filter on.
  • root_ids (List[Dict[str, Any]]) – List of root ids/external ids to filter on.
  • metadata (Dict[str, Any]) – Custom, application specific metadata. String key -> String value
  • source (str) – The source of this asset
  • created_time (Dict[str, Any]) – Range between two timestamps
  • last_updated_time (Dict[str, Any]) – Range between two timestamps
  • root (bool) – filtered assets are root assets or not
  • external_id_prefix (str) – External Id provided by client. Should be unique within the project
  • limit (int, optional) – Maximum number of assets to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:

List of requested assets

Return type:

AssetList

Examples

List assets:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> asset_list = c.assets.list(limit=5)

Iterate over assets:

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

Iterate over chunks of assets to reduce memory load:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for asset_list in c.assets(chunk_size=2500):
...     asset_list # do something with the assets

Search for assets

AssetsAPI.search(name: str = None, description: str = None, filter: Union[cognite.client.data_classes.assets.AssetFilter, Dict[KT, VT]] = None, limit: int = None) → cognite.client.data_classes.assets.AssetList

Search for assets

Parameters:
  • name (str) – Fuzzy match on name.
  • description (str) – Fuzzy match on description.
  • filter (Union[AssetFilter, Dict]) – Filter to apply. Performs exact match on these fields.
  • limit (int) – Maximum number of results to return.
Returns:

List of requested assets

Return type:

AssetList

Examples

Search for assets:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.assets.search(name="some name")

Create assets

AssetsAPI.create(asset: Union[cognite.client.data_classes.assets.Asset, List[cognite.client.data_classes.assets.Asset]]) → Union[cognite.client.data_classes.assets.Asset, cognite.client.data_classes.assets.AssetList]

Create one or more assets.

Parameters:asset (Union[Asset, List[Asset]]) – Asset or list of assets to create.
Returns:Created asset(s)
Return type:Union[Asset, AssetList]

Examples

Create new assets:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import Asset
>>> c = CogniteClient()
>>> assets = [Asset(name="asset1"), Asset(name="asset2")]
>>> res = c.assets.create(assets)

Delete assets

AssetsAPI.delete(id: Union[int, List[int]] = None, external_id: Union[str, List[str]] = None, recursive: bool = False) → None

Delete one or more assets

Parameters:
  • id (Union[int, List[int]) – Id or list of ids
  • external_id (Union[str, List[str]]) – External ID or list of exgernal ids
  • recursive (bool) – Recursively delete whole asset subtrees under given ids. Defaults to False.
Returns:

None

Examples

Delete assets by id or external id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.assets.delete(id=[1,2,3], external_id="3")

Update assets

AssetsAPI.update(item: Union[cognite.client.data_classes.assets.Asset, cognite.client.data_classes.assets.AssetUpdate, List[Union[cognite.client.data_classes.assets.Asset, cognite.client.data_classes.assets.AssetUpdate]]]) → Union[cognite.client.data_classes.assets.Asset, cognite.client.data_classes.assets.AssetList]

Update one or more assets

Parameters:item (Union[Asset, AssetUpdate, List[Union[Asset, AssetUpdate]]]) – Asset(s) to update
Returns:Updated asset(s)
Return type:Union[Asset, AssetList]

Examples

Update an asset that you have fetched. This will perform a full update of the asset:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> asset = c.assets.retrieve(id=1)
>>> asset.description = "New description"
>>> res = c.assets.update(asset)

Perform a partial update on a asset, updating the description and adding a new field to metadata:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import AssetUpdate
>>> c = CogniteClient()
>>> my_update = AssetUpdate(id=1).description.set("New description").metadata.add({"key": "value"})
>>> res = c.assets.update(my_update)

Data classes

class cognite.client.data_classes.assets.Asset(external_id: str = None, name: str = None, parent_id: int = None, description: str = None, metadata: Dict[str, Any] = None, source: str = None, id: int = None, created_time: int = None, last_updated_time: int = None, root_id: int = None, parent_external_id: str = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

A representation of a physical asset, for example a factory or a piece of equipment.

Parameters:
  • external_id (str) – The external ID provided by the client. Must be unique within the project.
  • name (str) – The name of the asset.
  • parent_id (int) – A JavaScript-friendly internal ID for the object.
  • description (str) – The description of the asset.
  • metadata (Dict[str, Any]) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
  • source (str) – The source of the asset.
  • id (int) – A JavaScript-friendly internal 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.
  • root_id (int) – A JavaScript-friendly internal ID for the object.
  • parent_external_id (str) – The external ID provided by the client. Must be unique within the project.
  • cognite_client (CogniteClient) – The client to associate with this object.
children() → cognite.client.data_classes.assets.AssetList

Returns the children of this asset.

Returns:The requested assets
Return type:AssetList
events(**kwargs) → EventList

Retrieve all events related to this asset.

Returns:All events related to this asset.
Return type:EventList
files(**kwargs) → FileMetadataList

Retrieve all files metadata related to this asset.

Returns:Metadata about all files related to this asset.
Return type:FileMetadataList
parent() → cognite.client.data_classes.assets.Asset

Returns this assets parent.

Returns:The parent asset.
Return type:Asset
subtree(depth: int = None) → cognite.client.data_classes.assets.AssetList

Returns the subtree of this asset up to a specified depth.

Parameters:depth (int, optional) – Retrieve assets up to this depth below the asset.
Returns:The requested assets sorted topologically.
Return type:AssetList
time_series(**kwargs) → TimeSeriesList

Retrieve all time series related to this asset.

Returns:All time series related to this asset.
Return type:TimeSeriesList
class cognite.client.data_classes.assets.AssetFilter(name: str = None, parent_ids: List[int] = None, root_ids: List[Dict[str, Any]] = None, metadata: Dict[str, Any] = None, source: str = None, created_time: Dict[str, Any] = None, last_updated_time: Dict[str, Any] = None, root: bool = None, external_id_prefix: str = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteFilter

Filter on assets with strict matching.

Parameters:
  • name (str) – The name of the asset.
  • parent_ids (List[int]) – No description.
  • root_ids (List[Union[Dict[str, Any], Dict[str, Any]]]) – No description.
  • metadata (Dict[str, Any]) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
  • source (str) – The source of the asset.
  • created_time (Dict[str, Any]) – Range between two timestamps.
  • last_updated_time (Dict[str, Any]) – Range between two timestamps.
  • root (bool) – Whether the filtered assets are root assets, or not.
  • external_id_prefix (str) – The external ID provided by the client. Must be unique within the project.
  • cognite_client (CogniteClient) – The client to associate with this object.
class cognite.client.data_classes.assets.AssetList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

events() → EventList

Retrieve all events related to these assets.

Returns:All events related to the assets in this AssetList.
Return type:EventList
files() → FileMetadataList

Retrieve all files metadata related to these assets.

Returns:Metadata about all files related to the assets in this AssetList.
Return type:FileMetadataList
time_series() → TimeSeriesList

Retrieve all time series related to these assets.

Returns:All time series related to the assets in this AssetList.
Return type:TimeSeriesList
class cognite.client.data_classes.assets.AssetUpdate(id: int = None, external_id: str = None)

Bases: cognite.client.data_classes._base.CogniteUpdate

Changes applied to asset

Parameters:
  • id (int) – A JavaScript-friendly internal ID for the object.
  • external_id (str) – The external ID provided by the client. Must be unique within the project.

Events

Retrieve an event by id

EventsAPI.retrieve(id: Optional[int] = None, external_id: Optional[str] = None) → Optional[cognite.client.data_classes.events.Event]

Retrieve a single event by id.

Parameters:
  • id (int, optional) – ID
  • external_id (str, optional) – External ID
Returns:

Requested event or None if it does not exist.

Return type:

Optional[Event]

Examples

Get event by id:

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

Get event by external id:

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

Retrieve multiple events by id

EventsAPI.retrieve_multiple(ids: Optional[List[int]] = None, external_ids: Optional[List[str]] = None) → cognite.client.data_classes.events.EventList

Retrieve multiple events by id.

Parameters:
  • ids (List[int], optional) – IDs
  • external_ids (List[str], optional) – External IDs
Returns:

The requested events.

Return type:

EventList

Examples

Get events by id:

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

Get events by external id:

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

List events

EventsAPI.list(start_time: Dict[str, Any] = None, end_time: Dict[str, Any] = None, type: str = None, subtype: str = None, metadata: Dict[str, Any] = None, asset_ids: List[int] = None, root_asset_ids: List[Dict[str, Any]] = None, source: str = None, created_time: Dict[str, Any] = None, last_updated_time: Dict[str, Any] = None, external_id_prefix: str = None, limit: int = 25) → cognite.client.data_classes.events.EventList

List events

Parameters:
  • start_time (Dict[str, Any]) – Range between two timestamps
  • end_time (Dict[str, Any]) – Range between two timestamps
  • type (str) – Type of the event, e.g ‘failure’.
  • subtype (str) – Subtype of the event, e.g ‘electrical’.
  • metadata (Dict[str, Any]) – Customizable extra data about the event. String key -> String value.
  • asset_ids (List[int]) – Asset IDs of related equipments that this event relates to.
  • root_asset_ids (List[Dict[str, Any]]) – The IDs of the root assets that the related assets should be children of.
  • source (str) – The source of this event.
  • created_time (Dict[str, Any]) – Range between two timestamps
  • last_updated_time (Dict[str, Any]) – Range between two timestamps
  • external_id_prefix (str) – External Id provided by client. Should be unique within the project
  • limit (int, optional) – Maximum number of events to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:

List of requested events

Return type:

EventList

Examples

List events and filter on max start time:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> file_list = c.events.list(limit=5, start_time={"max": 1500000000})

Iterate over events:

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

Iterate over chunks of events to reduce memory load:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for event_list in c.events(chunk_size=2500):
...     event_list # do something with the files

Search for events

EventsAPI.search(description: str = None, filter: Union[cognite.client.data_classes.events.EventFilter, Dict[KT, VT]] = None, limit: int = None) → cognite.client.data_classes.events.EventList

Search for events

Parameters:
  • description (str) – Fuzzy match on description.
  • filter (Union[EventFilter, Dict]) – Filter to apply. Performs exact match on these fields.
  • limit (int) – Maximum number of results to return.
Returns:

List of requested events

Return type:

EventList

Examples

Search for events:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.events.search(description="some description")

Create events

EventsAPI.create(event: Union[cognite.client.data_classes.events.Event, List[cognite.client.data_classes.events.Event]]) → Union[cognite.client.data_classes.events.Event, cognite.client.data_classes.events.EventList]

Create one or more events.

Parameters:event (Union[Event, List[Event]]) – Event or list of events to create.
Returns:Created event(s)
Return type:Union[Event, EventList]

Examples

Create new events:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import Event
>>> c = CogniteClient()
>>> events = [Event(start_time=0, end_time=1), Event(start_time=2, end_time=3)]
>>> res = c.events.create(events)

Delete events

EventsAPI.delete(id: Union[int, List[int]] = None, external_id: Union[str, List[str]] = None) → None

Delete one or more events

Parameters:
  • id (Union[int, List[int]) – Id or list of ids
  • external_id (Union[str, List[str]]) – External ID or list of external ids
Returns:

None

Examples

Delete events by id or external id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.events.delete(id=[1,2,3], external_id="3")

Update events

EventsAPI.update(item: Union[cognite.client.data_classes.events.Event, cognite.client.data_classes.events.EventUpdate, List[Union[cognite.client.data_classes.events.Event, cognite.client.data_classes.events.EventUpdate]]]) → Union[cognite.client.data_classes.events.Event, cognite.client.data_classes.events.EventList]

Update one or more events

Parameters:item (Union[Event, EventUpdate, List[Union[Event, EventUpdate]]]) – Event(s) to update
Returns:Updated event(s)
Return type:Union[Event, EventList]

Examples

Update an event that you have fetched. This will perform a full update of the event:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> event = c.events.retrieve(id=1)
>>> event.description = "New description"
>>> res = c.events.update(event)

Perform a partial update on a event, updating the description and adding a new field to metadata:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import EventUpdate
>>> c = CogniteClient()
>>> my_update = EventUpdate(id=1).description.set("New description").metadata.add({"key": "value"})
>>> res = c.events.update(my_update)

Data classes

class cognite.client.data_classes.events.Event(external_id: str = None, start_time: int = None, end_time: int = None, type: str = None, subtype: str = None, description: str = None, metadata: Dict[str, Any] = None, asset_ids: List[int] = None, source: str = None, id: int = None, last_updated_time: int = None, created_time: int = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

An event represents something that happened at a given interval in time, e.g a failure, a work order etc.

Parameters:
  • external_id (str) – External Id provided by client. Should be unique within the project
  • start_time (int) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
  • end_time (int) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
  • type (str) – Type of the event, e.g ‘failure’.
  • subtype (str) – Subtype of the event, e.g ‘electrical’.
  • description (str) – Textual description of the event.
  • metadata (Dict[str, Any]) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
  • asset_ids (List[int]) – Asset IDs of related equipment that this event relates to.
  • source (str) – The source of this event.
  • id (int) – Javascript friendly internal ID given to the object.
  • last_updated_time (int) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
  • created_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.events.EventFilter(start_time: Dict[str, Any] = None, end_time: Dict[str, Any] = None, metadata: Dict[str, Any] = None, asset_ids: List[int] = None, root_asset_ids: List[Dict[str, Any]] = None, source: str = None, type: str = None, subtype: str = None, created_time: Dict[str, Any] = None, last_updated_time: Dict[str, Any] = None, external_id_prefix: str = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteFilter

Filter on events filter with exact match

Parameters:
  • start_time (Dict[str, Any]) – Range between two timestamps.
  • end_time (Dict[str, Any]) – Range between two timestamps.
  • metadata (Dict[str, Any]) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
  • asset_ids (List[int]) – Asset IDs of related equipment that this event relates to.
  • root_asset_ids (List[Union[Dict[str, Any], Dict[str, Any]]]) – The IDs of the root assets that the related assets should be children of.
  • source (str) – The source of this event.
  • type (str) – The event type
  • subtype (str) – The event subtype
  • created_time (Dict[str, Any]) – Range between two timestamps.
  • last_updated_time (Dict[str, Any]) – Range between two timestamps.
  • external_id_prefix (str) – External Id provided by client. Should be unique within the project
  • cognite_client (CogniteClient) – The client to associate with this object.
class cognite.client.data_classes.events.EventList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.client.data_classes.events.EventUpdate(id: int = None, external_id: str = None)

Bases: cognite.client.data_classes._base.CogniteUpdate

Changes will be applied to event.

Parameters:
  • id (int) – Javascript friendly internal ID given to the object.
  • external_id (str) – External Id provided by client. Should be unique within the project

Files

Retrieve file metadata by id

FilesAPI.retrieve(id: Optional[int] = None, external_id: Optional[str] = None) → Optional[cognite.client.data_classes.files.FileMetadata]

Retrieve a single file metadata by id.

Parameters:
  • id (int, optional) – ID
  • external_id (str, optional) – External ID
Returns:

Requested file metadata or None if it does not exist.

Return type:

Optional[FileMetadata]

Examples

Get file metadata by id:

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

Get file metadata by external id:

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

Retrieve multiple files’ metadata by id

FilesAPI.retrieve_multiple(ids: Optional[List[int]] = None, external_ids: Optional[List[str]] = None) → cognite.client.data_classes.files.FileMetadataList

Retrieve multiple file metadatas by id.

Parameters:
  • ids (List[int], optional) – IDs
  • external_ids (List[str], optional) – External IDs
Returns:

The requested file metadatas.

Return type:

FileMetadataList

Examples

Get file metadatas by id:

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

Get file_metadatas by external id:

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

List files metadata

FilesAPI.list(name: str = None, mime_type: str = None, metadata: Dict[str, Any] = None, asset_ids: List[int] = None, source: str = None, created_time: Dict[str, Any] = None, last_updated_time: Dict[str, Any] = None, uploaded_time: Dict[str, Any] = None, external_id_prefix: str = None, uploaded: bool = None, limit: int = 25) → cognite.client.data_classes.files.FileMetadataList

List files

Parameters:
  • name (str) – Name of the file.
  • mime_type (str) – File type. E.g. text/plain, application/pdf, ..
  • metadata (Dict[str, Any]) – Custom, application specific metadata. String key -> String value
  • asset_ids (List[int]) – Only include files that reference these specific asset IDs.
  • source (str) – The source of this event.
  • created_time (Dict[str, Any]) – Range between two timestamps
  • last_updated_time (Dict[str, Any]) – Range between two timestamps
  • uploaded_time (Dict[str, Any]) – Range between two timestamps
  • external_id_prefix (str) – External Id provided by client. Should be unique within the project.
  • uploaded (bool) – Whether or not the actual file is uploaded. This field is returned only by the API, it has no effect in a post body.
  • limit (int, optional) – Max number of files to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:

The requested files.

Return type:

FileMetadataList

Examples

List files metadata and filter on external id prefix:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> file_list = c.files.list(limit=5, external_id_prefix="prefix")

Iterate over files metadata:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for file_metadata in c.files:
...     file_metadata # do something with the file metadata

Iterate over chunks of files metadata to reduce memory load:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for file_list in c.files(chunk_size=2500):
...     file_list # do something with the files

Search for files

FilesAPI.search(name: str = None, filter: Union[cognite.client.data_classes.files.FileMetadataFilter, dict] = None, limit: int = None) → cognite.client.data_classes.files.FileMetadataList

Search for files.

Parameters:
  • name (str, optional) – Prefix and fuzzy search on name.
  • filter (Union[FileMetadataFilter, dict], optional) – Filter to apply. Performs exact match on these fields.
  • limit (int, optional) – Max number of results to return.
Returns:

List of requested files metadata.

Return type:

FileMetadataList

Examples

Search for a file:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.files.search(name="some name")

Upload a file or directory

FilesAPI.upload(path: str, external_id: str = None, name: str = None, source: str = None, mime_type: str = None, metadata: Dict[str, Any] = None, asset_ids: List[int] = None, recursive: bool = False, overwrite: bool = False) → Union[cognite.client.data_classes.files.FileMetadata, cognite.client.data_classes.files.FileMetadataList]

Upload a file

Parameters:
  • path (str) – Path to the file you wish to upload. If path is a directory, this method will upload all files in that directory.
  • external_id (str) – External Id provided by client. Should be unique within the project.
  • name (str) – No description.
  • source (str) – The source of the file.
  • mime_type (str) – File type. E.g. text/plain, application/pdf, …
  • metadata (Dict[str, Any]) – Customizable extra data about the file. String key -> String value.
  • asset_ids (List[int]) – No description.
  • recursive (bool) – If path is a directory, upload all contained files recursively.
  • overwrite (bool) – If ‘overwrite’ is set to true, and the POST body content specifies a ‘externalId’ field, fields for the file found for externalId can be overwritten. The default setting is false. If metadata is included in the request body, all of the original metadata will be overwritten. The actual file will be overwritten after successful upload. If there is no successful upload, the current file contents will be kept. File-Asset mappings only change if explicitly stated in the assetIds field of the POST json body. Do not set assetIds in request body if you want to keep the current file-asset mappings.
Returns:

The file metadata of the uploaded file(s).

Return type:

Union[FileMetadata, FileMetadataList]

Examples

Upload a file in a given path:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.files.upload("/path/to/file", name="my_file")

If name is omitted, this method will use the name of the file

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.files.upload("/path/to/file")

You can also upload all files in a directory by setting path to the path of a directory:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.files.upload("/path/to/my/directory")

Upload a string or bytes

FilesAPI.upload_bytes(content: Union[str, bytes, TextIO, BinaryIO], external_id: str = None, name: str = None, source: str = None, mime_type: str = None, metadata: Dict[str, Any] = None, asset_ids: List[int] = None, overwrite: bool = False)

Upload bytes or string.

You can also pass a file handle to content.

Parameters:
  • content (Union[str, bytes, TextIO, BinaryIO]) – The content to upload.
  • external_id (str) – External Id provided by client. Should be unique within the project.
  • name (str) – No description.
  • source (str) – The source of the file.
  • mime_type (str) – File type. E.g. text/plain, application/pdf,…
  • metadata (Dict[str, Any]) – Customizable extra data about the file. String key -> String value.
  • asset_ids (List[int]) – No description.
  • overwrite (bool) – If ‘overwrite’ is set to true, and the POST body content specifies a ‘externalId’ field, fields for the file found for externalId can be overwritten. The default setting is false. If metadata is included in the request body, all of the original metadata will be overwritten. The actual file will be overwritten after successful upload. If there is no successful upload, the current file contents will be kept. File-Asset mappings only change if explicitly stated in the assetIds field of the POST json body. Do not set assetIds in request body if you want to keep the current file-asset mappings.

Examples

Upload a file from memory:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.files.upload_bytes(b"some content", name="my_file", asset_ids=[1,2,3])

Download files to disk

FilesAPI.download(directory: str, id: Union[int, List[int]] = None, external_id: Union[str, List[str]] = None) → None

Download files by id or external id.

This method will stream all files to disk, never keeping more than 2MB of a given file in memory.

Parameters:
  • directory (str) – Directory to download the file(s) to.
  • id (Union[int, List[int]], optional) – Id or list of ids
  • external_id (Union[str, List[str]), optional) – External ID or list of external ids.
Returns:

None

Examples

Download files by id and external id into directory ‘my_directory’:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.files.download(directory="my_directory", id=[1,2,3], external_id=["abc", "def"])

Download a file as bytes

FilesAPI.download_bytes(id: int = None, external_id: str = None) → bytes

Download a file as bytes.

Parameters:
  • id (int, optional) – Id of the file
  • external_id (str, optional) – External id of the file

Examples

Download a file’s content into memory:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> file_content = c.files.download_bytes(id=1)

Delete files

FilesAPI.delete(id: Union[int, List[int]] = None, external_id: Union[str, List[str]] = None) → None

Delete files

Parameters:
  • id (Union[int, List[int]]) – Id or list of ids
  • external_id (Union[str, List[str]]) – str or list of str
Returns:

None

Examples

Delete files by id or external id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.files.delete(id=[1,2,3], external_id="3")

Update files metadata

FilesAPI.update(item: Union[cognite.client.data_classes.files.FileMetadata, cognite.client.data_classes.files.FileMetadataUpdate, List[Union[cognite.client.data_classes.files.FileMetadata, cognite.client.data_classes.files.FileMetadataUpdate]]]) → Union[cognite.client.data_classes.files.FileMetadata, cognite.client.data_classes.files.FileMetadataList]

Update files

Parameters:item (Union[FileMetadata, FileMetadataUpdate, List[Union[FileMetadata, FileMetadataUpdate]]]) – file(s) to update.
Returns:The updated files.
Return type:Union[FileMetadata, FileMetadataList]

Examples

Update file metadata that you have fetched. This will perform a full update of the file metadata:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> file_metadata = c.files.retrieve(id=1)
>>> file_metadata.description = "New description"
>>> res = c.files.update(file_metadata)

Perform a partial update on file metadata, updating the source and adding a new field to metadata:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import FileMetadataUpdate
>>> c = CogniteClient()
>>> my_update = FileMetadataUpdate(id=1).source.set("new source").metadata.add({"key": "value"})
>>> res = c.files.update(my_update)

Data classes

class cognite.client.data_classes.files.FileMetadata(external_id: str = None, name: str = None, source: str = None, mime_type: str = None, metadata: Dict[str, Any] = None, asset_ids: List[int] = None, id: int = None, uploaded: bool = None, uploaded_time: int = None, created_time: int = None, last_updated_time: int = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

No description.

Parameters:
  • external_id (str) – The external ID provided by the client. Must be unique within the project.
  • name (str) – Name of the file.
  • source (str) – The source of the file.
  • mime_type (str) – File type. E.g. text/plain, application/pdf, ..
  • metadata (Dict[str, Any]) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
  • asset_ids (List[int]) – No description.
  • id (int) – A JavaScript-friendly internal ID for the object.
  • uploaded (bool) – Whether or not the actual file is uploaded. This field is returned only by the API, it has no effect in a post body.
  • uploaded_time (int) – The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.
  • 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.files.FileMetadataFilter(name: str = None, mime_type: str = None, metadata: Dict[str, Any] = None, asset_ids: List[int] = None, source: str = None, created_time: Dict[str, Any] = None, last_updated_time: Dict[str, Any] = None, uploaded_time: Dict[str, Any] = None, external_id_prefix: str = None, uploaded: bool = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteFilter

No description.

Parameters:
  • name (str) – Name of the file.
  • mime_type (str) – File type. E.g. text/plain, application/pdf, ..
  • metadata (Dict[str, Any]) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
  • asset_ids (List[int]) – Only include files that reference these specific asset IDs.
  • source (str) – The source of this event.
  • created_time (Dict[str, Any]) – Range between two timestamps.
  • last_updated_time (Dict[str, Any]) – Range between two timestamps.
  • uploaded_time (Dict[str, Any]) – Range between two timestamps.
  • external_id_prefix (str) – The external ID provided by the client. Must be unique within the project.
  • uploaded (bool) – Whether or not the actual file is uploaded. This field is returned only by the API, it has no effect in a post body.
  • cognite_client (CogniteClient) – The client to associate with this object.
class cognite.client.data_classes.files.FileMetadataList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.client.data_classes.files.FileMetadataUpdate(id: int = None, external_id: str = None)

Bases: cognite.client.data_classes._base.CogniteUpdate

Changes will be applied to file.

Args:

Time series

Retrieve a time series by id

TimeSeriesAPI.retrieve(id: Optional[int] = None, external_id: Optional[str] = None) → Optional[cognite.client.data_classes.time_series.TimeSeries]

Retrieve a single time series by id.

Parameters:
  • id (int, optional) – ID
  • external_id (str, optional) – External ID
Returns:

Requested time series or None if it does not exist.

Return type:

Optional[TimeSeries]

Examples

Get time series by id:

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

Get time series by external id:

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

Retrieve multiple time series by id

TimeSeriesAPI.retrieve_multiple(ids: Optional[List[int]] = None, external_ids: Optional[List[str]] = None) → cognite.client.data_classes.time_series.TimeSeriesList

Retrieve multiple time series by id.

Parameters:
  • ids (List[int], optional) – IDs
  • external_ids (List[str], optional) – External IDs
Returns:

The requested time series.

Return type:

TimeSeriesList

Examples

Get time series by id:

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

Get time series by external id:

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

List time series

TimeSeriesAPI.list(include_metadata: bool = True, asset_ids: Optional[List[int]] = None, limit: int = 25) → cognite.client.data_classes.time_series.TimeSeriesList

Iterate over time series

Fetches time series as they are iterated over, so you keep a limited number of objects in memory.

Parameters:
  • include_metadata (bool, optional) – Whether or not to include metadata
  • asset_ids (List[int], optional) – List time series related to these assets.
  • limit (int, optional) – Max number of time series to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:

The requested time series.

Return type:

TimeSeriesList

Examples

List time series:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.time_series.list(limit=5)

Iterate over time series:

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

Iterate over chunks of time series to reduce memory load:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for ts_list in c.time_series(chunk_size=2500):
...     ts_list # do something with the time_series

Search for time series

TimeSeriesAPI.search(name: str = None, description: str = None, query: str = None, filter: Union[cognite.client.data_classes.time_series.TimeSeriesFilter, Dict[KT, VT]] = None, limit: int = None) → cognite.client.data_classes.time_series.TimeSeriesList

Search for time series.

Parameters:
  • name (str, optional) – Prefix and fuzzy search on name.
  • description (str, optional) – Prefix and fuzzy search on description.
  • query (str, optional) – Search on name and description using wildcard search on each of the words (separated by spaces). Retrieves results where at least one word must match. Example: ‘some other’
  • filter (Union[TimeSeriesFilter, Dict], optional) – Filter to apply. Performs exact match on these fields.
  • limit (int, optional) – Max number of results to return.
Returns:

List of requested time series.

Return type:

TimeSeriesList

Examples

Search for a time series:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.time_series.search(name="some name")

Create time series

TimeSeriesAPI.create(time_series: Union[cognite.client.data_classes.time_series.TimeSeries, List[cognite.client.data_classes.time_series.TimeSeries]]) → Union[cognite.client.data_classes.time_series.TimeSeries, cognite.client.data_classes.time_series.TimeSeriesList]

Create one or more time series.

Parameters:time_series (Union[TimeSeries, List[TimeSeries]]) – TimeSeries or list of TimeSeries to create.
Returns:The created time series.
Return type:Union[TimeSeries, TimeSeriesList]

Examples

Create a new time series:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import TimeSeries
>>> c = CogniteClient()
>>> ts = c.time_series.create(TimeSeries(name="my ts"))

Delete time series

TimeSeriesAPI.delete(id: Union[int, List[int]] = None, external_id: Union[str, List[str]] = None) → None

Delete one or more time series.

Parameters:
  • id (Union[int, List[int]) – Id or list of ids
  • external_id (Union[str, List[str]]) – External ID or list of external ids
Returns:

None

Examples

Delete time series by id or external id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.time_series.delete(id=[1,2,3], external_id="3")

Update time series

TimeSeriesAPI.update(item: Union[cognite.client.data_classes.time_series.TimeSeries, cognite.client.data_classes.time_series.TimeSeriesUpdate, List[Union[cognite.client.data_classes.time_series.TimeSeries, cognite.client.data_classes.time_series.TimeSeriesUpdate]]]) → Union[cognite.client.data_classes.time_series.TimeSeries, cognite.client.data_classes.time_series.TimeSeriesList]

Update one or more time series.

Parameters:item (Union[TimeSeries, TimeSeriesUpdate, List[Union[TimeSeries, TimeSeriesUpdate]]]) – Time series to update
Returns:Updated time series.
Return type:Union[TimeSeries, TimeSeriesList]

Examples

Update a time series that you have fetched. This will perform a full update of the time series:

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

Perform a partial update on a time series, updating the description and adding a new field to metadata:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import TimeSeriesUpdate
>>> c = CogniteClient()
>>> my_update = TimeSeriesUpdate(id=1).description.set("New description").metadata.add({"key": "value"})
>>> res = c.time_series.update(my_update)

Data classes

class cognite.client.data_classes.time_series.TimeSeries(id: int = None, external_id: str = None, name: str = None, is_string: bool = None, metadata: Dict[str, Any] = None, unit: str = None, asset_id: int = None, is_step: bool = None, description: str = None, security_categories: List[int] = None, created_time: int = None, last_updated_time: int = None, legacy_name: str = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

No description.

Parameters:
  • id (int) – The generated ID for the time series.
  • external_id (str) – The externally supplied ID for the time series.
  • name (str) – The name of the time series.
  • is_string (bool) – Whether the time series is string valued or not.
  • metadata (Dict[str, Any]) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
  • unit (str) – The physical unit of the time series.
  • asset_id (int) – The asset that this time series belongs to.
  • is_step (bool) – Whether the time series is a step series or not.
  • description (str) – Description of the time series.
  • security_categories (List[int]) – The required security categories to access this time series.
  • created_time (int) – Time when this time series was created in CDF in milliseconds since Jan 1, 1970.
  • last_updated_time (int) – The latest time when this time series was updated in CDF in milliseconds since Jan 1, 1970.
  • legacy_name (str) – Set a value for legacyName to allow applications using API v0.3, v04, v05, and v0.6 to access this time series. The legacy name is the human-readable name for the time series and is mapped to the name field used in API versions 0.3-0.6. The legacyName field value must be unique, and setting this value to an already existing value will return an error. We recommend that you set this field to the same value as externalId.
  • cognite_client (CogniteClient) – The client to associate with this object.
count() → int

Returns the number of datapoints in this time series.

This result may not be completely accurate, as it is based on aggregates which may be occasionally out of date.

Returns:The number of datapoints in this time series.
Return type:int
first() → Optional[Datapoint]

Returns the first datapoint in this time series.

Returns:A datapoint object containing the value and timestamp of the first datapoint.
Return type:Datapoint
latest() → Optional[Datapoint]

Returns the latest datapoint in this time series

Returns:A datapoint object containing the value and timestamp of the latest datapoint.
Return type:Datapoint
class cognite.client.data_classes.time_series.TimeSeriesFilter(name: str = None, unit: str = None, is_string: bool = None, is_step: bool = None, metadata: Dict[str, Any] = None, asset_ids: List[int] = None, external_id_prefix: str = None, created_time: Dict[str, Any] = None, last_updated_time: Dict[str, Any] = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteFilter

Filtering parameters

Parameters:
  • name (str) – Filter on name.
  • unit (str) – Filter on unit.
  • is_string (bool) – Filter on isString.
  • is_step (bool) – Filter on isStep.
  • metadata (Dict[str, Any]) – Filter out timeseries that do not match these metadata fields and values (case-sensitive). The format is {“key1”:”value1”,”key2”:”value2”}.
  • asset_ids (List[int]) – Filter out time series that are not linked to any of these assets.
  • external_id_prefix (str) – Prefix filter on externalId. (case-sensitive)
  • created_time (Dict[str, Any]) – Filter out time series with createdTime outside this range.
  • last_updated_time (Dict[str, Any]) – Filter out time series with lastUpdatedTime outside this range.
  • cognite_client (CogniteClient) – The client to associate with this object.
class cognite.client.data_classes.time_series.TimeSeriesList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.client.data_classes.time_series.TimeSeriesUpdate(id: int = None, external_id: str = None)

Bases: cognite.client.data_classes._base.CogniteUpdate

Changes will be applied to time series.

Parameters:
  • id (int) – A JavaScript-friendly internal ID for the object.
  • external_id (str) – The external ID provided by the client. Must be unique within the project.

Data points

Retrieve datapoints

DatapointsAPI.retrieve(start: Union[int, str, datetime.datetime], end: Union[int, str, datetime.datetime], id: Union[int, List[int], Dict[str, Union[int, List[str]]], List[Dict[str, Union[int, List[str]]]]] = None, external_id: Union[str, List[str], Dict[str, Union[int, List[str]]], List[Dict[str, Union[int, List[str]]]]] = None, aggregates: List[str] = None, granularity: str = None, include_outside_points: bool = None, limit: int = None) → Union[cognite.client.data_classes.datapoints.Datapoints, cognite.client.data_classes.datapoints.DatapointsList]

Get datapoints for one or more time series.

Note that you cannot specify the same ids/external_ids multiple times.

Parameters:
  • start (Union[int, str, datetime]) – Inclusive start.
  • end (Union[int, str, datetime]) – Exclusive end.
  • (Union[int, List[int], Dict[str, Any], List[Dict[str, Any]]] (id) – Id or list of ids. Can also be object specifying aggregates. See example below.
  • external_id (Union[str, List[str], Dict[str, Any], List[Dict[str, Any]]]) – External id or list of external ids. Can also be object specifying aggregates. See example below.
  • aggregates (List[str]) – List of aggregate functions to apply.
  • granularity (str) – The granularity to fetch aggregates at. e.g. ‘1s’, ‘2h’, ‘10d’.
  • include_outside_points (bool) – Whether or not to include outside points.
  • limit (int) – Maximum number of datapoints to return for each time series.
Returns:

A Datapoints object containing the requested data, or a list of such objects.

Return type:

Union[Datapoints, DatapointsList]

Examples

You can get specify the ids of the datapoints you wish to retrieve in a number of ways. In this example we are using the time-ago format to get raw data for the time series with id 1:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> dps = c.datapoints.retrieve(id=1, start="2w-ago", end="now")

We can also get aggregated values, such as average. Here we are getting daily averages for all of 2018 for two different time series. Note that we are fetching them using their external ids:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> dps = c.datapoints.retrieve(external_id=["abc", "def"],
...                         start=datetime(2018,1,1),
...                         end=datetime(2019,1,1),
...                         aggregates=["average"],
...                         granularity="1d")

If you want different aggregates for different time series specify your ids like this:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> dps = c.datapoints.retrieve(id=[{"id": 1, "aggregates": ["average"]},
...                             {"id": 1, "aggregates": ["min"]}],
...                         external_id={"externalId": "1", "aggregates": ["max"]},
...                         start="1d-ago", end="now", granularity="1h")

Retrieve pandas dataframe

DatapointsAPI.retrieve_dataframe(start: Union[int, str, datetime.datetime], end: Union[int, str, datetime.datetime], aggregates: List[str], granularity: str, id: Union[int, List[int], Dict[str, Union[int, List[str]]], List[Dict[str, Union[int, List[str]]]]] = None, external_id: Union[str, List[str], Dict[str, Union[int, List[str]]], List[Dict[str, Union[int, List[str]]]]] = None, limit: int = None)

Get a pandas dataframe describing the requested data.

Note that you cannot specify the same ids/external_ids multiple times.

Parameters:
  • start (Union[int, str, datetime]) – Inclusive start.
  • end (Union[int, str, datetime]) – Exclusive end.
  • aggregates (List[str]) – List of aggregate functions to apply.
  • granularity (str) – The granularity to fetch aggregates at. e.g. ‘1s’, ‘2h’, ‘10d’.
  • (Union[int, List[int], Dict[str, Any], List[Dict[str, Any]]] (id) – Id or list of ids. Can also be object specifying aggregates. See example below.
  • external_id (Union[str, List[str], Dict[str, Any], List[Dict[str, Any]]]) – External id or list of external ids. Can also be object specifying aggregates. See example below.
  • limit (int) – Maximum number of datapoints to return for each time series.
Returns:

The requested dataframe

Return type:

pandas.DataFrame

Examples

Get a pandas dataframe:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> df = c.datapoints.retrieve_dataframe(id=[1,2,3], start="2w-ago", end="now",
...         aggregates=["average"], granularity="1h")

Perform data points queries

DatapointsAPI.query(query: Union[cognite.client.data_classes.datapoints.DatapointsQuery, List[cognite.client.data_classes.datapoints.DatapointsQuery]]) → Union[cognite.client.data_classes.datapoints.DatapointsList, List[cognite.client.data_classes.datapoints.DatapointsList]]

Get datapoints for one or more time series

This method is different from get() in that you can specify different start times, end times, and granularities for each requested time series.

Parameters:query (Union[DatapointsQuery, List[DatapointsQuery]) – List of datapoint queries.
Returns:The requested DatapointsList(s).
Return type:Union[DatapointsList, List[DatapointsList]]

Examples

This method is useful if you want to get multiple time series, but you want to specify different starts, ends, or granularities for each. e.g.:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import DatapointsQuery
>>> c = CogniteClient()
>>> queries = [DatapointsQuery(id=1, start="2d-ago", end="now"),
...             DatapointsQuery(external_id="abc",
...                             start="10d-ago",
...                             end="now",
...                             aggregates=["average"],
...                             granularity="1m")]
>>> res = c.datapoints.query(queries)

Retrieve latest datapoint

DatapointsAPI.retrieve_latest(id: Union[int, List[int]] = None, external_id: Union[str, List[str]] = None, before: Union[int, str, datetime.datetime] = None) → Union[cognite.client.data_classes.datapoints.Datapoints, cognite.client.data_classes.datapoints.DatapointsList]

Get the latest datapoint for one or more time series

Parameters:
  • (Union[int, List[int]] (id) – Id or list of ids.
  • external_id (Union[str, List[str]) – External id or list of external ids.
  • before – Union[int, str, datetime]: Get latest datapoint before this time.
Returns:

A Datapoints object containing the requested data, or a list of such objects.

Return type:

Union[Datapoints, DatapointsList]

Examples

Getting the latest datapoint in a time series. This method returns a Datapoints object, so the datapoint will be the first element:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.datapoints.retrieve_latest(id=1)[0]

You can also get the first datapoint before a specific time:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.datapoints.retrieve_latest(id=1, before="2d-ago")[0]

If you need the latest datapoint for multiple time series simply give a list of ids. Note that we are using external ids here, but either will work:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.datapoints.retrieve_latest(external_id=["abc", "def"])
>>> latest_abc = res[0][0]
>>> latest_def = res[1][0]

Insert data points

DatapointsAPI.insert(datapoints: Union[List[Dict[Union[int, float, datetime.datetime], Union[int, float, str]]], List[Tuple[Union[int, float, datetime.datetime], Union[int, float, str]]]], id: int = None, external_id: str = None) → None

Insert datapoints into a time series

Timestamps can be represented as milliseconds since epoch or datetime objects.

Parameters:
  • datapoints (Union[List[Dict, Tuple]]) – The datapoints you wish to insert. Can either be a list of tuples or a list of dictionaries. See examples below.
  • id (int) – Id of time series to insert datapoints into.
  • external_id (str) – External id of time series to insert datapoint into.
Returns:

None

Examples

Your datapoints can be a list of tuples where the first element is the timestamp and the second element is the value:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> # with datetime objects
>>> datapoints = [(datetime(2018,1,1), 1000), (datetime(2018,1,2), 2000)]
>>> res1 = c.datapoints.insert(datapoints, id=1)
>>> # with ms since epoch
>>> datapoints = [(150000000000, 1000), (160000000000, 2000)]
>>> res2 = c.datapoints.insert(datapoints, id=2)

Or they can be a list of dictionaries:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> # with datetime objects
>>> datapoints = [{"timestamp": datetime(2018,1,1), "value": 1000},
...    {"timestamp": datetime(2018,1,2), "value": 2000}]
>>> res1 = c.datapoints.insert(datapoints, external_id="abc")
>>> # with ms since epoch
>>> datapoints = [{"timestamp": 150000000000, "value": 1000},
...    {"timestamp": 160000000000, "value": 2000}]
>>> res2 = c.datapoints.insert(datapoints, external_id="def")

Insert data points into multiple time series

DatapointsAPI.insert_multiple(datapoints: List[Dict[str, Union[str, int, List[T]]]]) → None

Insert datapoints into multiple time series

Parameters:datapoints (List[Dict]) – The datapoints you wish to insert along with the ids of the time series. See examples below.
Returns:None

Examples

Your datapoints can be a list of tuples where the first element is the timestamp and the second element is the value:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()

>>> datapoints = []
>>> # with datetime objects and id
>>> datapoints.append({"id": 1, "datapoints": [(datetime(2018,1,1), 1000), (datetime(2018,1,2), 2000)]})
>>> # with ms since epoch and externalId
>>> datapoints.append({"externalId": 1, "datapoints": [(150000000000, 1000), (160000000000, 2000)]})

>>> res = c.datapoints.insert_multiple(datapoints)

Or they can be a list of dictionaries:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()

>>> datapoints = []
>>> # with datetime objects and external id
>>> datapoints.append({"externalId": "1", "datapoints": [{"timestamp": datetime(2018,1,1), "value": 1000},
...                     {"timestamp": datetime(2018,1,2), "value": 2000}]})
>>> # with ms since epoch and id
>>> datapoints.append({"id": 1, "datapoints": [{"timestamp": 150000000000, "value": 1000},
...                     {"timestamp": 160000000000, "value": 2000}]})

>>> res = c.datapoints.insert_multiple(datapoints)

Insert pandas dataframe

DatapointsAPI.insert_dataframe(dataframe)

Insert a dataframe.

The index of the dataframe must contain the timestamps. The names of the remaining columns specify the ids of the time series to which column contents will be written.

Said time series must already exist.

Parameters:dataframe (pandas.DataFrame) – Pandas DataFrame Object containing the time series.
Returns:None

Examples

Post a dataframe with white noise:

>>> import numpy as np
>>> import pandas as pd
>>> from cognite.client import CogniteClient
>>> from datetime import datetime, timedelta
>>>
>>> c = CogniteClient()
>>> ts_id = 123
>>> start = datetime(2018, 1, 1)
>>> # The scaling by 1000 is important: timestamp() returns seconds
>>> x = pd.DatetimeIndex([start + timedelta(days=d) for d in range(100)])
>>> y = np.random.normal(0, 1, 100)
>>> df = pd.DataFrame({ts_id: y}, index=x)
>>> res = c.datapoints.insert_dataframe(df)

Delete a range of data points

DatapointsAPI.delete_range(start: Union[int, str, datetime.datetime], end: Union[int, str, datetime.datetime], id: int = None, external_id: str = None) → None

Delete a range of datapoints from a time series.

Parameters:
  • start (Union[int, str, datetime]) – Inclusive start of delete range
  • end (Union[int, str, datetime]) – Exclusvie end of delete range
  • id (int) – Id of time series to delete data from
  • external_id (str) – External id of time series to delete data from
Returns:

None

Examples

Deleting the last week of data from a time series:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.datapoints.delete_range(start="1w-ago", end="now", id=1)

Delete ranges of data points

DatapointsAPI.delete_ranges(ranges: List[Dict[str, Any]]) → None

Delete a range of datapoints from multiple time series.

Parameters:ranges (List[Dict[str, Any]]) – The ids an ranges to delete. See examples below.
Returns:None

Examples

Each element in the list ranges must be specify either id or externalId, and a range:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> ranges = [{"id": 1, "start": "2d-ago", "end": "now"},
...             {"externalId": "abc", "start": "2d-ago", "end": "now"}]
>>> res = c.datapoints.delete_ranges(ranges)

Data classes

class cognite.client.data_classes.datapoints.Datapoint(timestamp: Union[int, float] = None, value: Union[str, int, float] = None, average: float = None, max: float = None, min: float = None, count: int = None, sum: float = None, interpolation: float = None, step_interpolation: float = None, continuous_variance: float = None, discrete_variance: float = None, total_variation: float = None)

Bases: cognite.client.data_classes._base.CogniteResource

An object representing a datapoint.

Parameters:
  • timestamp (Union[int, float]) – The data timestamp in milliseconds since the epoch (Jan 1, 1970).
  • value (Union[str, int, float]) – The data value. Can be String or numeric depending on the metric
  • average (float) – The integral average value in the aggregate period
  • max (float) – The maximum value in the aggregate period
  • min (float) – The minimum value in the aggregate period
  • count (int) – The number of datapoints in the aggregate period
  • sum (float) – The sum of the datapoints in the aggregate period
  • interpolation (float) – The interpolated value of the series in the beginning of the aggregate
  • step_interpolation (float) – The last value before or at the beginning of the aggregate.
  • continuous_variance (float) – The variance of the interpolated underlying function.
  • discrete_variance (float) – The variance of the datapoint values.
  • total_variation (float) – The total variation of the interpolated underlying function.
to_pandas() → pandas.DataFrame

Convert the datapoint into a pandas DataFrame.

Returns:The dataframe.
Return type:pandas.DataFrame
class cognite.client.data_classes.datapoints.Datapoints(id: int = None, external_id: str = None, timestamp: List[Union[int, float]] = None, value: List[Union[int, str, float]] = None, average: List[float] = None, max: List[float] = None, min: List[float] = None, count: List[int] = None, sum: List[float] = None, interpolation: List[float] = None, step_interpolation: List[float] = None, continuous_variance: List[float] = None, discrete_variance: List[float] = None, total_variation: List[float] = None)

Bases: object

An object representing a list of datapoints.

Parameters:
  • id (int) – Id of the timeseries the datapoints belong to
  • external_id (str) – External id of the timeseries the datapoints belong to (Only if id is not set)
  • timestamp (List[Union[int, float]]) – The data timestamps in milliseconds since the epoch (Jan 1, 1970).
  • value (List[Union[int, str, float]]) – The data values. Can be String or numeric depending on the metric
  • average (List[float]) – The integral average values in the aggregate period
  • max (List[float]) – The maximum values in the aggregate period
  • min (List[float]) – The minimum values in the aggregate period
  • count (List[int]) – The number of datapoints in the aggregate periods
  • sum (List[float]) – The sum of the datapoints in the aggregate periods
  • interpolation (List[float]) – The interpolated values of the series in the beginning of the aggregates
  • step_interpolation (List[float]) – The last values before or at the beginning of the aggregates.
  • continuous_variance (List[float]) – The variance of the interpolated underlying function.
  • discrete_variance (List[float]) – The variance of the datapoint values.
  • total_variation (List[float]) – The total variation of the interpolated underlying function.
dump(camel_case: bool = False) → Dict[str, Any]

Dump the datapoints into a json serializable Python data type.

Parameters:camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:A list of dicts representing the instance.
Return type:List[Dict[str, Any]]
plot(*args, **kwargs) → None

Plot the datapoints.

to_pandas(column_names='externalId') → pandas.DataFrame

Convert the datapoints into a pandas DataFrame.

Parameters:column_names (str) – Which field to use as column header. Defaults to “externalId”, can also be “id”.
Returns:The dataframe.
Return type:pandas.DataFrame
class cognite.client.data_classes.datapoints.DatapointsList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

plot(*args, **kwargs) → None

Plot the list of datapoints.

to_pandas(column_names='externalId') → pandas.DataFrame

Convert the datapoints list into a pandas DataFrame.

Parameters:column_names (str) – Which field to use as column header. Defaults to “externalId”, can also be “id”.
Returns:The datapoints list as a pandas DataFrame.
Return type:pandas.DataFrame
class cognite.client.data_classes.datapoints.DatapointsQuery(start: Union[str, int, datetime.datetime], end: Union[str, int, datetime.datetime], id: Union[int, List[int], Dict[str, Union[int, List[str]]], List[Dict[str, Union[int, List[str]]]]] = None, external_id: Union[str, List[str], Dict[str, Union[int, List[str]]], List[Dict[str, Union[int, List[str]]]]] = None, limit: int = None, aggregates: List[str] = None, granularity: str = None, include_outside_points: bool = None)

Bases: cognite.client.data_classes._base.CogniteResource

Parameters describing a query for datapoints.

Parameters:
  • start (Union[str, int, datetime]) – Get datapoints after this time. Format is N[timeunit]-ago where timeunit is w,d,h,m,s. Example: ‘2d-ago’ will get everything that is up to 2 days old. Can also send time in ms since epoch.
  • end (Union[str, int, datetime]) – Get datapoints up to this time. The format is the same as for start.
  • (Union[int, List[int], Dict[str, Any], List[Dict[str, Any]]] (id) –
    Id or list of ids. Can also be object
    specifying aggregates. See example below.
    external_id (Union[str, List[str], Dict[str, Any], List[Dict[str, Any]]]): External id or list of external
    ids. Can also be object specifying aggregates. See example below.
  • limit (int) – Return up to this number of datapoints.
  • aggregates (List[str]) – The aggregates to be returned. Use default if null. An empty string must be sent to get raw data if the default is a set of aggregates.
  • granularity (str) – The granularity size and granularity of the aggregates.
  • include_outside_points (bool) – Whether to include the last datapoint before the requested time period,and the first one after the requested period. This can be useful for interpolating data. Not available for aggregates.

Raw

Databases

List databases

RawDatabasesAPI.list(limit: int = 25) → cognite.client.data_classes.raw.DatabaseList

List databases

Parameters:limit (int, optional) – Maximum number of databases to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:List of requested databases.
Return type:DatabaseList

Examples

List the first 5 databases:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> db_list = c.raw.databases.list(limit=5)

Iterate over databases:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for db in c.raw.databases:
...     db # do something with the db

Iterate over chunks of databases to reduce memory load:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for db_list in c.raw.databases(chunk_size=2500):
...     db_list # do something with the dbs

Create new databases

RawDatabasesAPI.create(name: Union[str, List[str]]) → Union[cognite.client.data_classes.raw.Database, cognite.client.data_classes.raw.DatabaseList]

Create one or more databases.

Parameters:name (Union[str, List[str]]) – A db name or list of db names to create.
Returns:Database or list of databases that has been created.
Return type:Union[Database, DatabaseList]

Examples

Create a new database:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.raw.databases.create("db1")

Delete databases

RawDatabasesAPI.delete(name: Union[str, List[str]]) → None

Delete one or more databases.

Parameters:name (Union[str, List[str]]) – A db name or list of db names to delete.
Returns:None

Examples

Delete a list of databases:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.raw.databases.delete(["db1", "db2"])

Tables

List tables in a database

RawTablesAPI.list(db_name: str, limit: int = 25) → cognite.client.data_classes.raw.TableList

List tables

Parameters:
  • db_name (str) – The database to list tables from.
  • limit (int, optional) – Maximum number of tables to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:

List of requested tables.

Return type:

TableList

Examples

List the first 5 tables:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> table_list = c.raw.tables.list("db1", limit=5)

Iterate over tables:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for table in c.raw.tables(db_name="db1"):
...     table # do something with the table

Iterate over chunks of tables to reduce memory load:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for table_list in c.raw.tables(db_name="db1", chunk_size=2500):
...     table_list # do something with the tables

Create new tables in a database

RawTablesAPI.create(db_name: str, name: Union[str, List[str]]) → Union[cognite.client.data_classes.raw.Table, cognite.client.data_classes.raw.TableList]

Create one or more tables.

Parameters:
  • db_name (str) – Database to create the tables in.
  • name (Union[str, List[str]]) – A table name or list of table names to create.
Returns:

Table or list of tables that has been created.

Return type:

Union[Table, TableList]

Examples

Create a new table in a database:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.raw.tables.create("db1", "table1")

Delete tables from a database

RawTablesAPI.delete(db_name: str, name: Union[str, List[str]]) → None

Delete one or more tables.

Parameters:
  • db_name (str) – Database to delete tables from.
  • name (Union[str, List[str]]) – A table name or list of table names to delete.
Returns:

None

Examples

Delete a list of tables:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.raw.tables.delete("db1", ["table1", "table2"])

Rows

Get a row from a table

RawRowsAPI.retrieve(db_name: str, table_name: str, key: str) → Optional[cognite.client.data_classes.raw.Row]

Retrieve a single row by key.

Parameters:
  • db_name (str) – Name of the database.
  • table_name (str) – Name of the table.
  • key (str) – The key of the row to retrieve.
Returns:

The requested row.

Return type:

Optional[Row]

Examples

Retrieve a row with key ‘k1’ from tablew ‘t1’ in database ‘db1’:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> row = c.raw.rows.retrieve("db1", "t1", "k1")

List rows in a table

RawRowsAPI.list(db_name: str, table_name: str, min_last_updated_time: int = None, max_last_updated_time: int = None, limit: int = 25) → cognite.client.data_classes.raw.RowList

List rows in a table.

Parameters:
  • db_name (str) – Name of the database.
  • table_name (str) – Name of the table.
  • min_last_updated_time (int) – Rows must have been last updated after this time. ms since epoch.
  • max_last_updated_time (int) – Rows must have been last updated before this time. ms since epoch.
  • limit (int) – The number of rows to retrieve. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:

The requested rows.

Return type:

RowList

Examples

List rows:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> row_list = c.raw.rows.list("db1", "t1", limit=5)

Iterate over rows:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for row in c.raw.rows(db_name="db1", table_name="t1"):
...     row # do something with the row

Iterate over chunks of rows to reduce memory load:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for row_list in c.raw.rows(db_name="db1", table_name="t1", chunk_size=2500):
...     row_list # do something with the rows

Insert rows into a table

RawRowsAPI.insert(db_name: str, table_name: str, row: Union[List[cognite.client.data_classes.raw.Row], cognite.client.data_classes.raw.Row, Dict[KT, VT]], ensure_parent: bool = False) → None

Insert one or more rows into a table.

Parameters:
  • db_name (str) – Name of the database.
  • table_name (str) – Name of the table.
  • row (Union[List[Row], Row, Dict]) – The row(s) to insert
  • ensure_parent (bool) – Create database/table if they don’t already exist.
Returns:

None

Examples

Insert new rows into a table:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> rows = {"r1": {"col1": "val1", "col2": "val1"}, "r2": {"col1": "val2", "col2": "val2"}}
>>> res = c.raw.rows.insert("db1", "table1", rows)

Delete rows from a table

RawRowsAPI.delete(db_name: str, table_name: str, key: Union[str, List[str]]) → None

Delete rows from a table.

Parameters:
  • db_name (str) – Name of the database.
  • table_name (str) – Name of the table.
  • key (Union[str, List[str]]) – The key(s) of the row(s) to delete.
Returns:

None

Examples

Delete rows from table:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> keys_to_delete = ["k1", "k2", "k3"]
>>> res = c.raw.rows.delete("db1", "table1", keys_to_delete)

Data classes

class cognite.client.data_classes.raw.Database(name: str = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

A NoSQL database to store customer data.

Parameters:
  • name (str) – Unique name of a database.
  • cognite_client (CogniteClient) – The client to associate with this object.
tables(limit: int = None) → cognite.client.data_classes.raw.TableList

Get the tables in this database.

Parameters:limit (int) – The number of tables to return.
Returns:List of tables in this database.
Return type:TableList
to_pandas()

Convert the instance into a pandas DataFrame.

Returns:The pandas DataFrame representing this instance.
Return type:pandas.DataFrame
class cognite.client.data_classes.raw.DatabaseList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.client.data_classes.raw.Row(key: str = None, columns: Dict[str, Any] = None, last_updated_time: int = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

No description.

Parameters:
  • key (str) – Unique row key
  • columns (Dict[str, Any]) – Row data stored as a JSON object.
  • 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.
to_pandas()

Convert the instance into a pandas DataFrame.

Returns:The pandas DataFrame representing this instance.
Return type:pandas.DataFrame
class cognite.client.data_classes.raw.RowList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

to_pandas()

Convert the instance into a pandas DataFrame.

Returns:The pandas DataFrame representing this instance.
Return type:pandas.DataFrame
class cognite.client.data_classes.raw.Table(name: str = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

A NoSQL database table to store customer data

Parameters:
  • name (str) – Unique name of the table
  • cognite_client (CogniteClient) – The client to associate with this object.
rows(key: str = None, limit: int = None) → Union[cognite.client.data_classes.raw.Row, cognite.client.data_classes.raw.RowList]

Get the rows in this table.

Parameters:
  • key (str) – Specify a key to return only that row.
  • limit (int) – The number of rows to return.
Returns:

List of tables in this database.

Return type:

Union[Row, RowList]

to_pandas()

Convert the instance into a pandas DataFrame.

Returns:The pandas DataFrame representing this instance.
Return type:pandas.DataFrame
class cognite.client.data_classes.raw.TableList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

3D

Models

Retrieve a model by ID

ThreeDModelsAPI.retrieve(id: int) → cognite.client.data_classes.three_d.ThreeDModel

Retrieve a 3d model by id

Parameters:id (int) – Get the model with this id.
Returns:The requested 3d model.
Return type:ThreeDModel

Example

Get 3d model by id:

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

List models

ThreeDModelsAPI.list(published: bool = False, limit: int = 25) → cognite.client.data_classes.three_d.ThreeDModelList

List 3d models.

Parameters:
  • published (bool) – Filter based on whether or not the model has published revisions.
  • limit (int) – Maximum number of models to retrieve. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:

The list of 3d models.

Return type:

ThreeDModelList

Examples

List 3d models:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> three_d_model_list = c.three_d.models.list()

Iterate over 3d models:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for three_d_model in c.three_d.models:
...     three_d_model # do something with the 3d model

Iterate over chunks of 3d models to reduce memory load:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for three_d_model in c.three_d.models(chunk_size=50):
...     three_d_model # do something with the 3d model

Create models

ThreeDModelsAPI.create(name: Union[str, List[str]]) → Union[cognite.client.data_classes.three_d.ThreeDModel, cognite.client.data_classes.three_d.ThreeDModelList]

Create new 3d models.

Parameters:name (Union[str, List[str]) – The name of the 3d model(s) to create.
Returns:The created 3d model(s).
Return type:Union[ThreeDModel, ThreeDModelList]

Example

Create new 3d models:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.models.create(name="My Model")

Update models

ThreeDModelsAPI.update(item: Union[cognite.client.data_classes.three_d.ThreeDModel, cognite.client.data_classes.three_d.ThreeDModelUpdate, List[Union[cognite.client.data_classes.three_d.ThreeDModel, cognite.client.data_classes.three_d.ThreeDModelList]]]) → Union[cognite.client.data_classes.three_d.ThreeDModel, cognite.client.data_classes.three_d.ThreeDModelList]

Update 3d models.

Parameters:item (Union[ThreeDModel, ThreeDModelUpdate, List[Union[ThreeDModel, ThreeDModelUpdate]]]) – ThreeDModel(s) to update
Returns:Updated ThreeDModel(s)
Return type:Union[ThreeDModel, ThreeDModelList]

Examples

Update 3d model that you have fetched. This will perform a full update of the model:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> three_d_model = c.three_d.models.retrieve(id=1)
>>> three_d_model.name = "New Name"
>>> res = c.three_d.models.update(three_d_model)

Perform a partial update on a 3d model:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import ThreeDModelUpdate
>>> c = CogniteClient()
>>> my_update = ThreeDModelUpdate(id=1).name.set("New Name")
>>> res = c.three_d.models.update(my_update)

Delete models

ThreeDModelsAPI.delete(id: Union[int, List[int]]) → None

Delete 3d models.

Parameters:id (Union[int, List[int]]) – ID or list of IDs to delete.
Returns:None

Example

Delete 3d model by id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.models.delete(id=1)

Revisions

Retrieve a revision by ID

ThreeDRevisionsAPI.retrieve(model_id: int, id: int) → cognite.client.data_classes.three_d.ThreeDModelRevision

Retrieve a 3d model revision by id

Parameters:
  • model_id (int) – Get the revision under the model with this id.
  • id (int) – Get the model revision with this id.
Returns:

The requested 3d model revision.

Return type:

ThreeDModelRevision

Example

Retrieve 3d model revision by model id and revision id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.retrieve(model_id=1, id=1)

Create a revision

ThreeDRevisionsAPI.create(model_id: int, revision: Union[cognite.client.data_classes.three_d.ThreeDModelRevision, List[cognite.client.data_classes.three_d.ThreeDModelRevision]]) → Union[cognite.client.data_classes.three_d.ThreeDModelRevision, cognite.client.data_classes.three_d.ThreeDModelRevisionList]

Create a revisions for a specified 3d model.

Parameters:
Returns:

The created revision(s)

Return type:

Union[ThreeDModelRevision, ThreeDModelRevisionList]

Example

Create 3d model revision:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import ThreeDModelRevision
>>> c = CogniteClient()
>>> my_revision = ThreeDModelRevision(file_id=1)
>>> res = c.three_d.revisions.create(model_id=1, revision=my_revision)

List revisions

ThreeDRevisionsAPI.list(model_id: int, published: bool = False, limit: int = 25) → cognite.client.data_classes.three_d.ThreeDModelRevisionList

List 3d model revisions.

Parameters:
  • model_id (int) – List revisions under the model with this id.
  • published (bool) – Filter based on whether or not the revision is published.
  • limit (int) – Maximum number of models to retrieve. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:

The list of 3d model revisions.

Return type:

ThreeDModelRevisionList

Example

List 3d model revisions:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.list(model_id=1, published=True, limit=100)

Update revisions

ThreeDRevisionsAPI.update(model_id: int, item: Union[cognite.client.data_classes.three_d.ThreeDModelRevision, cognite.client.data_classes.three_d.ThreeDModelRevisionUpdate, List[Union[cognite.client.data_classes.three_d.ThreeDModelRevision, cognite.client.data_classes.three_d.ThreeDModelRevisionList]]]) → Union[cognite.client.data_classes.three_d.ThreeDModelRevision, cognite.client.data_classes.three_d.ThreeDModelRevisionList]

Update 3d model revisions.

Parameters:
Returns:

Updated ThreeDModelRevision(s)

Return type:

Union[ThreeDModelRevision, ThreeDModelRevisionList]

Examples

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

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> revision = c.three_d.revisions.retrieve(model_id=1, id=1)
>>> revision.status = "New Status"
>>> res = c.three_d.revisions.update(model_id=1, item=revision)

Perform a partial update on a revision, updating the published property and adding a new field to metadata:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import ThreeDModelRevisionUpdate
>>> c = CogniteClient()
>>> my_update = ThreeDModelRevisionUpdate(id=1).published.set(False).metadata.add({"key": "value"})
>>> res = c.three_d.revisions.update(model_id=1, item=my_update)

Delete revisions

ThreeDRevisionsAPI.delete(model_id: int, id: Union[int, List[int]]) → None

Delete 3d model revisions.

Parameters:
  • model_id (int) – Delete the revision under the model with this id.
  • id (Union[int, List[int]]) – ID or list of IDs to delete.
Returns:

None

Example

Delete 3d model revision by id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.delete(model_id=1, id=1)

Update a revision thumbnail

ThreeDRevisionsAPI.update_thumbnail(model_id: int, revision_id: int, file_id: int) → None

Update a revision thumbnail.

Parameters:
  • model_id (int) – Id of the model.
  • revision_id (int) – Id of the revision.
  • file_id (int) – Id of the thumbnail file in the Files API.
Returns:

None

Example

Update revision thumbnail:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.update_thumbnail(model_id=1, revision_id=1, file_id=1)

List nodes

ThreeDRevisionsAPI.list_nodes(model_id: int, revision_id: int, node_id: int = None, depth: int = None, limit: int = 25) → cognite.client.data_classes.three_d.ThreeDNodeList

Retrieves a list of nodes from the hierarchy in the 3D Model.

You can also request a specific subtree with the ‘nodeId’ query parameter and limit the depth of the resulting subtree with the ‘depth’ query parameter.

Parameters:
  • model_id (int) – Id of the model.
  • revision_id (int) – Id of the revision.
  • node_id (int) – ID of the root node of the subtree you request (default is the root node).
  • depth (int) – Get sub nodes up to this many levels below the specified node. Depth 0 is the root node.
  • limit (int) – Maximun number of nodes to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:

The list of 3d nodes.

Return type:

ThreeDNodeList

Example

List nodes from the hierarchy in the 3d model:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.list_nodes(model_id=1, revision_id=1, limit=10)

List ancestor nodes

ThreeDRevisionsAPI.list_ancestor_nodes(model_id: int, revision_id: int, node_id: int = None, limit: int = 25) → cognite.client.data_classes.three_d.ThreeDNodeList

Retrieves a list of ancestor nodes of a given node, including itself, in the hierarchy of the 3D model

You can also request a specific subtree with the ‘nodeId’ query parameter and limit the depth of the resulting subtree with the ‘depth’ query parameter.

Parameters:
  • model_id (int) – Id of the model.
  • revision_id (int) – Id of the revision.
  • node_id (int) – ID of the node to get the ancestors of.
  • limit (int) – Maximun number of nodes to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:

The list of 3d nodes.

Return type:

ThreeDNodeList

Example

Get a list of ancestor nodes of a given node:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.list_ancestor_nodes(model_id=1, revision_id=1, node_id=5, limit=10)

Files

Retrieve a 3D file

ThreeDFilesAPI.retrieve(id: int) → bytes

Retrieve the contents of a 3d file by id.

Parameters:id (int) – The id of the file to retrieve.
Returns:The contents of the file.
Return type:bytes

Example

Retrieve the contents of a 3d file by id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.files.retrieve(1)

Asset mappings

Create an asset mapping

ThreeDAssetMappingAPI.create(model_id: int, revision_id: int, asset_mapping: Union[cognite.client.data_classes.three_d.ThreeDAssetMapping, List[cognite.client.data_classes.three_d.ThreeDAssetMapping]]) → Union[cognite.client.data_classes.three_d.ThreeDAssetMapping, cognite.client.data_classes.three_d.ThreeDAssetMappingList]

Create 3d node asset mappings.

Parameters:
  • model_id (int) – Id of the model.
  • revision_id (int) – Id of the revision.
  • asset_mapping (Union[ThreeDAssetMapping, List[ThreeDAssetMapping]]) – The asset mapping(s) to create.
Returns:

The created asset mapping(s).

Return type:

Union[ThreeDAssetMapping, ThreeDAssetMappingList]

Example

Create new 3d node asset mapping:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import ThreeDAssetMapping
>>> my_mapping = ThreeDAssetMapping(node_id=1, asset_id=1)
>>> c = CogniteClient()
>>> res = c.three_d.asset_mappings.create(model_id=1, revision_id=1, asset_mapping=my_mapping)

List asset mappings

ThreeDAssetMappingAPI.list(model_id: int, revision_id: int, node_id: int = None, asset_id: int = None, limit: int = 25) → cognite.client.data_classes.three_d.ThreeDAssetMappingList

List 3D node asset mappings.

Parameters:
  • model_id (int) – Id of the model.
  • revision_id (int) – Id of the revision.
  • node_id (int) – List only asset mappings associated with this node.
  • asset_id (int) – List only asset mappings associated with this asset.
  • limit (int) – Maximum number of asset mappings to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns:

The list of asset mappings.

Return type:

ThreeDAssetMappingList

Example

List 3d node asset mappings:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.asset_mappings.list(model_id=1, revision_id=1)

Delete asset mappings

ThreeDAssetMappingAPI.delete(model_id: int, revision_id: int, asset_mapping: Union[cognite.client.data_classes.three_d.ThreeDAssetMapping, List[cognite.client.data_classes.three_d.ThreeDAssetMapping]]) → None

Delete 3d node asset mappings.

Parameters:
  • model_id (int) – Id of the model.
  • revision_id (int) – Id of the revision.
  • asset_mapping (Union[ThreeDAssetMapping, List[ThreeDAssetMapping]]) – The asset mapping(s) to delete.
Returns:

None

Example

Delete 3d node asset mapping:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> mapping_to_delete = c.three_d.asset_mappings.list(model_id=1, revision_id=1)[0]
>>> res = c.three_d.asset_mappings.delete(model_id=1, revision_id=1, asset_mapping=mapping_to_delete)

Data classes

class cognite.client.data_classes.three_d.ThreeDAssetMapping(node_id: int = None, asset_id: int = None, tree_index: int = None, subtree_size: int = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

No description.

Parameters:
  • node_id (int) – The ID of the node.
  • asset_id (int) – The ID of the associated asset (Cognite’s Assets API).
  • tree_index (int) – A number describing the position of this node in the 3D hierarchy, starting from 0. The tree is traversed in a depth-first order.
  • subtree_size (int) – The number of nodes in the subtree of this node (this number included the node itself).
  • cognite_client (CogniteClient) – The client to associate with this object.
class cognite.client.data_classes.three_d.ThreeDAssetMappingList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.client.data_classes.three_d.ThreeDModel(name: str = None, id: int = None, created_time: int = None, metadata: Dict[str, Any] = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

No description.

Parameters:
  • name (str) – The name of the model.
  • id (int) – The ID of the model.
  • created_time (int) – The creation time of the resource, in milliseconds since January 1, 1970 at 00:00 UTC.
  • metadata (Dict[str, Any]) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
  • cognite_client (CogniteClient) – The client to associate with this object.
class cognite.client.data_classes.three_d.ThreeDModelList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.client.data_classes.three_d.ThreeDModelRevision(id: int = None, file_id: int = None, published: bool = None, rotation: List[float] = None, camera: Dict[str, Any] = None, status: str = None, metadata: Dict[str, Any] = None, thumbnail_threed_file_id: int = None, thumbnail_url: str = None, asset_mapping_count: int = None, created_time: int = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

No description.

Parameters:
  • id (int) – The ID of the revision.
  • file_id (int) – The file id.
  • published (bool) – True if the revision is marked as published.
  • rotation (List[float]) – No description.
  • camera (Dict[str, Any]) – Initial camera position and target.
  • status (str) – The status of the revision.
  • metadata (Dict[str, Any]) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
  • thumbnail_threed_file_id (int) – The threed file ID of a thumbnail for the revision. Use /3d/files/{id} to retrieve the file.
  • thumbnail_url (str) – The URL of a thumbnail for the revision.
  • asset_mapping_count (int) – The number of asset mappings for this revision.
  • created_time (int) – The creation time of the resource, in milliseconds since January 1, 1970 at 00:00 UTC.
  • cognite_client (CogniteClient) – The client to associate with this object.
class cognite.client.data_classes.three_d.ThreeDModelRevisionList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.client.data_classes.three_d.ThreeDModelRevisionUpdate(id: int = None, external_id: str = None)

Bases: cognite.client.data_classes._base.CogniteUpdate

No description.

Parameters:id (int) – A JavaScript-friendly internal ID for the object.
class cognite.client.data_classes.three_d.ThreeDModelUpdate(id: int = None, external_id: str = None)

Bases: cognite.client.data_classes._base.CogniteUpdate

No description.

Parameters:id (int) – A JavaScript-friendly internal ID for the object.
class cognite.client.data_classes.three_d.ThreeDNode(id: int = None, tree_index: int = None, parent_id: int = None, depth: int = None, name: str = None, subtree_size: int = None, bounding_box: Dict[str, Any] = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

No description.

Parameters:
  • id (int) – The ID of the node.
  • tree_index (int) – The index of the node in the 3D model hierarchy, starting from 0. The tree is traversed in a depth-first order.
  • parent_id (int) – The parent of the node, null if it is the root node.
  • depth (int) – The depth of the node in the tree, starting from 0 at the root node.
  • name (str) – The name of the node.
  • subtree_size (int) – The number of descendants of the node, plus one (counting itself).
  • bounding_box (Dict[str, Any]) – The bounding box of the subtree with this sector as the root sector. Is null if there are no geometries in the subtree.
  • cognite_client (CogniteClient) – The client to associate with this object.
class cognite.client.data_classes.three_d.ThreeDNodeList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

Identity and access management

Service accounts

List service accounts

ServiceAccountsAPI.list() → cognite.client.data_classes.iam.ServiceAccountList

List service accounts.

Returns:List of service accounts.
Return type:ServiceAccountList

Example

List service accounts:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.iam.service_accounts.list()

Create service accounts

ServiceAccountsAPI.create(service_account: Union[cognite.client.data_classes.iam.ServiceAccount, List[cognite.client.data_classes.iam.ServiceAccount]]) → Union[cognite.client.data_classes.iam.ServiceAccount, cognite.client.data_classes.iam.ServiceAccountList]

Create one or more new service accounts.

Parameters:service_account (Union[ServiceAccount, List[ServiceAccount]]) – The service account(s) to create.
Returns:The created service account(s).
Return type:Union[ServiceAccount, ServiceAccountList]

Example

Create service account:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import ServiceAccount
>>> c = CogniteClient()
>>> my_account = ServiceAccount(name="my@service.com", groups=[1, 2, 3])
>>> res = c.iam.service_accounts.create(my_account)

Delete service accounts

ServiceAccountsAPI.delete(id: Union[int, List[int]]) → None

Delete one or more service accounts.

Parameters:id (Union[int, List[int]]) – ID or list of IDs to delete.
Returns:None

Example

Delete service account by id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.iam.service_accounts.delete(1)

API keys

List API keys

APIKeysAPI.list(include_deleted: bool = False, all: bool = False, service_account_id: bool = None) → cognite.client.data_classes.iam.APIKeyList

List api keys.

Parameters:
  • include_deleted (bool) – Whether or not to include deleted api keys. Defaults to False.
  • all (bool) – Whether or not to return all api keys for this project. Requires users:list acl. Defaults to False.
  • service_account_id (int) – Get api keys for this service account only. Only available to admin users.
Returns:

List of api keys.

Return type:

APIKeyList

Example

List api keys:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.iam.api_keys.list()

Create API keys

APIKeysAPI.create(service_account_id: Union[int, List[int]]) → Union[cognite.client.data_classes.iam.APIKey, cognite.client.data_classes.iam.APIKeyList]

Create a new api key for one or more service accounts.

Parameters:service_account_id (Union[int, List[int]]) – ID or list of IDs of service accounts to create an api key for.
Returns:API key or list of api keys.
Return type:Union[APIKey, APIKeyList]

Example

Create new api key for a given service account:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.iam.api_keys.create(1)

Delete API keys

APIKeysAPI.delete(id: Union[int, List[int]]) → None

Delete one or more api keys.

Parameters:id (Union[int, List[int]]) – ID or list of IDs of api keys to delete.
Returns:None

Example

Delete api key for a given service account:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.iam.api_keys.delete(1)

Groups

List groups

GroupsAPI.list(all: bool = False) → cognite.client.data_classes.iam.GroupList

List groups.

Parameters:all (bool) – Whether to get all groups, only available with the groups:list acl.
Returns:List of groups.
Return type:GroupList

Example

List groups:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.iam.groups.list()

Create groups

GroupsAPI.create(group: Union[cognite.client.data_classes.iam.Group, List[cognite.client.data_classes.iam.Group]]) → Union[cognite.client.data_classes.iam.Group, cognite.client.data_classes.iam.GroupList]

Create one or more groups.

Parameters:group (Union[Group, List[Group]]) – Group or list of groups to create.
Returns:The created group(s).
Return type:Union[Group, GroupList]

Example

Create group:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import Group
>>> c = CogniteClient()
>>> my_capabilities = [{"groupsAcl": {"actions": ["LIST"],"scope": {"all": { }}}}]
>>> my_group = Group(name="My Group", capabilities=my_capabilities)
>>> res = c.iam.groups.create(my_group)

Delete groups

GroupsAPI.delete(id: Union[int, List[int]]) → None

Delete one or more groups.

Parameters:id (Union[int, List[int]]) – ID or list of IDs of groups to delete.
Returns:None

Example

Delete group:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.iam.groups.delete(1)

List service accounts in a group

GroupsAPI.list_service_accounts(id: int) → cognite.client.data_classes.iam.ServiceAccountList

List service accounts in a group.

Parameters:id (int) – List service accounts which are a member of this group.
Returns:List of service accounts.
Return type:ServiceAccountList

Example

List service accounts in a group:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.iam.groups.list_service_accounts(1)

Add service accounts to a group

GroupsAPI.add_service_account(id: int, service_account_id: Union[int, List[int]]) → None

Add one or more service accounts to a group.

Parameters:
  • id (int) – Add service accounts to the group with this id.
  • service_account_id (Union[int, List[int]]) – Add these service accounts to the specified group.
Returns:

None

Example

Add service account to group:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.iam.groups.add_service_account(id=1, service_account_id=1)

Remove service accounts from a group

GroupsAPI.remove_service_account(id: int, service_account_id: Union[int, List[int]]) → None

Remove one or more service accounts from a group.

Parameters:
  • id (int) – Remove service accounts from the group with this id.
  • service_account_id – Remove these service accounts from the specified group.
Returns:

None

Example

Remove service account from group:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.iam.groups.remove_service_account(id=1, service_account_id=1)

Security categories

List security categories

SecurityCategoriesAPI.list(limit: int = 25) → cognite.client.data_classes.iam.SecurityCategoryList

List security categories.

Parameters:limit (int) – Max number of security categories to return. Defaults to 25.
Returns:List of security categories
Return type:SecurityCategoryList

Example

List security categories:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.iam.security_categories.list()

Create security categories

SecurityCategoriesAPI.create(security_category: Union[cognite.client.data_classes.iam.SecurityCategory, List[cognite.client.data_classes.iam.SecurityCategory]]) → Union[cognite.client.data_classes.iam.SecurityCategory, cognite.client.data_classes.iam.SecurityCategoryList]

Create one or more security categories.

Parameters:security_category (Union[SecurityCategory, List[SecurityCategory]]) – Security category or list of categories to create.
Returns:The created security category or categories.
Return type:Union[SecurityCategory, SecurityCategoryList]

Example

Create security category:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import SecurityCategory
>>> c = CogniteClient()
>>> my_category = SecurityCategory(name="My Category")
>>> res = c.iam.security_categories.create(my_category)

Delete security categories

SecurityCategoriesAPI.delete(id: Union[int, List[int]]) → None

Delete one or more security categories.

Parameters:id (Union[int, List[int]]) – ID or list of IDs of security categories to delete.
Returns:None

Example

Delete security category:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.iam.security_categories.delete(1)

Data classes

class cognite.client.data_classes.iam.APIKey(id: int = None, service_account_id: int = None, created_time: int = None, status: str = None, value: str = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

No description.

Parameters:
  • id (int) – The internal ID for the API key.
  • service_account_id (int) – The ID of the service account.
  • created_time (int) – The time of creation in Unix milliseconds.
  • status (str) – The status of the API key.
  • value (str) – The API key to be used against the API.
  • cognite_client (CogniteClient) – The client to associate with this object.
class cognite.client.data_classes.iam.APIKeyList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.client.data_classes.iam.Group(name: str = None, source_id: str = None, capabilities: List[Dict[str, Any]] = None, id: int = None, is_deleted: bool = None, deleted_time: int = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

No description.

Parameters:
  • name (str) – Name of the group
  • source_id (str) – ID of the group in the source. If this is the same ID as a group in the IDP, a user in that group will implicitly be a part of this group as well.
  • capabilities (List[Dict[str, Any]]) – No description.
  • id (int) – No description.
  • is_deleted (bool) – No description.
  • deleted_time (int) – No description.
  • cognite_client (CogniteClient) – The client to associate with this object.
class cognite.client.data_classes.iam.GroupList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.client.data_classes.iam.SecurityCategory(name: str = None, id: int = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

No description.

Parameters:
  • name (str) – Name of the security category
  • id (int) – Id of the security category
  • cognite_client (CogniteClient) – The client to associate with this object.
class cognite.client.data_classes.iam.SecurityCategoryList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.client.data_classes.iam.ServiceAccount(name: str = None, groups: List[int] = None, id: int = None, is_deleted: bool = None, deleted_time: int = None, cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResource

No description.

Parameters:
  • name (str) – Unique name of the service account
  • groups (List[int]) – List of group ids
  • id (int) – No description.
  • is_deleted (bool) – If this service account has been logically deleted
  • deleted_time (int) – Time of deletion
  • cognite_client (CogniteClient) – The client to associate with this object.
class cognite.client.data_classes.iam.ServiceAccountList(resources: List[Any], cognite_client=None)

Bases: cognite.client.data_classes._base.CogniteResourceList

Base data classes

CogniteResource

class cognite.client.data_classes._base.CogniteResource
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]
to_pandas(expand: List[str] = None, ignore: List[str] = None)

Convert the instance into a pandas DataFrame.

Returns:The dataframe.
Return type:pandas.DataFrame

CogniteResourceList

class cognite.client.data_classes._base.CogniteResourceList(resources: List[Any], cognite_client=None)
dump(camel_case: bool = False) → List[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 list of dicts representing the instance.
Return type:List[Dict[str, Any]]
get(id: int = None, external_id: str = None) → Optional[cognite.client.data_classes._base.CogniteResource]

Get an item from this list by id or exernal_id.

Parameters:
  • id (int) – The id of the item to get.
  • external_id (str) – The external_id of the item to get.
Returns:

The requested item

Return type:

Optional[CogniteResource]

to_pandas() → pandas.DataFrame

Convert the instance into a pandas DataFrame.

Returns:The dataframe.
Return type:pandas.DataFrame

CogniteResponse

class cognite.client.data_classes._base.CogniteResponse
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]

CogniteFilter

class cognite.client.data_classes._base.CogniteFilter
dump(camel_case: bool = False)

Dump the instance into a json serializable Python data type.

Returns:A dictionary representation of the instance.
Return type:Dict[str, Any]

CogniteUpdate

class cognite.client.data_classes._base.CogniteUpdate(id: int = None, external_id: str = None)
dump()

Dump the instance into a json serializable Python data type.

Returns:A dictionary representation of the instance.
Return type:Dict[str, Any]

Exceptions

CogniteAPIError

exception cognite.client.exceptions.CogniteAPIError(message: str, code: int = None, x_request_id: str = None, missing: List[T] = None, duplicated: List[T] = None, successful: List[T] = None, failed: List[T] = None, unknown: List[T] = None, unwrap_fn: Callable = None)

Cognite API Error

Raised if a given request fails. If one or more of concurrent requests fails, this exception will also contain information about which items were successfully processed (2xx), which may have been processed (5xx), and which have failed to be processed (4xx).

Parameters:
  • message (str) – The error message produced by the API
  • code (int) – The error code produced by the failure
  • x_request_id (str) – The request-id generated for the failed request.
  • extra (Dict) – A dict of any additional information.
  • successful (List) – List of items which were successfully proccessed.
  • failed (List) – List of items which failed.
  • unknown (List) – List of items which may or may not have been successfully processed.

Examples

Catching an API-error and handling it based on the error code:

from cognite.client import CogniteClient
from cognite.client.exceptions import CogniteAPIError

c = CogniteClient()

try:
    c.login.status()
except CogniteAPIError as e:
    if e.code == 401:
        print("You are not authorized")
    elif e.code == 400:
        print("Something is wrong with your request")
    elif e.code == 500:
        print("Something went terribly wrong. Here is the request-id: {}".format(e.x_request_id)
    print("The message returned from the API: {}".format(e.message))

CogniteNotFoundError

exception cognite.client.exceptions.CogniteNotFoundError(not_found: List[T], successful: List[T] = None, failed: List[T] = None, unknown: List[T] = None, unwrap_fn: Callable = None)

Cognite Not Found Error

Raised if one or more of the referenced ids/external ids are not found.

Parameters:
  • not_found (List) – The ids not found.
  • successful (List) – List of items which were successfully proccessed.
  • failed (List) – List of items which failed.
  • unknown (List) – List of items which may or may not have been successfully processed.

CogniteDuplicatedError

exception cognite.client.exceptions.CogniteDuplicatedError(duplicated: List[T], successful: List[T] = None, failed: List[T] = None, unknown: List[T] = None, unwrap_fn: Callable = None)

Cognite Duplicated Error

Raised if one or more of the referenced ids/external ids have been duplicated in the request.

Parameters:
  • duplicated (list) – The duplicated ids.
  • successful (List) – List of items which were successfully proccessed.
  • failed (List) – List of items which failed.
  • unknown (List) – List of items which may or may not have been successfully processed.

CogniteAPIKeyError

exception cognite.client.exceptions.CogniteAPIKeyError

Cognite API Key Error.

Raised if the API key is missing or invalid.

CogniteImportError

exception cognite.client.exceptions.CogniteImportError(module: str, message: str = None)

Cognite Import Error

Raised if the user attempts to use functionality which requires an uninstalled package.

Parameters:
  • module (str) – Name of the module which could not be imported
  • message (str) – The error message to output.

CogniteMissingClientError

exception cognite.client.exceptions.CogniteMissingClientError

Cognite Missing Client Error

Raised if the user attempts to make use of a method which requires the cognite_client being set, but it is not.

Utils

Convert timestamp to milliseconds since epoch

cognite.client.utils.timestamp_to_ms(timestamp: Union[int, float, str, datetime.datetime]) → int

Returns the ms representation of some timestamp given by milliseconds, time-ago format or datetime object

Parameters:timestamp (Union[int, float, str, datetime]) – Convert this timestamp to ms.
Returns:Milliseconds since epoch representation of timestamp
Return type:int

Convert milliseconds since epoch to datetime

cognite.client.utils.ms_to_datetime(ms: Union[int, float]) → datetime.datetime

Converts milliseconds since epoch to datetime object.

Parameters:ms (Union[int, float]) – Milliseconds since epoch
Returns:Datetime object.
Return type:datetime