Main Content

seek

Set read position in event stream

Since R2022b

collapse all in page

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

    Syntax

    offset = seek(stream,position)
    offset = seek(stream,position,origin)

    Description

    offset = seek(stream,position) sets the read position of event stream stream to position. You can specify a numeric absolute position or a relative position, such as "Beginning" or "End" for the start or end of the stream, respectively. seek returns the position from which the next read operation occurs.

    example

    offset = seek(stream,position,origin) moves the read position of an event stream position number of events relative to the specified origin.

    example

    Examples

    collapse all

    Create a TestStream object to read from and write events to an event stream hosted by MATLAB.

    ts = testStream;

    Write sample timetable data to the event stream.

    load indoors
writetimetable(ts,indoors)

    Read data from the stream. The stream contains 60 events, but the stream by default has a window size of 100. Therefore, readtimetable reads the entire stream in a single read. The read position is one position past the end of the stream.

    tt = readtimetable(ts);

    Move the read position back to the first event.

    seek(ts,"Beginning");

    Create an InMemoryStream object to read from and write events to an event stream hosted by MATLAB. Configure the object to read 10 events at a time.

    numRows = 10;
is = inMemoryStream(Rows=numRows);

    Write timetable data to the event stream.

    load indoors
writetimetable(is,indoors)

    Move the read position 10 rows back from the end position.

    seek(is,-numRows + 1,"End");

    Read the last 10 events from the stream.

    tt = readtimetable(is)
    tt =

  10×2 timetable

           Time            Humidity    AirQuality
    ___________________    ________    __________

    2015-11-17 13:00:19       37           79    
    2015-11-17 14:13:31       37           80    
    2015-11-17 15:26:43       37           79    
    2015-11-17 16:39:55       37           77    
    2015-11-17 17:53:07       37           79    
    2015-11-17 19:06:19       37           79    
    2015-11-17 20:19:31       37           80    
    2015-11-17 21:32:43       37           81    
    2015-11-17 22:45:55       37           79    
    2015-11-17 23:59:07       35           79

    Input Arguments

    collapse all

    Object connected to an event stream, specified as a KafkaStream, InMemoryStream, or TestStream object.

    Position in an event stream at which the next read starts, specified as an absolute or relative position.

    Absolute Position

    Specify one of these values:

    • A positive integer indicating the number of events from the start of the event stream that the read position moves to. You cannot specify an integer greater than the length of the stream. For example, seek(stream,5) moves the read position to the fifth event in the stream.

    • A datetime scalar indicating the event timestamp that the read position moves to. If the stream contains no event corresponding to the specified date or time, the stream position moves to the first time after the specified time. For example, seek(stream,datetime(2022,5,13,16,34,26)) moves the read position to the event that has a timestamp of 13-May-2022 16:34:26.

    Relative Position

    Specify one of these values:

    • "Beginning" — First event available in stream. For example: seek(stream,"Beginning").

    • "End" — Just past the last event in the stream. For example: seek(stream,"End").

    • "Current" — Just past the current event in the stream. For example: seek(stream,"End").

    • If you specify origin, a positive or negative integer indicating the number of events relative to that origin. For example, seek(stream,-10,"End") moves the read position 10 positions from the last event in the stream.

      position must not exceed either end of the stream relative to origin. If origin is "End", then position must be negative. If origin is "Beginning", then position must be positive.

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

    Origin that the read position specified by position is relative to, specified as one of these values:

    • "Beginning" — Read position is relative to the first event available in stream.

    • "End" — Read position is relative to the last event in the stream.

    • "Current" — Read position is relative to the current event in the stream.

    Data Types: string | char

    Version History

    Introduced in R2022b

    See Also

    | | | | | |