Stream Data

The API in this section interacts with data from the specified streams.

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

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

List Values

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

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

• Find Distinct Value: Returns a stored event based on the specified index and searchMode.

  Parameters: Accepts index and searchMode.

• Filtered: Returns a collection of stored values as determined by a filter.The filter limits results by applying an expression against event fields.

  Parameters: Accepts a filter expression.

• 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.

  Parameters: Accepts startIndex and count.

• Window: Returns a collection of stored events based on the specified startIndex and endIndex.

  Parameters: Accepts startIndex and endIndex. This request has an optional continuation token for large collections of events.

Request

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

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

string streamId
Stream identifier.

[optional] string filter
Filter expression.

[optional] string startIndex
Index identifying the beginning of the series of events to return.

[optional] string endIndex
Index identifying the end of the series of events to return.

[optional] integer count
Parameter representing the maximum number of objects to retrieve. If unspecified, a default value of 100 is used.

[optional] string index
The index.

[optional] integer searchMode
The SdsSearchMode, type of search: Exact (the default), ExactOrNext, Next, ExactOrPrevious, or Previous.

[optional] integer skip
Parameter representing the zero-based offset of the first object to retrieve. If unspecified, a default value of 0 is used.

[optional] boolean reversed
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 will collect events before startIndex from the stream.

[optional] integer boundaryType
SdsBoundaryType specifying the handling of events at or near the start and end indexes.

[optional] integer startBoundaryType
SdsBoundaryType specifying the first value in the result in relation to the start index. If startBoundaryType is specified, endBoundaryType must be specified.

[optional] integer endBoundaryType
SdsBoundaryType specifies the last value in the result in relation to the end index. If startBoundaryType is specified, endBoundaryType must be specified.

[optional] string continuationToken
Token used to retrieve the next page of data. If count is specified, a continuationToken must also be specified.

Response

Example response body

200 Response

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

400 Response (ErrorResponseBody)

{
  "OperationId": "string",
  "Error": "string",
  "Reason": "string",
  "Resolution": "string",
  "Parameters": {
    "property1": "string",
    "property2": "string"
  }
}

Insert Values

Inserts data into the specified stream. Returns an error if data is already present at the index of any event.

Notes: This request will return an error if an event already exists for any index in the request. If any individual index encounters a problem, the entire operation is rolled back and no insertions are made. The streamId and index that caused the issue are included in the error response.

Request

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

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

string streamId
Stream identifier.

Response

Update Values

Writes one or more events to or over existing events the specified stream.

Notes: This request performs an insert or a replace depending on whether an event already exists at the event indexes. If any item fails to write, the entire operation is rolled back and no events are written to the stream. The index that caused the issue is included in the error response.

Request

PUT /api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data
?allowCreate={allowCreate}

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

string streamId
Stream identifier.

[optional] boolean allowCreate
If false, writes one or more events over existing events in the specified stream.

Response

Patch Values

Modifies the specified stream event(s). Patching affects only the data item parameters that are included in the call.

Notes: Patching is used to patch the events of the selected fields for one or more events in the stream. Only the fields indicated in selectExpression are modified. The events to be modified are indicated by the index value of each entry in the collection. If there is a problem patching any individual event, the entire operation is rolled back and the error will indicate the streamId and index of the problem.

Request

PATCH /api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data
?selectExpression={selectExpression}

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

string streamId
Stream identifier.

[optional] string selectExpression
Comma separated list of strings that indicates the event fields that will be changed in stream events.

Response

Remove Values

There are two options for specifying which events to remove from a stream: index collection and windows

Index Collection: Removes the event at each index from the specified stream. Different overloads are available to make it easier to indicate the index where you want to remove a data event. One or more indexes can be specified in the request.

Window: Removes events at and between the start index and end index. A window can be specified with a start index and end index.

Notes: If any individual event fails to be removed, the entire operation is rolled back and no events are removed. The streamId and index that caused the issue are included in the error response. If you attempt to remove events at indexes that have no events, an error is returned. If this occurs, use the Window request format to remove any events from a specified window of indexes, which will not return an error if no data is found.

Request

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

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

string streamId
Stream identifier.

[optional] string index
One or more indexes of events to remove.

[optional] string startIndex
Index identifying the beginning of the window.

[optional] string endIndex
Index identifying the end of the window.

Response

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. Interpolation is not supported for streams with compound indexes.

SDS supports two ways of specifying which stored events to return: index collection and interval.

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.

Parameters: Accepts index.

Interval: Returns events at evenly spaced intervals based on the specified startIndex, endIndex, and count. If no stored event exists at an index interval, the stream's read characteristics determine how the returned event is calculated.

Parameters: Accepts startIndex, endIndex and count.

Request

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

Parameters

string tenantId
Tenant identifier.

string namespaceId
Namespace identifier.

string streamId
Stream identifier.

[optional] string index
One or more indexes.

[optional] string startIndex
Index identifying the beginning of the series of events to return.

[optional] string endIndex
Index identifying the end of the series of events to return.

[optional] integer count
Parameter representing the maximum number of objects to retrieve. If unspecified, a default value of 100 is used.

Response

List 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.

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
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] integer count
Parameter representing the number of summary intervals to retrieve. If unspecified, a default value of 1 is used.

[optional] string filter
Filter expression.

Response

List 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.

Request

GET /api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams/{streamId}/Data/Sampled
?startIndex={startIndex}&endIndex={endIndex}&intervals={intervals}&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
Index identifying the beginning of the series of events to return.

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

integer intervals
The number of sample intervals requested.

string sampleBy
Property or properties to use when sampling.

[optional] integer boundaryType
SdsBoundaryType specifying the handling of events at or near the start and end indexes.

[optional] integer startBoundaryType
SdsBoundaryType specifying the first value in the result in relation to the start index. If startBoundaryType is specified, endBoundaryType must be specified.

[optional] integer endBoundaryType
SdsBoundaryType specifies the last value in the result in relation to the end index. If startBoundaryType is specified, endBoundaryType must be specified.

[optional] string filter
Filter expression.

Response

Definitions

ErrorResponseBody

The error response contains standard details on the cause and resolution of the error.

Properties

{
  "OperationId": "string",
  "Error": "string",
  "Reason": "string",
  "Resolution": "string",
  "Parameters": {
    "property1": "string",
    "property2": "string"
  }
}

SdsSearchMode

The SdsSearchMode defines search behavior when seeking a stored event near a specified index.

Enumerated Values

SdsBoundaryType

The SdsBoundaryType defines how data on the boundary of queries is handled: around the start index for range value queries, and around the start and end index for window values.

Enumerated Values