{"id":5157,"library":"cognite-sdk","title":"Cognite Python SDK","description":"The Cognite Python SDK is a client library for interacting with Cognite Data Fusion (CDF), a cloud-based industrial data platform. It simplifies programmatic access to CDF's APIs, enabling developers and data scientists to work efficiently with industrial data. The package is tightly integrated with pandas, facilitating data manipulation. The current version is 8.0.7, and major versions are released periodically, introducing significant new features like full asynchronous support in v8.","status":"active","version":"8.0.7","language":"en","source_language":"en","source_url":"https://github.com/cognitedata/cognite-sdk-python","tags":["SDK","API","Cognite Data Fusion","CDF","cloud","async","industrial data"],"install":[{"cmd":"pip install cognite-sdk","lang":"bash","label":"Core installation"},{"cmd":"pip install \"cognite-sdk[pandas, geo]\"","lang":"bash","label":"With optional dependencies (e.g., pandas and geospatial)"}],"dependencies":[{"reason":"Required Python version.","package":"python","optional":false},{"reason":"New required dependency since v8, replaces 'requests' for HTTP operations and enables async functionality.","package":"httpx","optional":false},{"reason":"For enhanced DataFrame integration, available via 'cognite-sdk[pandas]' extra.","package":"pandas","optional":true},{"reason":"For geospatial data handling, available via 'cognite-sdk[geo]' extra.","package":"geopandas","optional":true}],"imports":[{"note":"The synchronous client, still fully supported and wraps the AsyncCogniteClient internally in v8.","symbol":"CogniteClient","correct":"from cognite.client import CogniteClient"},{"note":"The new primary asynchronous client introduced in v8.","symbol":"AsyncCogniteClient","correct":"from cognite.client import AsyncCogniteClient"},{"note":"Used for configuring the client instance.","symbol":"ClientConfig","correct":"from cognite.client import ClientConfig"},{"note":"A common credential provider for OAuth2 client credentials flow.","symbol":"OAuthClientCredentials","correct":"from cognite.client.credentials import OAuthClientCredentials"},{"note":"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.","wrong":"from cognite.client.data_classes._some_internal_module import SomeClass","symbol":"Internal Modules","correct":"from cognite.client import SomeClass"}],"quickstart":{"code":"import os\nfrom cognite.client import CogniteClient, AsyncCogniteClient, ClientConfig, global_config\nfrom cognite.client.credentials import OAuthClientCredentials\nimport asyncio\n\n# It is highly recommended to use environment variables for sensitive information.\n# Example environment variables:\n# COGNITE_TENANT_ID='YOUR_TENANT_ID'\n# COGNITE_CLIENT_ID='YOUR_CLIENT_ID'\n# COGNITE_CLIENT_SECRET='YOUR_CLIENT_SECRET'\n# COGNITE_CLUSTER='westeurope-1'\n# COGNITE_PROJECT='my-cdf-project'\n# COGNITE_CLIENT_NAME='my-python-app'\n\n# 1. Configure the client using environment variables\ntenant_id = os.environ.get('COGNITE_TENANT_ID', 'your-tenant-id')\nclient_id = os.environ.get('COGNITE_CLIENT_ID', 'your-client-id')\nclient_secret = os.environ.get('COGNITE_CLIENT_SECRET', 'your-client-secret')\ncluster = os.environ.get('COGNITE_CLUSTER', 'api') # e.g., 'westeurope-1' for 'https://westeurope-1.cognitedata.com'\nproject = os.environ.get('COGNITE_PROJECT', 'my-cdf-project')\nclient_name = os.environ.get('COGNITE_CLIENT_NAME', 'my-python-app')\n\nbase_url = f\"https://{cluster}.cognitedata.com\"\n\ncreds = OAuthClientCredentials(\n    token_url=f\"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token\",\n    client_id=client_id,\n    client_secret=client_secret,\n    scopes=[f\"{base_url}/.default\"]\n)\n\nclient_config = ClientConfig(\n    client_name=client_name,\n    base_url=base_url,\n    project=project,\n    credentials=creds\n)\n\n# Optionally set a global configuration (will be used if no config is explicitly passed)\nglobal_config.default_client_config = client_config\n\n# 2. Instantiate a synchronous client (still supported in v8)\nsync_client = CogniteClient()\nprint(f\"Synchronous client initialized for project: {sync_client.config.project}\")\n# Example usage:\n# assets = sync_client.assets.list(limit=1)\n# if assets: print(f\"Found asset: {assets[0].name}\")\n\n# 3. Instantiate an asynchronous client (new and recommended in v8)\nasync def main():\n    async_client = AsyncCogniteClient()\n    print(f\"Asynchronous client initialized for project: {async_client.config.project}\")\n    # Example usage:\n    # tss = await async_client.time_series.list(limit=1)\n    # if tss: print(f\"Found time series: {tss[0].name}\")\n    await async_client.close()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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()`).","message":"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.","severity":"breaking","affected_versions":"8.x.x (from 7.x.x)"},{"fix":"Replace `client.datapoints` with `client.time_series.data`. Replace `client.extraction_pipeline_runs` with `client.extraction_pipelines.runs`.","message":"Removed deprecated API accessors. `client.datapoints` and `client.extraction_pipeline_runs` attributes are no longer available.","severity":"breaking","affected_versions":"8.x.x (from 7.x.x)"},{"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.","message":"Generic `aggregate` and `filter` methods on classic CDF APIs (Assets, Events, Sequences, TimeSeries) have been removed or replaced with more specific alternatives.","severity":"breaking","affected_versions":"8.x.x (from 7.x.x)"},{"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.","message":"The static method `NodeId.load_if()` was removed. Attempting to call it will result in an `AttributeError`.","severity":"breaking","affected_versions":"8.x.x (from 7.x.x)"},{"fix":"Always use environment variables, a secure configuration file, or a credential provider that fetches tokens securely (e.g., `OAuthClientCredentials` as shown in quickstart).","message":"Hardcoding credentials (API keys, client secrets) is a security risk.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Importing from internal SDK modules (e.g., `cognite.client.data_classes._some_module`) can lead to breaking changes.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}