Cognite Python SDK

Warnings

• breaking Major architectural shift to full asynchronous support in v8. The new `AsyncCogniteClient` is the primary client, and the synchronous `CogniteClient` now internally wraps the async client. This also introduces `httpx` as a new required dependency.
  Fix: Migrate to `AsyncCogniteClient` for native async/await patterns. If continuing to use `CogniteClient`, be aware it's now an async wrapper. Ensure `httpx` is installed. Review helper/utility methods, as many now have `_async` variants (e.g., `asset.children_async()`).
• breaking Removed deprecated API accessors. `client.datapoints` and `client.extraction_pipeline_runs` attributes are no longer available.
  Fix: Replace `client.datapoints` with `client.time_series.data`. Replace `client.extraction_pipeline_runs` with `client.extraction_pipelines.runs`.
• breaking Generic `aggregate` and `filter` methods on classic CDF APIs (Assets, Events, Sequences, TimeSeries) have been removed or replaced with more specific alternatives.
  Fix: Use specific aggregation methods like `aggregate_count`, `aggregate_unique_values`, etc. For filtering, use the `list` method with `advanced_filters` instead of the generic `filter` method.
• breaking The static method `NodeId.load_if()` was removed. Attempting to call it will result in an `AttributeError`.
  Fix: This method was likely an internal implementation detail and has been removed in v8. If you relied on this, you may need to re-evaluate your approach or use the (potentially internal) `_load_if` if absolutely necessary, but this is not recommended.
• gotcha Hardcoding credentials (API keys, client secrets) is a security risk.
  Fix: Always use environment variables, a secure configuration file, or a credential provider that fetches tokens securely (e.g., `OAuthClientCredentials` as shown in quickstart).
• gotcha Importing from internal SDK modules (e.g., `cognite.client.data_classes._some_module`) can lead to breaking changes.
  Fix: Only import symbols directly from `cognite.client` or other documented top-level modules. Internal module structures are not part of the public API and can change without warning between versions.

Install

• pip install cognite-sdk Core installation
• pip install "cognite-sdk[pandas, geo]" With optional dependencies (e.g., pandas and geospatial)

Imports

• CogniteClient

  from cognite.client import CogniteClient

  The synchronous client, still fully supported and wraps the AsyncCogniteClient internally in v8.
• AsyncCogniteClient

  from cognite.client import AsyncCogniteClient

  The new primary asynchronous client introduced in v8.
• ClientConfig

  from cognite.client import ClientConfig

  Used for configuring the client instance.
• OAuthClientCredentials

  from cognite.client.credentials import OAuthClientCredentials

  A common credential provider for OAuth2 client credentials flow.
• Internal Modules

  from cognite.client import SomeClass

  Avoid importing from internal SDK modules (prefixed with `_`) as their structure may change, leading to compatibility issues. All public interfaces should be imported from the top level `cognite.client` package.

Quickstart

This quickstart demonstrates how to instantiate both the synchronous (`CogniteClient`) and asynchronous (`AsyncCogniteClient`) clients for Cognite Data Fusion, emphasizing the recommended use of environment variables for secure credential handling via `OAuthClientCredentials` and `ClientConfig`. The `AsyncCogniteClient` is new in v8 and is now the primary client.

import os
from cognite.client import CogniteClient, AsyncCogniteClient, ClientConfig, global_config
from cognite.client.credentials import OAuthClientCredentials
import asyncio

# It is highly recommended to use environment variables for sensitive information.
# Example environment variables:
# COGNITE_TENANT_ID='YOUR_TENANT_ID'
# COGNITE_CLIENT_ID='YOUR_CLIENT_ID'
# COGNITE_CLIENT_SECRET='YOUR_CLIENT_SECRET'
# COGNITE_CLUSTER='westeurope-1'
# COGNITE_PROJECT='my-cdf-project'
# COGNITE_CLIENT_NAME='my-python-app'

# 1. Configure the client using environment variables
tenant_id = os.environ.get('COGNITE_TENANT_ID', 'your-tenant-id')
client_id = os.environ.get('COGNITE_CLIENT_ID', 'your-client-id')
client_secret = os.environ.get('COGNITE_CLIENT_SECRET', 'your-client-secret')
cluster = os.environ.get('COGNITE_CLUSTER', 'api') # e.g., 'westeurope-1' for 'https://westeurope-1.cognitedata.com'
project = os.environ.get('COGNITE_PROJECT', 'my-cdf-project')
client_name = os.environ.get('COGNITE_CLIENT_NAME', 'my-python-app')

base_url = f"https://{cluster}.cognitedata.com"

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

client_config = ClientConfig(
    client_name=client_name,
    base_url=base_url,
    project=project,
    credentials=creds
)

# Optionally set a global configuration (will be used if no config is explicitly passed)
global_config.default_client_config = client_config

# 2. Instantiate a synchronous client (still supported in v8)
sync_client = CogniteClient()
print(f"Synchronous client initialized for project: {sync_client.config.project}")
# Example usage:
# assets = sync_client.assets.list(limit=1)
# if assets: print(f"Found asset: {assets[0].name}")

# 3. Instantiate an asynchronous client (new and recommended in v8)
async def main():
    async_client = AsyncCogniteClient()
    print(f"Asynchronous client initialized for project: {async_client.config.project}")
    # Example usage:
    # tss = await async_client.time_series.list(limit=1)
    # if tss: print(f"Found time series: {tss[0].name}")
    await async_client.close()

if __name__ == "__main__":
    asyncio.run(main())