Cognite Data Fusion API

Create subscriptions

Create one or more subscriptions that can be used to listen for changes in data points for a set of time series.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code

Request

Request Body schema: application/json
required

The subscriptions to create.

required

Array of objects = 1 items

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

Limits

Filter query max depth: 10.
Filter query max number of clauses: 100.
and and or clauses must have at least one element (and at most 99, since each element counts towards the total clause limit, and so does the and/or clause itself).
The property array 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 property array must match one of the existing properties (static top-level property or dynamic metadata property).
containsAll, containsAny, and in filter values array size must be in the range [1, 100].
containsAll, containsAny, and in filter values array must contain elements of number or string type (matching the type of the given property).
range filter must have at lest one of gt, gte, lt, lte attributes. But gt is mutually exclusive to gte, while lt is mutually exclusive to lte.
gt, gte, lt, lte in the range filter must be of number or string type (matching the type of the given property).
The maximum length of the value of a leaf filter that is applied to a string property is 256.

Responses

201

A list of subscriptions that were created.

post/timeseries/subscriptions

Request samples

Payload
Python SDK
curl

application/json

{"items": [{"externalId": "string",
"name": "string",
"description": "string",
"dataSetId": 1,
"partitionCount": 1,
"timeSeriesIds": ["my.known.id"
],
"instanceIds": [{"space": "string",
"externalId": "string"
}
],
"filter": {"or": [{"not": {"and": [{"equals": {"property": ["metadata",
"manufacturer"
],
"value": "acme"
}
},
{"in": {"property": ["name"
],
"values": ["pump-1-temperature",
"motor-9-temperature"
]
}
},
{"range": {"property": ["dataSetId"
],
"gte": 1,
"lt": 10
}
}
]
}
},
{"and": [{"equals": {"property": ["assetId"
],
"value": 1234
}
},
{"equals": {"property": ["description"
],
"value": "Temperature in Celsius"
}
}
]
}
]
}
}
]
}

Response samples