Cognite OData services

Cognite provides OData services to fetch data from Cognite Data Fusion (CDF) using OData clients such as Microsoft Power BI, Microsoft Excel, and TIBCO Spotfire.

Open Data Protocol (OData) is an open standard defining best practices for building and consuming RESTful APIs. OData offers:

• Standardized query syntax: Enables consistent filtering, sorting, pagination, and projections across different data sources.

• Metadata support: Clients can discover the data structure and types via metadata documents.

• Interoperability: Any client that supports HTTP and understands OData can consume OData services.

Cognite provides an asset-centric OData service and a data-modeling OData service. Both services wrap the standard Cognite APIs, implementing an OData Version 4 API for read-only purposes. They translate OData requests into corresponding Cognite API calls, allowing you to interact with CDF data using OData-compatible clients and tools.

Using the OData services

To interact with the Cognite OData services, you make HTTP GET requests to specific endpoints.

Authenticate

To authenticate with the OData services, you must include a bearer token in the authorization header of your HTTP requests.

For example:

Authorization: Bearer {YourAccessToken}

You can obtain an access token using the appropriate authentication flow for your setup (e.g., OAuth 2.0, OpenID Connect). For more details, refer to the Authentication documentation.

Make requests

Example GET request

To retrieve all assets in a project:

GET https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/Assets

Where:

• {cluster}: The CDF cluster name (e.g., westeurope-1).
• {apiVersion}: The OData service API version (e.g., v1).
• {project}: Your CDF project name.

Query parameters

Use query parameters to filter, sort, select, and paginate data.

• Filtering - use the $filter query parameter to filter data.

  Example: Retrieve assets where Name equals 'Pump 1': GET .../Assets?$filter=Name eq 'Pump 1'

• Selecting fields- use the $select query parameter to retrieve specific fields.

  Example: Retrieve only the Id and Name of assets: GET .../Assets?$select=Id,Name

• Sorting - use the $orderby query parameter to sort results.

  Example: Order assets by Name ascending: GET .../Assets?$orderby=Name asc

• Expanding related entities - use the $expand query parameter to include related entities. Example: Retrieve an asset along with its parent: GET .../Assets(702630644612)/Parent?$expand=Parent

  Note: Not all entities and relationships support expansion. Refer to the individual service documentation for details.

• *Combining query parameters - you can combine multiple query parameters to refine your request.

  Example: Retrieve the Id and Name of assets where Name starts with 'Pump', ordered by Name, and retrieve the first 10 results: GET .../Assets?$filter=startswith(Name,'Pump')&$select=Id,Name&$orderby=Name asc&$top=10

Response format

The OData services return responses in JSON format, following the OData V4 standard.

Example response:

{
  "@odata.context": "https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/$metadata#Assets/",
  "value": [
    {
      "Id": "12345",
      "DataSetId": null,
      "ExternalId": "WMT:VAL",
      "Name": "Pump 1",
      "Description": "Main pump"
      // other properties
    }
  ]
}

Pagination in responses

The OData service may paginate the response for large result sets. The response includes a @odata.nextLink property with a URL to retrieve the next page of results.

Example:

{
  "@odata.context": "https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/$metadata#Assets",
  "value": [ // records ],
  "@odata.nextLink": "https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/Assets?$skipToken=123"
}

Limitations and supported features

The OData services aim to conform to the OData V4 standard, but some features may be limited or unsupported due to underlying constraints of the Cognite APIs.

Refer to the individual service documentation for detailed information on supported features and limitations.