Filter sequences

Retrieves a list of sequences that match the given criteria.

Advanced filtering

The advancedFilter 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
search ["name"] and ["description"] Introduced to provide functional parity with the /sequences/search endpoint.
{"search": {"property": ["property"], "value": "example"}}

Supported properties

Property Type
["description"] string
["externalId"] string
["metadata", "<someCustomKey>"] string
["name"] string
["assetId"] number
["assetRootId"] number
["createdTime"] number
["dataSetId"] number
["id"] number
["lastUpdatedTime"] number
["accessCategories"] array of strings

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).
  • search filter value must not be blank, and the length must be in the range [1, 128], and there may be at most two search filters in the entire filter query.
  • The maximum length of the value of a leaf filter that is applied to a string property is 256.

Sorting

By default, sequences are sorted by their creation time in ascending order. Sorting by another property or by several other properties can be explicitly requested via the sort field, which must contain a list of one or more sort specifications. Each sort specification indicates the property to sort on and, optionally, the order in which to sort (defaults to asc). If multiple sort specifications are supplied, the results are sorted on the first property, and those with the same value for the first property are sorted on the second property, and so on.
Partitioning is done independently of sorting; there is no guarantee of sort order between elements from different partitions.

Null values

In case the nulls field has the auto value, or the field isn't specified, null (missing) values are considered bigger than any other values. They are placed last when sorting in the asc order and first in the desc order. Otherwise, missing values are placed according to the nulls field (last or first), and their placement won't depend on the order field. Note that the number zero, empty strings, and empty lists are all considered not null.

Example

{
  "sort": [
    {
      "property" : ["createdTime"],
      "order": "desc",
      "nulls": "last"
    },
    {
      "property" : ["metadata", "<someCustomKey>"]
    }
  ]
}

Properties

You can sort on the following properties:

Property
["assetId"]
["createdTime"]
["dataSetId"]
["description"]
["externalId"]
["lastUpdatedTime"]
["metadata", "<someCustomKey>"]
["name"]

Limits

The sort array must contain 1 to 2 elements.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json

Retrieves a list of sequences matching the given criteria.

object (SequenceFilter)
(Boolean filter (and (object) or or (object) or not (object))) or (Leaf filter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or search (object))) (TimeSeriesFilterLanguage)

A filter DSL (Domain Specific Language) to define advanced filter queries.

At the top level, an advancedFilter expression is either a single Boolean filter or a single leaf filter. Boolean filters contain other Boolean filters and/or leaf filters. The total number of filters may be at most 100, and the depth (the greatest number of times filters have been nested inside each other) may be at most 10. The search leaf filter may at most be used twice within a single advancedFilter, but all other filters can be used as many times as you like as long as the other limits are respected.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Returns up to this many results per page.

cursor
string
partition
string (Partition)

Splits the data set into N partitions. The attribute is specified as a "M/N" string, where M is a natural number in the interval of [1, N]. You need to follow the cursors within each partition in order to receive all the data.

To prevent unexpected problems and maximize read throughput, you should at most use 10 (N <= 10) partitions.

When using more than 10 partitions, CDF may reduce the number of partitions silently. For example, CDF may reduce the number of partitions to K = 10 so if you specify an X/N partition value where X = 8 and N = 20 - i.e. "partition": "8/20"- then CDF will change N to N = K = 10 and process the request. But if you specify the X/N partition value where X = 11 (X > K) and N = 20 - i.e. "partition": "11/20"- then CDF will reply with an empty result list and no cursor in the response.

In future releases of the resource APIs, Cognite may reject requests if you specify more than 10 partitions. When Cognite enforces this behavior, the requests will result in a 400 Bad Request status.

Array of objects (TimeSeriesSortItem) [ 1 .. 2 ] items

Sort by array of selected properties.

Responses
200

Response with a list of sequences matching the given criteria.

post/sequences/list
Request samples
application/json
{
  • "filter": {
    • "name": "string",
    • "externalIdPrefix": "my.known.prefix",
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "rootAssetIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "dataSetIds": [
      ]
    },
  • "advancedFilter": {
    • "or": [
      ]
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "partition": "1/10",
  • "sort": [
    • {
      }
    ]
}
Response samples
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}