Read data API

The following example API calls show different methods for reading data.

Example type, stream, and data

Many of the API methods described below contain example requests and responses in JSON to highlight usage and specific behaviors. The following type, stream, and data are used in the examples:

Example type
SimpleType is an SdsType with a single index. This type is defined in Python and Javascript:

public enum State

{

Ok,

Warning,

Alarm

}

public class SimpleType

{

[SdsMember(IsKey = true, Order = 0) ]

public DateTime Time { get; set; }

public State State { get; set; }

[SdsMember(Uom = "meter")]

public Double Measurement { get; set; }

}

class State(Enum):

Ok = 0

Warning = 1

Alarm = 2

class SimpleType(object):

Time = property(getTime, setTime)

def getTime(self):

return self.__time

def setTime(self, time):

self.__time = time

State = property(getState, setState)

def getState(self):

return self.__state

def setState(self, state):

self.__state = state

Measurement = property(getValue, setValue)

def getValue(self):

return self.__measurement

def setValue(self, measurement):

self.__measurement = measurement

var State =

{

Ok: 0,

Warning: 1,

Alarm: 2,

}

var SimpleType = function () {

this.Time = null;

this.State = null;

this.Value = null;

}

Example Stream
Simple is an SdsStream of type SimpleType.

Example Data
Simple has stored values as follows:

11/23/2017 12:00:00 PM: Ok 0

11/23/2017 1:00:00 PM: Ok 10

11/23/2017 2:00:00 PM: Ok 20

11/23/2017 3:00:00 PM: Ok 30

11/23/2017 4:00:00 PM: Ok 40

All times are represented at offset 0, GMT.

Get First Value

Returns the first value in the stream. If no values exist in the stream, null is returned

Request

GET /api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data/First

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

string streamId
Stream identifier.

Response

Example response body

400 Response (ErrorResponseBody)

{

"OperationId": "string",

"Error": "string",

"Reason": "string",

"Resolution": "string",

"Parameters": {

"property1": "string",

"property2": "string"

}

}

Get Last Value

Returns the last value in the stream. If no values exist in the stream, null is returned.

Request

GET /api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data/Last

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

string streamId
Stream identifier.

Response

Example response body

400 Response (ErrorResponseBody)

{

"OperationId": "string",

"Error": "string",

"Reason": "string",

"Resolution": "string",

"Parameters": {

"property1": "string",

"property2": "string"

}

}

Find Distinct Value

Returns a stored event based on the specified index and searchMode

Request

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

Parameters

string tenantId
Tenant identifier

string namespaceId
Namespace identifier

string streamId
Stream identifier

string index
The index

string searchMode
The Read data, the default is exact

Response

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

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

Example request

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

The request has an index that matches the index of an existing event, but since a SdsSearchMode of next was specified, the response contains the next event in the stream after the specified index:

Example response body

HTTP/1.1 200

Content-Type: application/json

[

{

"Time": "2017-11-23T14:00:00Z",

"State": 0,

"Measurement": 20

}

]

Example request

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

The request specifies an index that does not match an index of an existing event. The next event in the stream is retrieved.

Example response body

HTTP/1.1 200

Content-Type: application/json

[

{

"Time": "2017-11-23T14:00:00Z",

"State": 0,

"Measurement": 20

}

]

List Values

Returns a collection of stored values at indexes based on request parameters

SDS supports three ways of specifying which stored events to return:

• Read data API: A filtered request accepts a Filter expressions.

• Read data API: A range request accepts a start index and a count.

• Read data API: A window request accepts a start index and end index. This request has an optional continuation token for large collections of events.

Filtered

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

Request

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

Parameters

string tenantId
Tenant identifier

string namespaceId
Namespace identifier

string streamId
Stream identifier

string filter
Filter expression (see Filter expressions)

Response

Example request

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

The events in the stream with Measurement greater than 10 are returned.

Example response body

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.

Range

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

Request

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

Parameters

string tenantId
Tenant identifier

string namespaceId
Namespace identifier

string streamId
Stream identifier

string startIndex
Index identifying the beginning of the series of events to return

int count
The number of events to return

int skip
Optional value specifying the number of events 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 events after startIndex from the stream. A reversed request collects events before startIndex from the stream.

SdsBoundaryType boundaryType
Optional SdsBoundaryType specifies the handling of events at or near startIndex

string filter
Optional filter expression

Response

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

Example request

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

This request returns a response with up to 100 events starting at 13:00 and extending forward toward the end of the stream:

Example response body

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.

Example request

To reverse the direction of the request, set reversed to true. The following request returns up to 100 events starting at 13:00 and extending back toward the start of the stream:

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

Example response body

HTTP/1.1 200

Content-Type: application/json

[

{

"Time": "2017-11-23T13:00:00Z",

"Measurement": 10

},

{

"Time": "2017-11-23T12:00:00Z"

}

]

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

Further, Measurement is not included in the second, 12:00:00, event as zero is the default value for numbers.

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

Example request

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

Example response body

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

}

]

The event outside of the index is the next event or the event at 14:00 because the request operates in reverse.

Example request

Adding a filter to the request means only events 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

Example response body

HTTP/1.1 200

Content-Type: application/json

[

{

"Time": "2017-11-23T14:00:00Z",

"State": 0,

"Measurement": 20

}

]

Window

Returns a collection of stored events based on the specified startIndex and endIndex

For handling events 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 events.

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

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}

Parameters

string tenantId
Tenant identifier

string namespaceId
Namespace identifier

string streamId
Stream identifier

string startIndex
Index bounding the beginning of the series of events to return

string endIndex
Index bounding the end of the series of events to return

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

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

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

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

string filter
Optional Filter expressions

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

Response

The response includes a status code and a response body containing a serialized collection of events. A continuation token can be returned if specified in the request.

Example request

The following requests all stored events 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 event stored at the specified index:

Example response body

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.

Example request

When the request is modified to specify a boundary type of Outside, the value before 13:30 and the value 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

Example response body

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 event (12:00:00) as zero is the default value for numbers.

Example request

With a start boundary of Inside, only values inside the start boundary (after 13:30) are included in the result. With an end boundary of Outside, one value 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 body

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

}

]

Example request

In order to page the results of the request, a continuation token may be specified. This requests the first page of the first two stored events between start index and end index 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=

Example response body

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"

}

Example request

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

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

Example response body

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 event. The returned continuation token is null.

List Interpolated Values

Returns a collection of values based on request parameters. The stream's read characteristics determine how events are calculated for indexes at which no stored event exists. For more information, see Read characteristics and Read characteristics. Interpolation is not supported for streams with compound indexes.

SDS supports two ways of specifying which interpolated events to return:

• Read data API: One or more indexes can be passed to the request in order to retrieve events at specific indexes.

• Read data API: An interval can be specified with a start index, end index, and count. This will return the specified count of events evenly spaced from start index to end index.

Index collection

Returns events at the specified indexes. If no stored event exists at a specified index, the stream's read characteristics determine how the returned event is calculated. For more information, see Read characteristics and Read characteristics.

Request

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

Parameters

string tenantId
Tenant identifier

string namespaceId
Namespace identifier

string streamId
Stream identifier.

string index
One or more indexes

Response

Example request

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 event:

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

The response will contain the event stored at the specified index.

Example response body

HTTP/1.1 200 Content-Type: application/json [ { "Time": "2017-11-23T13:00:00Z", "State": 0, "Measurement": 10 } HTTP/1.1 200

Content-Type: application/json

[

{

"Time": "2017-11-23T13:00:00Z",

"State": 0,

"Measurement": 10

}

]

Example request

The following request specifies an index for which no stored event 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 an event interpolated at the specified index:

Example response body

HTTP/1.1 200

Content-Type: application/json

[

{

"Time": "2017-11-23T13:30:00Z",

"State": 0,

"Measurement": 15

}

]

Example request

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 events:

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 events for two of the three specified indexes.

Example response body

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 events at evenly spaced intervals based on the specified start index, end index, and count. If no stored event exists at an index interval, the stream's read characteristics determine how the returned event is calculated. For more information, see Read characteristics and Read characteristics.

Request

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

Parameters

string tenantId
Tenant identifier

string namespaceId
Namespace identifier

string streamId
Stream identifier

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 events to return. Read characteristics of the stream determine how the events are constructed.

Response

Example request

For a stream, named Simple, of type Simple for the following request:

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

the start and end fall exactly on event indexes, and the number of events from start to end match the count of three (3).

Example response body

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

}

]

Get Summaries

Returns summary intervals between a specified start and end index.

Index types that cannot be interpolated do not support summary requests. Strings are an example of indexes that cannot be interpolated. Summaries are not supported for streams with compound indexes. Interpolating between two indexes that consist of multiple properties is not defined and results in non-determinant behavior.

Summary values supported by SdsSummaryType enum:

Count, Minimum, Maximum, and Range are based only on stored events and do not include interpolated values. Mean, Standard Deviation, Skewness, and Kurtosis are event-weighted calculations. Total, Weighted Mean, WeightedStandardDeviation, and WeightedPopulationStandardDeviation are index-weighted calculations.

Currently, these values can only be calculated for properties of the following types:

Note: Properties marked with an InterpolationMode of Discrete do not support summaries. Unsupported properties will be excluded from the summaries returned.

Request

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

Parameters

string tenantId
Tenant identifier

string namespaceId
Namespace identifier

string streamId
Stream identifier

string startIndex
The start index for the intervals

string endIndex
The end index for the intervals

int count
The number of intervals requested

string filter
Optional filter expression

Response

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

Each SdsInterval has a start, end, and collection of summary values.

Example request

The following request calculates two summary intervals between the startIndex and endIndex:

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

Example response body

HTTP/1.1 200

Content-Type: application/json

[

{

"Start": {

"Time": "2017-11-23T12:00:00Z",

"State": 0,

"Measurement": 0

},

"End": {

"Time": "2017-11-23T14:00:00Z",

"State": 0,

"Measurement": 20

},

"Summaries": {

"Count": {

"Time": 3,

"Measurement": 3

},

"Minimum": {

"Measurement": 0

},

"Maximum": {

"Measurement": 20

},

"Range": {

"Measurement": 20

},

"Total": {

"Measurement": 20

},

"Mean": {

"Measurement": 10

},

"StandardDeviation": {

"Measurement": 7.0710678118654755

},

"PopulationStandardDeviation": {

"Measurement": 5

},

"WeightedMean": {

"Measurement": 10

},

"WeightedStandardDeviation": {

"Measurement": 7.0710678118654755

},

"WeightedPopulationStandardDeviation": {

"Measurement": 5

},

"Skewness": {

"Measurement": 0

},

"Kurtosis": {

"Measurement": -2

}

}

},

{

"Start": {

"Time": "2017-11-23T14:00:00Z",

"State": 0,

"Measurement": 20

},

"End": {

"Time": "2017-11-23T16:00:00Z",

"State": 0,

"Measurement": 40

},

"Summaries": {

"Count": {

"Time": 3,

"Measurement": 3

},

"Minimum": {

"Measurement": 30

},

"Maximum": {

"Measurement": 40

},

"Range": {

"Measurement": 10

},

"Total": {

"Measurement": 60

},

"Mean": {

"Measurement": 30

},

"StandardDeviation": {

"Measurement": 7.0710678118654755

},

"PopulationStandardDeviation": {

"Measurement": 5

},

"WeightedMean": {

"Measurement": 30

},

"WeightedStandardDeviation": {

"Measurement": 7.0710678118654755

},

"WeightedPopulationStandardDeviation": {

"Measurement": 5

},

"Skewness": {

"Measurement": 0

},

"Kurtosis": {

"Measurement": -2

}

}

}

]

SDS also supports summary requests for nullable SdsTypes. It means an SdsType has at least a nullable SdsTypeProperty.

Example

The following example contains a nullable double property with interpolation mode set to continuous:

.NET

public class SimpleType

{

[SdsMember(IsKey = true, Order = 0) ]

public DateTime Time { get; set; }

[SdsMember(Uom = "meter")]

public double? Measurement { get; set; }

}

Measurement has stored values as follows:

11/23/2017 12:00:01 PM: Measurement 2

11/23/2017 12:00:02 PM: Measurement 2

11/23/2017 12:00:03 PM: Measurement null

11/23/2017 12:00:04 PM: Measurement 1

11/23/2017 12:00:05 PM: Measurement 2

11/23/2017 12:00:06 PM: Measurement null

11/23/2017 12:00:07 PM: Measurement null

11/23/2017 12:00:08 PM: Measurement 3

While calculating weighted summaries, if we encounter a null value at a given index then we would consider interpolation mode of property to find the interpolated value of the given interval. See the table below for [12:00:02 PM, 12:00:03 PM] interval. The values are 2 and null at 12:00:02 and 12:00:03 PM respectively.

Similarly, for intervals [12:00:03 PM, 12:00:04 PM] and [12:00:04 PM, 12:00:05 PM] respectively, the table would look like below:

Note: Non-weighted summaries disregard null values and treat them as non-existent. In the example above, non-weighted summaries for Measurement would be calculated based on (2,2,1,2,3) whereas weighted summaries for Measurement consider null values for its calculation. For more information see Read characteristics.

Example request

The following request calculates one summary interval between the startIndex and endIndex:

GET api/v1-preview/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data/Summaries?startIndex=2017-11-23T12:00:01Z&endIndex=2017-11-23T12:00:08Z&count=1

Example response body

HTTP/1.1 200

Content-Type: application/json

[

{

"Start": {

"Time": "2017-11-23T12:00:01Z",

"Measurement": 2

},

"End": {

"Time": "2017-11-23T12:00:08Z",

"Measurement": 3

},

"Summaries": {

"Count": {

"Time": 8,

"Measurement": 5

},

"Minimum": {

"Measurement": 1

},

"Maximum": {

"Measurement": 3

},

"Range": {

"Measurement": 2

},

"Total": {

"Measurement": 7.5

},

"Mean": {

"Measurement": 1.875

},

"StandardDeviation": {

"Measurement": 0.478713553878169

},

"PopulationStandardDeviation": {

"Measurement": 0.41457809879442492

},

"WeightedMean": {

"Measurement": 1.75

},

"WeightedStandardDeviation": {

"Measurement": 0.35355339059327379

},

"WeightedPopulationStandardDeviation": {

"Measurement": 0.25

},

"Skewness": {

"Measurement": 0.49338220021815865

},

"Kurtosis": {

"Measurement": -1.3719008264462809

}

}

}

]

Get Sampled Values

Returns representative data sampled by intervals between a specified start and end index.

Sampling is driven by a specified property or properties of the stream's Sds Type. Property types that cannot be interpolated do not support sampling requests. Strings are an example of a property that cannot be interpolated. For more information see Read characteristics.

Request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data/Sampled?startIndex={startIndex}&endIndex={endIndex}&intervals={intervals}&sampleBy={sampleBy}[&sampleBy={sampleBy}&...&boundaryType={boundaryType}&startBoundaryType={startBoundaryType} &endBoundaryType={endBoundaryType}&filter={filter}]

Parameters

string tenantId
Tenant identifier

string namespaceId
Namespace identifier

string streamId
Stream identifier

string startIndex
The start index for the intervals

string endIndex
The end index for the intervals

int intervals
The number of intervals requested

string sampleBy
Property or properties to use when sampling

SdsBoundaryType boundaryType
Optional SdsBoundaryType specifies the handling of events at or near the startIndex and endIndex

SdsBoundaryType startBoundaryType
Optional SdsBoundaryType specifies the handling of events at or near the startIndex

SdsBoundaryType endBoundaryType
Optional SdsBoundaryType specifies the handling of events at or near the endIndex

string filter
Optional filter expression

Response

Example request

The following request returns two sample intervals between the startIndex and endIndex:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/Simple/Data/Sampled?startIndex=2019-01-01T00:00:00Z&endIndex=2019-01-02T00:00:00Z&intervals=2&sampleBy=Measurement

Example response body

HTTP/1.1 200

Content-Type: application/json

[

{

"Time": "2019-01-01T00:00:01Z",

"State": 1,

"Measurement": 1

},

{

"Time": "2019-01-01T00:11:50Z",

"State": 2,

"Measurement": 0.00006028870675578446

},

{

"Time": "2019-01-01T11:55:33Z",

"Measurement": 6.277981349066863

},

{

"Time": "2019-01-01T12:00:00Z",

"Measurement": 3.101013140344655

},

{

"Time": "2019-01-01T12:00:01Z",

"State": 1,

"Measurement": 4.101013140344655

},

{

"Time": "2019-01-01T12:01:50Z",

"State": 2,

"Measurement": 0.0036776111121028521

},

{

"Time": "2019-01-01T23:57:23Z",

"State": 2,

"Measurement": 6.2816589601789659

},

{

"Time": "2019-01-02T00:00:00Z",

"Measurement": 6.20202628068931

}

]

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

400 Response (ErrorResponseBody)

{

"OperationId": "string",

"Error": "string",

"Reason": "string",

"Resolution": "string",

"Parameters": {

"property1": "string",

"property2": "string"

}

}

Join Values

Returns data from multiple streams, which are joined based on the request specifications. The streams must be of the same type.

SDS supports the following types of joins:

SDS supports GET and POST join requests:

• Read data API: The stream, joinMode, start index, and end index are specified in the request URI path.

• Read data API: Only the joinMode is specified in the URI. The streams and read specification for each stream are specified in the body of the request.

GET request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Bulk/Streams/Data/Joins?streams={streams}&joinMode={joinMode}&startIndex={startIndex}&endIndex={endIndex}[&boundaryType={boundaryType}&startBoundaryType={startBoundaryType}&endBoundaryType={endBoundaryType}&filter={filter}&count={count}]

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier

string streams
Commas separated list of stream identifiers

SdsJoinMode joinMode
Type of join: inner, outer, interpolated, merge left or merge right

string startIndex
Index identifying the beginning of the series of events to return

string endIndex
Index identifying the end of the series of events to return

[Optional] int count
Maximum number of events to return

[Optional] SdsBoundaryType boundaryType
SdsBoundaryType specifies the handling of events at or near the startIndex and endIndex

[Optional] SdsBoundaryType startBoundaryType
SdsBoundaryType specifies the handling of events at or near the startIndex

[Optional] SdsBoundaryType endBoundaryType
SdsBoundaryType specifies the handling of events at or near the endIndex

[Optional] string filter
Filter expression

Response

Examples

Data from streams Simple1 and Simple2 will be used to illustrate how each join operation works.

Stream data Simple1

HTTP/1.1 200

Content-Type: application/json

[

{

"Time": "2017-11-23T11:00:00Z",

"Measurement": 10

},

{

"Time": "2017-11-23T13:00:00Z",

"Measurement": 20

},

{

"Time": "2017-11-23T14:00:00Z",

"Measurement": 30

},

{

"Time": "2017-11-23T16:00:00Z",

"Measurement": 40

}

]

Stream data Simple2

HTTP/1.1 200

Content-Type: application/json

[

{

"Time": "2017-11-23T12:00:00Z",

"Measurement": 50

},

{

"Time": "2017-11-23T14:00:00Z",

"Measurement": 60

},

{

"Time": "2017-11-23T15:00:00Z",

"Measurement": 70

},

{

"Time": "2017-11-23T17:00:00Z",

"Measurement": 80

}

]

Inner Join example request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Bulk/Streams/Data/Joins?streams=Simple1,Simple2&joinMode=inner&startIndex=0001-01-01T00:00:00.0000000&endIndex=9999-12-31T23:59:59.9999999

Response

Measurements from both streams with common indexes.

Example response body

HTTP/1.1 200

Content-Type: application/json

[

[

{

"Time": "2017-11-23T14:00:00Z",

"Measurement": 30

},

{

"Time": "2017-11-23T14:00:00Z",

"Measurement": 60

}

]

]

Outer Join example request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Bulk/Streams/Data/Joins?streams=Simple1,Simple2&joinMode=outer&startIndex=0001-01-01T00:00:00.0000000&endIndex=9999-12-31T23:59:59.9999999

Response

All Measurements from both streams, with default values at indexes where a stream does not have a value.

Example response body

HTTP/1.1 200

Content-Type: application/json

[

[

{

"Time": "2017-11-23T11:00:00Z",

"Measurement": 10

},

null

],

[

null,

{

"Time": "2017-11-23T12:00:00Z",

"Measurement": 50

}

],

[

{

"Time": "2017-11-23T13:00:00Z",

"Measurement": 20

},

null

],

[

{

"Time": "2017-11-23T14:00:00Z",

"Measurement": 30

},

{

"Time": "2017-11-23T14:00:00Z",

"Measurement": 60

}

],

[

null,

{

"Time": "2017-11-23T15:00:00Z",

"Measurement": 70

}

],

[

{

"Time": "2017-11-23T16:00:00Z",

"Measurement": 40

},

null

],

[

null,

{

"Time": "2017-11-23T17:00:00Z",

"Measurement": 80

}

]

]

Default value is null for SdsTypes.

Interpolated Join example request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Bulk/Streams/Data/Joins?streams=Simple1,Simple2&joinMode=interpolated&startIndex=0001-01-01T00:00:00.0000000&endIndex=9999-12-31T23:59:59.9999999

Response

All Measurements from both streams with missing values interpolated. If the missing values are between valid measurements within a stream, they are interpolated. For more information, see Read characteristics. If the missing values are outside of the boundary values, they are extrapolated. For more information, see Read characteristics.

Note: The Interpolated SdsJoinMode currently does not support SdsInterpolationModes of the streams. All join requests with interpolations will honor the interpolation mode of the stream type or type property.

Example response body

HTTP/1.1 200

Content-Type: application/json

[

[

{

"Time": "2017-11-23T11:00:00Z",

"Measurement": 10

},

{

"Time": "2017-11-23T11:00:00Z",

"Measurement": 50

}

],

[

{

"Time": "2017-11-23T12:00:00Z",

"Measurement": 15

},

{

"Time": "2017-11-23T12:00:00Z",

"Measurement": 50

}

],

[

{

"Time": "2017-11-23T13:00:00Z",

"Measurement": 20

},

{

"Time": "2017-11-23T13:00:00Z",

"Measurement": 55

}

],

[

{

"Time": "2017-11-23T14:00:00Z",

"Measurement": 30

},

{

"Time": "2017-11-23T14:00:00Z",

"Measurement": 60

}

],

[

{

"Time": "2017-11-23T15:00:00Z",

"Measurement": 35

},

{

"Time": "2017-11-23T15:00:00Z",

"Measurement": 70

}

],

[

{

"Time": "2017-11-23T16:00:00Z",

"Measurement": 40

},

{

"Time": "2017-11-23T16:00:00Z",

"Measurement": 75

}

],

[

{

"Time": "2017-11-23T17:00:00Z",

"Measurement": 40

},

{

"Time": "2017-11-23T17:00:00Z",

"Measurement": 80

}

]

]

Interpolated values are in bold. Extrapolated values are in italics.

MergeLeft Join example request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Bulk/Streams/Data/Joins?streams=Simple1,Simple2&joinMode=mergeleft&startIndex=0001-01-01T00:00:00.0000000&endIndex=9999-12-31T23:59:59.9999999

Response

Similar to OuterJoin, but value at each index is the first available value at that index when iterating the given list of streams from left to right.

Example response body

HTTP/1.1 200

Content-Type: application/json

[

{

"Time": "2017-11-23T11:00:00Z",

"Measurement": 10

},

{

"Time": "2017-11-23T12:00:00Z",

"Measurement": 50

},

{

"Time": "2017-11-23T13:00:00Z",

"Measurement": 20

},

{

"Time": "2017-11-23T14:00:00Z",

"Measurement": 30

},

{

"Time": "2017-11-23T15:00:00Z",

"Measurement": 70

},

{

"Time": "2017-11-23T16:00:00Z",

"Measurement": 40

},

{

"Time": "2017-11-23T17:00:00Z",

"Measurement": 80

}

]

Takes the value from the stream on the left (Simple1) at "2017-11-23T14:00:00Z".

MergeRight Join example request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Bulk/Streams/Data/Joins?streams=Simple1,Simple2&joinMode=mergeright&startIndex=0001-01-01T00:00:00.0000000&endIndex=9999-12-31T23:59:59.9999999

Response

Similar to OuterJoin, but value at each index is the first available value at that index when iterating the given list of streams from right to left.

Example response body

HTTP/1.1 200

Content-Type: application/json

[

{

"Time": "2017-11-23T11:00:00Z",

"Measurement": 10

},

{

"Time": "2017-11-23T12:00:00Z",

"Measurement": 50

},

{

"Time": "2017-11-23T13:00:00Z",

"Measurement": 20

},

{

"Time": "2017-11-23T14:00:00Z",

"Measurement": 60

},

{

"Time": "2017-11-23T15:00:00Z",

"Measurement": 70

},

{

"Time": "2017-11-23T16:00:00Z",

"Measurement": 40

},

{

"Time": "2017-11-23T17:00:00Z",

"Measurement": 80

}

]

Takes the value from the stream on the right (Simple2) at "2017-11-23T14:00:00Z".

POST request

POST api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Bulk/Streams/Data/Joins?joinMode={joinMode}

Parameters

string tenantId
Tenant identifier

string namespaceId
Namespace identifier

SdsJoinMode joinMode
Type of join: inner, outer, interpolated, merge left or merge right

Request body

Read option specific to each stream

Response

The response includes a status code and a response body containing multiple serialized events.

Outer Join example request

POST api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Bulk/Streams/Data/Joins?joinMode=outer

Outer Join example request body

Different start indexes and end indexes are specified per stream.

[

{

"StreamId": "Simple1",

"Options":

{

"StartIndex": "2017-11-23T11:00:00Z",

"EndIndex": "2017-11-23T14:00:00Z",

"StartBoundaryType": "Exact",

"EndBoundaryType": "Exact",

"Count": 100,

"Filter": ""

}

},

{

"StreamId": "Simple2",

"Options":

{

"StartIndex": "2017-11-23T15:00:00Z",

"EndIndex": "2017-11-23T17:00:00Z",

"StartBoundaryType": "Exact",

"EndBoundaryType": "Exact",

"Count": 100,

"Filter": ""

}

}

]

Outer Join example response body

Only events within the two streams' specified index boundaries are considered for the outer join operation.

HTTP/1.1 200

Content-Type: application/json

[

[

{

"Time": "2017-11-23T11:00:00Z",

"Measurement": 10

},

null

],

[

{

"Time": "2017-11-23T13:00:00Z",

"Measurement": 20

},

null

],

[

{

"Time": "2017-11-23T14:00:00Z",

"Measurement": 30

},

null

],

[

null,

{

"Time": "2017-11-23T15:00:00Z",

"Measurement": 70

}

],

[

null,

{

"Time": "2017-11-23T17:00:00Z",

"Measurement": 80

}

]

]

Not all values from both streams are included because the query restricts each stream. See Outer Join GET request above to compare.

Definitions

ErrorResponseBody

Contains the error message format that follows the CONNECT data services error standards

Properties

{

"OperationId": "string",

"Error": "string",

"Reason": "string",

"Resolution": "string",

"Parameters": {

"property1": "string",

"property2": "string"

}

}