Get started with Python SDK

Installation

To install the Python SDK package:

pip install cognite-sdk

The SDK is tightly integrated with the pandas library. To install use:

pip install "cognite-sdk[pandas]"

To upgrade the version of the Python SDK package:

pip install --upgrade cognite-sdk

Authenticate

The preferred way to authenticate against the Cognite API is using OpenID Connect (OIDC). To enable this, use one of the credential providers, such as OAuthClientCredentials:

python
from cognite.client import CogniteClient, ClientConfig
from cognite.client.credentials import OAuthClientCredentials

# This value will depend on the cluster your CDF project runs on
base_url = "https://api.cognitedata.com"
tenant_id = "my-tenant-id"

creds = OAuthClientCredentials(
    token_url=f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token",
    client_id="my-client-id",
    client_secret="my-client-secret",
    scopes=[f"{base_url}/.default"]
)

cnf = ClientConfig(
    client_name="custom-client-name",
    project="cdf-project-name",
    credentials=creds,
    base_url=base_url
)

client = CogniteClient(cnf)

You can find the examples for all OAuth credential providers in the Credential Providers section.

You can also make your own credential provider:

python
from cognite.client import CogniteClient, ClientConfig
from cognite.client.credentials import Token
def token_provider():
    ...
cnf = ClientConfig(
    client_name="my-special-client",
    base_url="https://<cluster>.cognitedata.com",
    project="my-project",
    credentials=Token(token_provider)
    )
c = CogniteClient(cnf)

To know more about authentication, see Authenticate with Azure AD.

If OIDC hasn't been enabled for your CDF project, you must authenticate using an API key.

from cognite.client import CogniteClient, ClientConfig
from cognite.client.credentials import APIKey
cnf = ClientConfig(
    client_name="<your-client-name>",
    base_url="https://<cluster>.cognitedata.com",
    project="my-project",
    credentials=APIKey("very-secret"))
c = CogniteClient(cnf)

Instantiate a new client

Use this code to instantiate a client and get your login status. CDF returns an object with attributes describing which project and service account your API key belongs to.

The client_name is a user-defined string intended to give the client a unique identifier. You can provide the client_name by passing it directly to the ClientConfig constructor.

You may set a default client configuration which will be used if no config is passed to CogniteClient. All examples in this documentation assume that a default configuration has been set.

from cognite.client import CogniteClient, ClientConfig, global_config
from cognite.client.credentials import APIKey
cnf = ClientConfig(client_name="my-special-client",base_url="https://<cluster>.cognitedata.com", project="my-project", credentials=APIKey("very-secret"))
global_config.default_client_config = cnf

client = CogniteClient()
status = client.login.status()

Read more about the CogniteClient and the functionality it exposes.

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 returns the first 25 time series resources.

from cognite.client import CogniteClient

client = CogniteClient()
ts_list = client.time_series.list()

Create an asset hierarchy

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

At the top of an asset hierarchy is a root asset (for example, the oil rig). Each project can have several 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

client = CogniteClient()
my_asset = Asset(name="my first asset", parent_id=123)

client.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 several requests.

To make sure that the assets are posted in the correct order, you can use the .create_hierarchy() function, which takes care of the sorting before splitting the request into smaller chunks. Note that the .create_hierarchy() function requires the external_id property to be set for all assets.

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

client = 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")

client.assets.create_hierarchy([root, child, descendant])

Wrap the .create_hierarchy() 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 weren't 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:
    client.assets.create_hierarchy([root, child, descendant])
except CogniteAPIError as e:
    assets_posted = e.successful
    assets_may_have_been_posted = e.unknown
    assets_not_posted = e.failed

Assets are used to connect related data, even if the data comes from different sources. Time series of data points, events, and files are all connected to one or more assets. A pump asset can be connected to a time series measuring pressure within the pump, as well as events recording maintenance operations and a file with a 3D diagram of the pump.

To retrieve all events related to a given subtree of assets, we first fetch the subtree under an asset using the .subtree() method. This returns an AssetList object with the .events() method. This method returns events related to any asset in the AssetList.

from cognite.client import CogniteClient
from cognite.client.data_classes import Asset

client = CogniteClient()
subtree_root_asset="some-external-id"
subtree = client.assets.retrieve(external_id=subtree_root_asset).subtree()
related_events = subtree.events()

You can use the same pattern to retrieve all time series or files related to a set of assets.

related_files = subtree.files()
related_time_series = subtree.time_series()

Next steps

To learn more about the Python SDK, see the SDK reference documentation.

Get started with Python SDK

Installation​

Authenticate​

Instantiate a new client​

Discover time series​

Create an asset hierarchy​

Retrieve all events related to an asset subtree​

Next steps​