SDS data query methods

When using SDS data operations to query data from a stream, you can query for data in stream using different query options based upon the operation type. The following table lists the available query options and the operations that they can be used with.

Find distinct value

Returns a stored data point based on the specified index and searchMode.

Find distinct value request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data?index={index}&searchMode={searchMode}

Find distinct value parameters

The following parameters must be defined when querying an SDS stream for a distinct data point.

string index
The index.

string searchMode
The SdsSearchMode. The default is exact.

Find distinct value response

The response includes a status code and a response body containing a serialized collection with one data point.

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T14:00:00Z",
        "State": 0,
        "Measurement": 20
    }
]

Depending on the request index and searchMode, it is possible to have an empty collection returned.

Filtered

Returns a collection of stored data points as determined by a filter. The filter limits results by applying an expression against data point fields. Filter expressions are explained in detail in the Filter expressions section.

Filtered request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data?filter={filter}

Filtered parameters

string filter
Filter expression (see Filter expressions).

Filtered response

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T14:00:00Z",
        "Measurement": 20
    },
    {
        "Time": "2017-11-23T15:00:00Z",
        "Measurement": 30
    },
    {
        "Time": "2017-11-23T16:00:00Z",
        "Measurement": 40
    }
]

Note that State is not included in the JSON as its value is the default value.

Filtered examples

In the following request example, the data points in the stream with Measurement greater than 10 are returned.

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data?filter=Measurement gt 10

The response returns stream data points with a Measurement greater than 10.

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T14:00:00Z",
        "Measurement": 20
    },
    {
        "Time": "2017-11-23T15:00:00Z",
        "Measurement": 30
    },
    {
        "Time": "2017-11-23T16:00:00Z",
        "Measurement": 40
    }
]

Index collection

Returns data points at the specified indexes. If no stored data point exists at a specified index, the stream's read characteristics determine how the returned data point is calculated. For more information, see Interpolation and Extrapolation.

Index collection request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data/Interpolated?index={index}[&index={index}...]

Index collection parameters

string index
One or more indexes.

Index collection examples

Simple stream with continuous interpolation and extrapolation

Consider a stream of type Simple with the default InterpolationMode of Continuous and ExtrapolationMode of All. In the following request, the specified index matches an existing stored data point:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data/Interpolated?index=2017-11-23T13:00:00Z

The response will contain the data point stored at the specified index.

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T13:00:00Z",
        "State": 0,
        "Measurement": 10
    }
]

Simple stream with an index with no stored data point

The following request specifies an index for which no stored data point exists:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data/Interpolated?index=2017-11-23T13:30:00Z

Because the index is a valid type for interpolation and the stream has a InterpolationMode of Continuous, this request receives a response with a data point interpolated at the specified index:

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T13:30:00Z",
        "State": 0,
        "Measurement": 15
    }
]

Simple stream with discrete interpolation

Consider a stream of type Simple with an InterpolationMode of Discrete and ExtrapolationMode of All. In the following request, the specified indexes only match two existing stored data points:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data/Interpolated?index=2017-11-23T12:30:00Z&index=2017-11-23T13:00:00Z&index=2017-11-23T14:00:00Z

For this request, the response contains data points for two of the three specified indexes.

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T13:00:00Z",
        "State": 0,
        "Measurement": 10
    },
    {
        "Time": "2017-11-23T14:00:00Z",
        "State": 0,
        "Measurement": 20
    }
]

Interval

Returns data points at evenly spaced intervals based on the specified startIndex, endIndex, and count. If no stored data point exists at an index interval, the stream's read characteristics determine how the returned data point is calculated. For more information, see Interpolation and Extrapolation.

Interval request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data/Interpolated?startIndex={startIndex}&endIndex={endIndex}&count={count}

Interval parameters

string startIndex
The index defining the beginning of the window.

string endIndex
The index defining the end of the window.

int count
The number of data points to return. Read characteristics of the stream determine how the data points are constructed.

Interval response

A serialized collection of data points is returned with evenly spaced intervals as defined in the request.

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T13:00:00Z",
        "State": 0,
        "Measurement": 10
    },
    {
        "Time": "2017-11-23T14:00:00Z",
        "State": 0,
        "Measurement": 20
    },
    {
        "Time": "2017-11-23T15:00:00Z",
        "State": 0,
        "Measurement": 30
    }
]

Range

Returns a collection of stored data points as determined by a startIndex and count. Additional optional parameters specify the direction of the range, how to handle data points near or at the start index, whether to skip a certain number of data points at the start of the range, and how to filter the data.

Range request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data?startIndex={startIndex}&count={count}[&skip={skip}&reversed={reversed}&boundaryType={boundaryType}&filter={filter}]

Range parameters

string startIndex
Index identifying the beginning of the series of data points to return.

int count
The number of data points to return.

int skip
Optional value specifying the number of data points to skip at the beginning of the result.

bool reversed
Optional specification of the direction of the request. By default, range requests move forward from startIndex, collecting data points after startIndex from the stream. A reversed request will collect data points before startIndex from the stream.

SdsBoundaryType boundaryType
Optional parameter that specifies the handling of data points at or near startIndex.

string filter
Optional filter expression.

Range response

The response includes a status code and a response body containing a serialized collection of data points.

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T13:00:00Z",
        "Measurement": 10
    },
    {
        "Time": "2017-11-23T14:00:00Z",
        "Measurement": 20
    },
    {
        "Time": "2017-11-23T15:00:00Z",
        "Measurement": 30
    },
    {
        "Time": "2017-11-23T16:00:00Z",
        "Measurement": 40
    }
]

Note that State is not included in the JSON as its value is the default value.

Range examples

Range of 100 data points extending forward

This request will return a response with up to 100 data points starting at 13:00 and extending forward toward the end of the stream:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data?startIndex=2017-11-23T13:00:00Z&count=100

The response returns the range of data points starting from the startIndex timestamp. The response has its returned data points truncated for brevity.

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T13:00:00Z",
        "Measurement": 10
    },
    {
        "Time": "2017-11-23T14:00:00Z",
        "Measurement": 10
    },
    ...
]

Note that State is not included in the JSON as its value is the default value. Further, Measurement is not included in the second data point, 12:00:00, as zero is the default value for numbers.

Range of 100 data points reversed

The following request specifies a boundary type of outside for a reversed-direction range request. The response will contain up to 100 data points. The boundary type Outside indicates that up to one data point outside the boundary will be included in the response. For a reverse direction range request, this means one data point forward of the specified start index. In a default direction range request, it would mean one data point before the specified start index.

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data?startIndex=2017-11-23T13:00:00Z&count=100&reversed=true&boundaryType=2

The response returns the 100 data points after the start index. The data point outside of the index is the next data point, or the data point at 14:00, because the request operates in reverse.

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T14:00:00Z",
        "State": 0,
        "Measurement": 20
    },
    {
        "Time": "2017-11-23T13:00:00Z",
        "State": 0,
        "Measurement": 10
    },
    {
        "Time": "2017-11-23T12:00:00Z",
        "State": 0,
        "Measurement": 0
    }
]

Range with filter

Adding a filter to the request means only data points that meet the filter criteria are returned:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data?startIndex=2017-11-23T13:00:00Z&count=100&reversed=true&boundaryType=2&filter=Measurement gt 10

The range and order is still in effect, but only data points that meet the filter criteria are included.

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T14:00:00Z",
        "State": 0,
        "Measurement": 20
    }
]

Window

Returns a collection of stored data points based on the specified startIndex and endIndex.

For handling data points at and near the boundaries of the window, a single SdsBoundaryType that applies to both the start and end indexes can be passed with the request, or separate boundary types may be passed for the start and end individually.

Paging is supported for window requests with a large number of data points.

To retrieve the next page of data points, include the continuationToken from the results of the previous request. For the first request, specify a null or empty string for the continuationToken.

Window requests

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data?startIndex={startIndex}&endIndex={endIndex}

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data?startIndex={startIndex}&endIndex={endIndex}&boundaryType={boundaryType}

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data?startIndex={startIndex}&startBoundaryType={startBoundaryType}&endIndex={endIndex}&endBoundaryType={endBoundaryType}

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data?startIndex={startIndex}&endIndex={endIndex}&count={count}&continuationToken={continuationToken}

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data?startIndex={startIndex}&startBoundaryType={startBoundaryType}&endIndex={endIndex}&endBoundaryType={endBoundaryType}&filter={filter}&count={count}&continuationToken={continuationToken}

Window parameters

string startIndex
Index bounding the beginning of the series of data points to return

string endIndex
Index bounding the end of the series of data points to return

int count
Optional maximum number of data points to return. If count is specified, a continuationToken must also be specified.

SdsBoundaryType boundaryType
Optional SdsBoundaryType specifies handling of data points at or near the start and end indexes

SdsBoundaryType startBoundaryType
Optional SdsBoundaryType specifies the first data point in the result in relation to the start index. If startBoundaryType is specified, endBoundaryType must be specified.

SdsBoundaryType endBoundaryType
Optional SdsBoundaryType specifies the last data point in the result in relation to the end index. If startBoundaryType is specified, endBoundaryType must be specified.

string filter
Optional filter expression

string continuationToken
Optional token used to retrieve the next page of data. If count is specified, a continuationToken must also be specified.

Window response

The response includes a status code and a response body containing a serialized collection of data points.

A continuation token can be returned if specified in the request.

Window examples

Window of data points between two timestamps

The following request returns all stored data points between 12:30 and 15:30:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data?startIndex=2017-11-23T12:30:00Z&endIndex=2017-11-23T15:30:00Z

The response will contain the data points stored within the specified range:

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T13:00:00Z",
        "Measurement": 10
    },
    {
        "Time": "2017-11-23T14:00:00Z",
        "Measurement": 20
    },
    {
        "Time": "2017-11-23T15:00:00Z",
        "Measurement": 30
    }
]

Note that State is not included in the JSON as its value is the default value.

Window of data points between two timestamps with a boundary of Outside

When the request is modified to specify a boundary type of Outside, the data point before 13:30 and the data point after 15:30 are included:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data?startIndex=2017-11-23T12:30:00Z&endIndex=2017-11-23T15:30:00Z&boundaryType=2

The response includes the windowed data points, as well as the two data points outside of the startIndex and endIndex.

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T12:00:00Z"
    },
    {
        "Time": "2017-11-23T13:00:00Z",
        "Measurement": 10
    },
    {
        "Time": "2017-11-23T14:00:00Z",
        "Measurement": 20
    },
    {
        "Time": "2017-11-23T15:00:00Z",
        "Measurement": 30
    },
    {
        "Time": "2017-11-23T16:00:00Z",
        "Measurement": 40
    }
]

Note that State is not included in the JSON as its value is the default value.

Further, Measurement is not included in the second data point (12:00:00) because zero is the default value for numbers.

Window of data points between two timestamps with mixed boundaries

With a startBoundary of Inside, only data points inside the start boundary (after 13:30) are included in the result. With an end boundary of Outside, one data point outside the end index (after 15:30) is included:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data?startIndex=2017-11-23T12:30:00Z&&startBoundaryType=1&endIndex=2017-11-23T15:30:00Z&endBoundaryType=2

Example response:

HTTP/1.1 200
Content-Type: application/json

[
    {
        "Time": "2017-11-23T13:00:00Z",
        "State": 0,
        "Measurement": 10
    },
    {
        "Time": "2017-11-23T14:00:00Z",
        "State": 0,
        "Measurement": 20
    },
    {
        "Time": "2017-11-23T15:00:00Z",
        "State": 0,
        "Measurement": 30
    },
    {
        "Time": "2017-11-23T16:00:00Z",
        "State": 0,
        "Measurement": 40
    }
]

Pagination

To page the results of the request, a continuationToken may be specified. This requests the first page of the first two stored data points between startIndex and endIndex by indicating count is 2 and continuationToken is an empty string

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data?startIndex=2017-11-23T12:30:00Z&endIndex=2017-11-23T15:30:00Z&count=2&continuationToken=

Response:

HTTP/1.1 200
Content-Type: application/json

{
    "Results": [
        {
            "Time": "2017-11-23T13:00:00Z",
            "State": 0,
            "Measurement": 10
        },
        {
            "Time": "2017-11-23T14:00:00Z",
            "State": 0,
            "Measurement": 20
        }
    ],
    "ContinuationToken": "2017-11-23T14:00:00.0000000Z"
}

Pagination with ContinuationToken

This request uses the continuation token from the previous page to request the next page of stored data points:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data?startIndex=2017-11-23T12:30:00Z&endIndex=2017-11-23T15:30:00Z&count=2&continuationToken=2017-11-23T14:00:00Z

Response:

HTTP/1.1 200
Content-Type: application/json

{
    "Results": [
        {
            "Time": "2017-11-23T15:00:00Z",
            "State": 0,
            "Measurement": 30
        }
    ],
    "ContinuationToken": null
}

In this case, the results contain the final data point. The returned continuation token is null.