Time series - Cognite Docs

Legacy data modeling

This resource is part of the asset-centric data model.

New projects: We recommend using the data modeling service for greater flexibility and performance.
Existing projects: Asset-centric time series metadata and asset filters are deprecated. Data point reads and writes stay available through instanceId. See Deprecated and retired features and Data modeling status for CDF projects.

Looking for datapoint operations? See Time series and datapoints for inserting, retrieving, and querying time series data.This page focuses on time series metadata management for asset-centric projects.

The time series API lets you create, update, search, and manage time series metadata in asset-centric projects. For data modeling projects, use the Instances API to manage time series as instances in your data model. A time series indexes a series of data points in time order. Examples include the temperature of a water pump asset, monthly precipitation in a location, and the daily average number of manufacturing defects. An asset can have several time series connected to it. For example, a water pump asset can have time series that measure pump temperature, pressure, rpm, flow volume, power consumption, and more. Each time series has a unique id generated at creation. You can specify an externalId to control the identifier, which must be unique within a project. Time series can also have metadata key-value fields and labels for organization and categorization.

Count time series matching filter criteria

Count the number of time series that match selected filtering criteria, such as being part of a specific data set or following a naming convention for externalId.

Example: count time series by filter criteria

POST /api/v1/projects/daitya/timeseries/aggregate HTTP/1.1
content-type: application/json

{
  "filter": {
    "dataSetIds": [
      {
        "externalId": "Cognite data quality monitoring alerts and metrics"
      }
    ],
    "externalIdPrefix": "dq_monitor"
  }
}

The response will look similar to this:

{
  "items": [
    {
      "count": 273
    }
  ]
}

Advanced filtering

Time series advancedFilter uses the same leaf filters as asset advanced filtering. See Filter language. Time series limits differ from assets:

Maximum depth is 10, and the maximum number of clauses is 100. Each element of and or or counts toward that total, as does the and or or clause itself, so a boolean clause can hold at most 99 elements.
Each property element is at most 256 characters.
A leaf filter on a string property accepts a value of at most 256 characters.
A query can contain at most 2 search leaf filters, each 1 to 128 characters.

Aggregates

When aggregate is omitted, the endpoint returns the count of matching time series, the same result as aggregate set to count. Set aggregate to uniqueValues and name one property in properties to list the distinct values of that property, up to 1000 values. filter and advancedFilter select which time series are included.

List data points

POST /timeseries/data/list reads data points from multiple time series and supports aggregation and pagination. If start is omitted both at the top level and on an item, it defaults to epoch 0 (1 January 1970). Data points before 1970 are excluded unless you set start to a negative number.

Best practices

Use these tips to increase throughput and query performance.

Message size and batching

Send many data points from the same time series in the same request. If you have room for more data points in the request, you can add more time series. Preferred batch sizes are up to 100k numeric data points or 10-100k string data points, depending on the string length (around 1 MB is good). For each time series, group the data points in time. Ideally, different requests shouldn’t have overlapping time series ranges. If data changes, update existing ranges.

Error handling

For general guidance on handling 429 Too Many Requests responses, exponential backoff, and retry strategies, see API rate limits. If you receive repeated 500 Internal Server Error responses, you may have found a bug. Contact support@cognite.com and include the request ID from the error message.

Retries and idempotency

Most API endpoints, including all datapoint requests, are idempotent. You can send the same request several times without any effect beyond the first request. When you modify or delete time series, subsequent requests can fail harmlessly if the references have become invalid. The only endpoint that’s not idempotent is creating a time series without externalId. For each successful request, you generate a new time series. The recommendation is to always use externalId on your time series.

CDF always applies the complete request or nothing at all. A 200 response indicates that the complete request was applied.

​Count time series matching filter criteria

​Advanced filtering

​Aggregates

​List data points

​Best practices

​Message size and batching

​Error handling

​Retries and idempotency

Count time series matching filter criteria

Advanced filtering

Aggregates

List data points

Best practices

Message size and batching

Error handling

Retries and idempotency