Sequences

In Cognite Data Fusion, a sequence is a generic resource type for indexing a series of rows by row number. Each row contains one or more columns with either string or numeric data. Examples of sequences are performance curves and various types of logs.

In this article:

About sequences

An asset can have one or more sequences connected to it. You can analyze and visualize sequences to draw inferences from the data, for example to visualize the expected performance of a generator given its load. Another common way to use sequences is to store large amounts of data whose index are not linked to time.

A row is a piece of information associated with a row number. Each row has a number of columns, each containing an integer, floating point, or string value. You define the column types when you create the sequence, and each sequence can have up to 200 columns. The rows are identified by their row number, a searchable positive 64-bit integer. You can't search by other columns than the row number. The rows do not have to be consecutive or start at a specific number.

Typical use cases for sequences include:

  • Storing and retrieving an entire curve with an x-y dependency. In this case, use two floating-point columns so that you're not restricted by the integer type on the row number.
  • Storing a log based on distance or depth, with information in columns of different types for each entry. If you store the distance or depth as the row number (an integer), you may lose precision, but can search for all events that occurred at a particular distance or depth.

See the sequences API documentation for more information about how to work with sequences.

Create a sequence

To create a sequence, you need to define the columns. It is optional, but highly recommended, to give the sequence itself an externalId. For columns, an externalId is required, and we recommend that you also specify a valueType.

This example request creates a sequence:

POST /api/v1/projects/publicdata/sequences
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
content-length: 999

{
    "items": [
        {
            "externalId": "XV_123/performance_curve",
            "name": "performance curve XV_123",
            "description": "Performance curve for the so-and-so compressor",
            "metadata": 
                {
                    "source": "unliberated data store 42"
                },
            "assetId": 4324823473421,
            "columns": [
                {
                    "externalId": "load",
                    "valueType": "DOUBLE",
                    "metadata": {"unit": "kPa"}
                },
                {
                    "externalId": "performance",
                    "valueType": "LONG",
                    "description": "expected performance as % of maximum",
                    "metadata": {
                        "unit": "%",
                        "some other field": "some value"
                    }
                },
                {
                    "externalId": "quality",
                    "valueType": "STRING",
                    "name": "optional human readable name"
                }                
            ]
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

Add rows to a sequence

To add rows to a sequence, you need to specify the id or externalId of the sequence, along with a list of the columns you are inserting data into.

For example, to insert two rows in the sequence created in the previous example, use:

POST /api/v1/projects/publicdata/sequences/data
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
content-length: 999

{
    "items": [
        {
            "externalId": "XV_123/performance_curve",
            "columns": ["load","performance","quality"],
            "rows": [ 
                    {"rowNumber":1, "values":[123.45, 80, "POOR"] }
                    {"rowNumber":2, "values":[20.1, 95, "GOOD"] }
            ]
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Retrieve rows from a sequence

To get the rows from a sequence, you can use the externalId or the id of the sequence. Optionally, you can specify the columns you want to retrieve. The default is to return all columns.

For example, to get the first 5 rows from a sequence by using the externalId, in this case performance_curve, use the request:

POST /api/v1/projects/publicdata/sequences/data/list
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
content-length: 999

{
    "limit": 5,
    "externalId": "example",
    "start": 0,
    "end": 5
}
1
2
3
4
5
6
7
8
9
10
11
12

Note: end is exclusive. Even if you specify a higher limit, the request returns a maximum of five rows.

Note: Unlike the endpoints for creating sequences and inserting rows, you can only request rows from a single sequence here.

The response will look similar to this:

{
    "externalId": "example",
    "id": 7137123130454053,
    "columns": [
        {
            "externalId": "load",
            "valueType":"DOUBLE"
        },
        {
            "externalId": "performance",
            "valueType":"LONG"
        }
    ],
    "rows": [
        {
            "rowNumber": 1,
            "values": [0.0, 100]
        },
        {
            "rowNumber": 2,
            "values": [10.0, 95]
        },
        {
            "rowNumber": 3,
            "values": [20.0, 92]
        },
        {
            "rowNumber": 4,
            "values": [25.0, 85]
        },
        {
            "rowNumber": 5,
            "values": [30.0, 65]
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

Paginate retrieved rows

When you get a large number of rows, you can use cursors to paginate through the results.

For example, to get a single specific column from all rows with row numbers between 0 and 999999, use the request:

POST /api/v1/projects/publicdata/sequences/data/list
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
content-length: 999

{
    "limit": 10000,
    "externalId": "big_example",
    "start": 0,
    "end": 1000000,
    "columns": ["performance"],
    "cursor": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Note: 10000 is the maximum limit per request.

The response will look similar to this:

{
    "externalId": "big_example",
    "id": 21312313130454053,
    "columns": [
        {
            "externalId": "performance",
            "valueType":"LONG"
        }
    ],
    "rows": [
        {
            "rowNumber": 0,
            "values": [100]
        },
        {
            "rowNumber": 1,
            "values": [99]
        },
        <9997 rows ommitted>,
        {
            "rowNumber": 9999,
            "values": [42]
        }
    ],
    "nextCursor": "3zZmOn50qL9Kkhjwmrz602sHfQifGypzdqYEtQG3ajuU" 
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

To retrieve the next 10000 rows, pass the same request with the cursor field changed to the value returned in nextCursor.

Last Updated: 10/2/2019, 5:06:57 PM