Streams

A stream is an ordered collection of data points that share the same SDS type definition. Streams store sequential data (typically time-series data) indexed by a key property, and enable efficient storage and retrieval of timestamped measurements or sequential records from devices, sensors, and processes.

Streams are derived from SDS types. Think of the relationship this way: an SDS type is a blueprint or schema that defines the structure of data points (the properties, data types, and key rules), while a stream is a container that holds actual data points conforming to that schema. You define the SDS type once, then create one or more streams that reference it. Every data point written to a stream must match that structure.

For example, if you define a telemetry SDS type with Time (key), Temperature, and Pressure properties, then create a stream using that type, all data points written to the stream must have those three properties in that structure. The SDS type validates the data point shape. The stream stores the actual data.

The following example shows a representative stream definition. It uses the same stream throughout this topic so later examples can build on it. The inline comments describe what each field represents.

{

  "id": "TemperatureSensor_Building_Alpha", // Unique stream ID within the service instance

  "typeId": "TelemetryType", // SDS type that defines properties like Time, Temperature, and Pressure

  "name": "Temperature Sensor Building Alpha", // Human-readable name

  "description": "Primary temperature sensor for Building Alpha HVAC monitoring.", // Additional context for users

  "interpolationMode": "Continuous", // Controls how missing-index reads are resolved for this stream

  "createdDate": "2026-03-10T14:30:00Z", // Server-managed timestamps

  "modifiedDate": "2026-03-10T14:30:00Z"

}

For field purpose and usage guidance, see Stream properties. For complete field definitions, see SdsStream schema.

After the stream is created, you can write data points to it. Each data point must conform to the TelemetryType schema. It must have a Time property (the key), a Temperature value, and a Pressure value. The stream validates and stores each data point in time order.

A data point is a single data record stored in a stream that conforms to the stream's type schema and is indexed by a key property. The following table shows example data points written to the TemperatureSensor_Building_Alpha stream:

Each row represents a single data point stored in the stream. The Time value uniquely identifies each data point and maintains the time order. The stream persists these data points and provides efficient retrieval using query endpoints.

Create a stream when you need to:

• Store time-series or sequential data from devices or processes.

• Define a reusable data container that conforms to an existing type.

• Apply stream-level configurations such as custom interpolation or unit conversions.

• Organize multiple related data sources under a common type schema.

Prerequisites

Before creating a stream:

• Have access to CONNECT and authentication credentials (account ID and token).

• Have a Stream Management service instance provisioned.

• Have defined at least one SDS type that will serve as the stream's data schema.

Stream properties

SdsStream properties define how a stream is identified, how it binds to an SDS type, and how the service manages read behavior and organization metadata. In practice, stream properties are the control surface for making a stream usable in production. They let you reference the stream reliably, query and discover it efficiently, and tune interpolation and property-level behavior without changing the underlying SDS type.

You can use SdsStream properties to:

• Identify and bind a stream to its SDS type using id and typeId.

• Add human-readable context with name and description.

• Configure stream-specific behavior with indexes and propertyOverrides.

• Configure query behavior with interpolationMode and extrapolationMode.

• Track lifecycle timestamps through server-managed createdDate and modifiedDate.

• For the complete SdsStream schema definition, see Stream Management.

Rules for the stream ID

The stream ID (id) must follow these rules:

• Is not case sensitive.

• Cannot be only whitespace.

• Cannot contain leading or trailing whitespace.

• Cannot contain forward slash (/).

• Can have at most 250 characters.

Secondary indexes

Secondary indexes are optional stream-level indexes configured through the indexes property in SdsStream.

Secondary indexes are only applicable to streams. They are not defined on SDS types. An SDS type defines the primary index, while each stream can define its own secondary indexes.

This means streams that share the same SDS type can still use different secondary-index configurations based on query needs.

When configuring secondary indexes:

• Use only supported index property data types (for example, DateTime, DateTimeOffset, TimeSpan, String, Guid, Boolean, Char, or numeric types).

• Define secondary indexes on the stream after the SDS type exists.

• Keep primary and compound-index rules in mind when choosing eligible properties.

• Ensure each sdsTypePropertyId in indexes matches a property defined on the stream's SDS type.

Example stream request body with secondary indexes:

This example continues the earlier TemperatureSensor_Building_Alpha stream example. Assume the SDS type TelemetryType already defines Time as the primary index, with Temperature as an additional ordered property. The request body below shows how the same stream definition can include a secondary index on Temperature.

{

  "id": "TemperatureSensor_Building_Alpha", // Same stream shown earlier in this topic

  "typeId": "TelemetryType", // Same SDS type shown earlier. It defines the primary index.

  "name": "Temperature Sensor Building Alpha",

  "description": "Primary temperature sensor for Building Alpha HVAC monitoring.",

  "indexes":

    {

      "sdsTypePropertyId": "Temperature" // Adds a secondary index on the Temperature property

    }

 

}

In this example, Time remains the primary index because it is defined on the SDS type. The indexes array does not replace that primary index. It adds an additional queryable index for Temperature on this stream.

For index behavior, constraints, and examples, see Indexes, especially:

• Primary indexes

• Compound indexes

• Secondary indexes

• Supported property data types for indexes

Property overrides

Use propertyOverrides to apply stream-specific behavior to individual SDS type properties.

Each sdsTypePropertyId in propertyOverrides must match a property defined on the stream's SDS type.

Each item in propertyOverrides targets one SDS type property by sdsTypePropertyId and can override:

• interpolationMode for that property.

• uom (unit of measure) for that property.

This example continues the same TemperatureSensor_Building_Alpha stream and applies a property-level override to Temperature.

{

  "id": "TemperatureSensor_Building_Alpha",

  "typeId": "TelemetryType",

  "propertyOverrides":

    {

      "sdsTypePropertyId": "Temperature", // Property from the SDS type to override

      "interpolationMode": "StepwiseContinuousLeading", // Overrides stream/type interpolation for this property

      "uom": "degreeCelsius" // Overrides unit of measure for this property

    }

 

}

Property overrides do not redefine primary or secondary indexes. They refine read behavior and units for the targeted property only.

Units of measure

Use uom settings when you need stream data to carry unit metadata or be read with unit-specific behavior.

• At the SDS type level, a property can define a default unit of measure.

• At the stream level, propertyOverrides can override uom for a specific property.

For units, quantities, and conversion documentation, see Units of measure and quantities.

Interpolation and extrapolation

Use stream read settings to control how missing-index requests are resolved.

For interpolation and extrapolation definitions, mode values, behavior examples, inheritance rules, and property override behavior, see , especially:

• Where interpolation and extrapolation mode settings are defined

• Interpolation modes

• Extrapolation modes

• Property override behavior

Organize streams with tags and metadata

You can also apply tags and metadata to streams through dedicated endpoints to organize streams and improve discovery.

• Use tags for lightweight grouping and filtering.

• Use metadata for key-value context such as location, asset identity, or ownership attributes.

For comprehensive guidance on tags and metadata operations, see Stream tags and metadata.