inMemoryStream

Create connection to event stream hosted by MATLAB without schema processing applied

Since R2022b

This object requires Streaming Data Framework for MATLAB^® Production Server™.

Description

The inMemoryStream function creates an InMemoryStream object, which you can use to test reading from and writing to event streams hosted by MATLAB. Unlike the TestStream object, InMemoryStream objects do not apply schema processing when reading and writing timetable data. The data in an inMemoryStream object disappears when you exit MATLAB.

Creation

Syntax

stream = inMemoryStream

stream = inMemoryStream(Rows=numevents)

stream = inMemoryStream(Duration=timespan)

stream = inMemoryStream(___,Name=Value)

Description

Row-Based Event Window

stream = inMemoryStream creates a default InMemoryStream object connected to an event stream hosted by MATLAB that does not apply schema processing. The object reads 50 stream event rows at a time.

stream = inMemoryStream(Rows=numevents) creates an InMemoryStream object that reads numevents stream event rows at a time.

Duration-Based Event Window

stream = inMemoryStream(Duration=timespan) creates an InMemoryStream object that reads stream events occurring during the specified timestamp span, timespan.

Additional Options

stream = inMemoryStream(___,Name=Value) sets event stream properties using one or more name-value arguments and any of the previous syntaxes.

Input Arguments

numevents — Number of events in event window

50 (default) | positive integer

Number of events in the event window, specified as a positive integer. Rows=numevents specifies the number of rows that a call to the readtimetable function returns. If there are less than the number of specified rows available for reading, then readtimetable times out and returns an empty timetable.

Example: Rows=500 specifies that each call to readtimetable returns a timetable with 500 rows.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

timespan — Timestamp span in event window

0 (default) | duration scalar

Timestamp span in the event window, specified as a duration scalar. Duration=timespan determines the events that the readtimetable function returns based on their timestamp. timespan specifies the difference between the last and first timestamps of events in the event window.

Example: Duration=minutes(1) specifies that each call to readtimetable returns a timetable that has one minute's worth of events, where the timestamp of the last event is no more than one minute later than the timestamp of the first event.

Data Types: duration

Properties

Name — Event stream name

string scalar

Event stream name, specified as a string scalar or character vector.

You cannot set the value of this property or use it as an input argument during object creation.

Example: 5cb30967-46fd-4058-8be7-704e4dbccc8d

Data Types: string

WindowSize — Event window size

50 (default) | duration scalar | positive integer

This property is read-only.

Event window size, specified as a fixed amount of time (using the timespan argument) or a fixed number of messages (using the numevents argument).

Data Types: duration | single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

ReadLimit — Wait strategy

"Size" (default) | "Time"

Strategy to wait for a response from the stream, specified as one of these values:

• "Size" — Client prioritizes filling the event window. Using this strategy, the client might wait longer than the RequestTimeout time period as long as it is still receiving the expected number of messages. The default number of messages is 50. If the client receives no messages within the RequestTimeout time period, it no longer waits.

• "Time" — Client strictly adheres to the RequestTimeout limit, even if it has not received the expected number of messages. RequestTimeout specifies the amount of time the stream object waits between receiving events. If the stream is actively receiving data, it does not time out during that operation.

Note

This object does not implement the ReadLimit property and does not have a RequestTimeout property. It is provided for compatibility with other stream connector objects. By setting the wait strategy in this object, you can more easily update your code to switch between objects that do implement this property, such as KafkaStream.

TimestampResolution — Unit of event timestamp

"Milliseconds" (default) | "Seconds" | "Minutes" | "Hours" | "Days"

Unit of event timestamp, specified as one of these values:

• "Milliseconds"

• "Seconds"

• "Minutes"

• "Hours"

• "Days"

Interpret the event timestamp as the number of corresponding units before or after the Unix epoch.

Data Types: string | char

Event Key and Body Encoding

KeyVariable — Name of key variable

key (default) | string scalar | character vector

Name of the key variable in the event stream, specified as a string scalar or character vector.

Data Types: string | char

KeyEncoding — Character encoding format for bits in event key

utf8 (default) | utf16 | base64 | uint8

Character encoding format used to interpret the bits in an event key, specified as one of the following:

• utf8 — UTF-8 encoding format

• utf16 — UTF-16 encoding format

• base64— Base 64 encoding format

• uint8 — Eight-bit unsigned binary bytes

If KeyEncoding is utf8 or utf16, then the KeyType property must be text. If KeyEncoding is base64 or uint8, then KeyType must be one of the numeric encoding formats.

KeyType — Character encoding scheme for bytes in event key

text (default) | utf16 | int8 | uint8 | int16 | uint16 | int32 | uint32 | int64 | uint64 | single | double

Character encoding scheme used to interpret the bytes in an event key, specified as one of these values:

• uint8 — One-byte unsigned integer

• int8 — One-byte signed integer

• uint16 — Two-byte unsigned integer

• int16 — Two-byte signed integer

• uint32 — Four-byte unsigned integer

• int32 — Four-byte signed integer

• uint64 — Eight-byte unsigned integer

• int64 — Eight-byte signed integer

• single — Single-precision IEEE 754 floating point number

• double — Double-precision IEEE 754 floating point number

• text — String

If KeyType is text, then the KeyEncoding property must be either utf8 or utf16. If KeyType is any of the other numeric encoding formats, then KeyEncoding must be either base64 or uint8.

KeyByteOrder — Order for storing bits in event key

BigEndian (default) | LittleEndian | MatchHost | NotApplicable

Order for storing bits in the event key, specified as one of the following.

• LittleEndian — Least significant bit is stored first

• BigEndian — Most significant bit is stored first

• MatchHost— Bits are stored in the same order as is used by the host computer on which the streaming data framework is running

• NotApplicable — Not an integer key

This property is applicable only for integer keys and not applicable to floating point or text keys.

BodyEncoding — Character encoding format for bits in event body

utf8 (default) | uint8 | utf16 | base64

Character encoding format used to interpret the bits in the event body, specified as one of the following:

• utf8 — UTF-8 encoding format

• utf16 — UTF-16 encoding format

• base64— Base 64 encoding format

• uint8 — Eight-bit unsigned binary bytes

This property determines the size and encoding of the bytes used in the event body, which are in the format specified by BodyFormat.

BodyFormat — Format of bytes in event body

JSON (default) | Array | Text | Binary

Format of bytes in event body, specified as one of the following:

• JSON — JSON string

• Array — MATLAB array

• Text — String data

• Binary — Binary data

Depending on the encoding specified by BodyEncoding, bytes can be larger than eight bits.

Object Functions

readtimetable	Read timetable from event stream
writetimetable	Write timetable to event stream
seek	Set read position in event stream
preview	Preview subset of events from event stream
identifyingName	Event stream name
detectImportOptions	Create import options based on event stream content
detectExportOptions	Create export options based on event stream content

Examples

Write and Preview Events for In-Memory Stream

Create an InMemoryStream object to preview events from and write events to an event stream hosted by MATLAB.

is = inMemoryStream

is = 

  InMemoryStream with properties:

                   Name: "7803fad7-64b3-4439-af40-1b0e139fd68a"
             WindowSize: 50
            KeyVariable: "key"
            KeyEncoding: "utf8"
                KeyType: "text"
           KeyByteOrder: "BigEndian"
           BodyEncoding: "uint8"
             BodyFormat: "Array"
              ReadLimit: "Size"
    TimestampResolution: "Milliseconds"

Write timetable data to the event stream.

load indoors
writetimetable(is,indoors)

Preview data from the timetable. Unlike TestStream and KafkaStream, objects the InMemoryStream object does not include a key column to identify the event source, because the data kept in memory disappears when you exit MATLAB.

preview(is)

ans =

  8×2 timetable

           Time            Humidity    AirQuality
    ___________________    ________    __________

    2015-11-15 00:00:24       36           80    
    2015-11-15 01:13:35       36           80    
    2015-11-15 02:26:47       37           79    
    2015-11-15 03:39:59       37           82    
    2015-11-15 04:53:11       36           80    
    2015-11-15 06:06:23       36           80    
    2015-11-15 07:19:35       36           80    
    2015-11-15 08:32:47       37           80

Version History

Introduced in R2022b