Asset-centric OData service
Connect Cognite Data Fusion (CDF) as a data source and use OData clients to query, transform, and visualize data stored in CDF asset-centric resources.
The asset-centric OData service lets you access CDF resources such as assets, time series, events, files, sequences, and RAW data via an OData API.
The asset-centric OData service accepts URLs with the following schema:
https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}
Where:
{cluster}: the name of the CDF cluster, e.g., westeurope-1.{apiVersion}: the version of the OData service API (latest is v1).{project}: the name of the CDF project, e.g., publicdata.
If you point the OData client to the correct asset-centric OData URL and authenticate, the server returns a table with all asset-centric types currently supported by the OData service in addition to supported OData functions.
Filtering asset-centric resource types
The asset-centric OData service can push filters down to CDF. This improves performance by ensuring that filtering happens on the server side, reducing the amount of data transmitted to the client.
Filtering options
- Pushdown: Filter functions that are pushed down to the
CDF backend. This is the most efficient filtering.
- Local: Filtering done by the~~ OData~~ service before returning the result to the client. Less efficient than pushdown.
- Client-side: Filtering done by the client after data is retrieved. Least efficient.
Definitions
- FilterFunctions:
Contains, StartsWith, and EndsWith.
- Comparison:
<, <=, >, >=, and =.
- Search: uses the search API and may require additional local filtering.
Search returns a limited number of rows, and you may not receive all matching data in CDF.
Assets
| Property | Pushdown | Local |
|---|
Id | = | = |
ExternalId | =, StartsWith | =, FilterFunctions |
Name | =, Search | =, FilterFunctions |
Description | Search | =, FilterFunctions |
ParentId | = | = |
ParentExternalId | = | = |
DataSetId | = | = |
Source | = | = |
MetaData | = | |
RootId | = | = |
CreatedTime | Comparison | Comparison |
LastUpdatedTime | Comparison | Comparison |
Time series
| Property | Pushdown | Local |
|---|
Id | = | = |
ExternalId | =, StartsWith | =, FilterFunctions |
Name | =, Search | =, FilterFunctions |
Description | Search | =, FilterFunctions |
IsString | = | = |
MetaData | = | |
Unit | = | = |
IsStep | = | = |
AssetId | = | = |
SecurityCategories | | |
DataSetId | = | = |
CreatedTime | Comparison | Comparison |
LastUpdatedTime | Comparison | Comparison |
Data point
| Property | Pushdown | Local |
|---|
Id | = | = |
TimeStamp | Comparison | Comparison |
Events
| Property | Pushdown | Local |
|---|
Id | = | = |
ExternalId | =, StartsWith | FilterFunctions |
Description | Search | =, FilterFunctions |
Source | = | = |
Type | = | = |
SubType | = | = |
MetaData | = | |
DataSetId | = | = |
StartTime | Comparison | Comparison |
EndTime | Comparison | Comparison |
CreatedTime | Comparison | Comparison |
LastUpdatedTime | Comparison | Comparison |
AssetIds | Contains | Contains |
Files
| Property | Pushdown | Local |
|---|
Id | = | = |
ExternalId | =, StartsWith | =, FilterFunctions |
Name | =, Search | =, FilterFunctions |
Source | = | = |
MimeType | = | = |
MetaData | | |
DataSetId | = | = |
SourceCreatedTime | Comparison | Comparison |
SourceModifiedTime | Comparison | Comparison |
CreatedTime | Comparison | Comparison |
LastUpdatedTime | Comparison | Comparison |
UploadedTime | Comparison | Comparison |
Uploaded | = | = |
AssetIds | Contains | Contains |
Sequences
| Property | Pushdown | Local |
|---|
Id | * | = |
ExternalId | StartsWith | =, StartsWith |
Name | =, Search | =, FilterFunctions |
Description | =, Search | =, FilterFunctions |
MetaData | | |
AssetId | = | = |
DataSetId | = | = |
CreatedTime | Comparison | Comparison |
LastUpdatedTime | Comparison | Comparison |
Columns | | |
Supported via the Sequences(id) syntax.
CDF RAW databases
| Property | Pushdown | Local |
|---|
Name | = | = |
CDF RAW tables
| Property | Pushdown | Local |
|---|
Name | = | = |
CDF RAW rows
| Property | Pushdown | Local |
|---|
Key | = | =, FilterFunction |
LastUpdatedTime | Comparison | Comparison |
Supported OData functions
AssetsRoots
Fetch the root assets for a CDF project.
| Parameter | Type | Description |
|---|
| No parameters | | |
AssetsSearch
Search assets in a CDF project.
| Parameter | Type | Description |
|---|
Search | Text | Whitespace-separated terms to search for in assets. Does a best-effort fuzzy search in relevant fields (currently name and description) for variations of any search terms. Orders results by relevance. |
EventsSearch
Search events in a CDF project.
| Parameter | Type | Description |
|---|
Search | Text | Whitespace-separated terms to search for in events. Does a best-effort fuzzy search in relevant fields (currently description) for variations of any search terms. Orders results by relevance. |
TimeseriesAggregate
Aggregate data points from multiple time series.
| Parameter | Type | Description |
|---|
Tags | Text | A comma-separated list of time series IDs or external IDs to include in the query. |
Granularity | Text | The granularity used to fetch data point aggregates. |
Start | Text | Get datapoints starting from and including this time. |
End | Text (optional) | Get datapoints up to, but excluding, this point in time. If no value is provided, defaults to now. |
TimeseriesSearch
Search time series in a CDF project.
| Parameter | Type | Description |
|---|
Search | Text | A whitespace-separated terms to search for in time series. Does a best-effort fuzzy search in relevant fields (currently name and description) for variations of any search terms and orders results by relevance. |