Create subscriptions
Required capabilities:
timeSeriesSubscriptionsAcl:WRITE
Create one or more subscriptions that can be used to listen for changes in data points for a set of time series.
Documentation Index
Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
Use this file to discover all available pages before exploring further.
Authorizations
Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.
Body
The subscriptions to create.
Subscription definitions. A subscription may be configured explicitly with a list
of time series, or it may be a configured dynamically through a filter. The
subscription cannot change type later.
An explicit list must be manually updated by the user, while a filter will be updated
automatically whenever a time series is added/deleted/updated (eventually consistent).
The filter subscriptions uses the same syntax as advanced filters in the Filter time series
endpoint, with two exceptions: The field is named `filter` instead of `advancedFilter`,
and we do not support the `search` LeafFilter.
Advanced filtering
The filter
field lets you create complex filtering expressions that combine simple operations,
such as equals, prefix, and exists, by using the Boolean operators and, or, and not.
Filtering applies to basic fields as well as metadata. See the advancedFilter syntax in the request example.
Supported leaf filters
| Leaf filter | Supported fields | Description and example |
|---|---|---|
containsAll | Array type fields | Only includes results which contain all of the specified values. {"containsAll": {"property": ["property"], "values": [1, 2, 3]}} |
containsAny | Array type fields | Only includes results which contain at least one of the specified values. {"containsAny": {"property": ["property"], "values": [1, 2, 3]}} |
equals | Non-array type fields | Only includes results that are equal to the specified value. {"equals": {"property": ["property"], "value": "example"}} |
exists | All fields | Only includes results where the specified property exists (has a value). {"exists": {"property": ["property"]}} |
in | Non-array type fields | Only includes results that are equal to one of the specified values. {"in": {"property": ["property"], "values": [1, 2, 3]}} |
prefix | String type fields | Only includes results which start with the specified text. {"prefix": {"property": ["property"], "value": "example"}} |
range | Non-array type fields | Only includes results that fall within the specified range. {"range": {"property": ["property"], "gt": 1, "lte": 5}} Supported operators: gt, lt, gte, lte |
Supported properties
| Property | Type |
|---|---|
["description"] | string |
["externalId"] | string |
["metadata", "<someCustomKey>"] | string |
["name"] | string |
["unit"] | string |
["unitExternalId"] | string |
["unitQuantity"] | string |
["instanceId", "space"] | string |
["instanceId", "externalId"] | string |
["assetId"] | number |
["assetRootId"] | number |
["createdTime"] | number |
["dataSetId"] | number |
["id"] | number |
["lastUpdatedTime"] | number |
["isStep"] | Boolean |
["isString"] | Boolean |
["type"] | string |
Limits
- Filter query max depth: 10.
- Filter query max number of clauses: 100.
andandorclauses must have at least one element (and at most 99, since each element counts towards the total clause limit, and so does theand/orclause itself).- The
propertyarray of each leaf filter has the following limitations:- Number of elements in the array is 1 or 2.
- Elements must not be null or blank.
- Each element max length is 256 characters.
- The
propertyarray must match one of the existing properties (static top-level property or dynamic metadata property).
containsAll,containsAny, andinfiltervaluesarray size must be in the range [1, 100].containsAll,containsAny, andinfiltervaluesarray must contain elements of number or string type (matching the type of the given property).rangefilter must have at lest one ofgt,gte,lt,lteattributes. Butgtis mutually exclusive togte, whileltis mutually exclusive tolte.gt,gte,lt,ltein therangefilter must be of number or string type (matching the type of the given property).- The maximum length of the
valueof a leaf filter that is applied to a string property is 256.
1 elementResponse
A list of subscriptions that were created.
List of subscriptions.