Seek

On This Page

Description

Returns the requested location within the specified stream shard, for use in a subsequent GetRecords operation. The operation supports different seek types, as outlined in the Stream Record Consumption overview and in the description of the Type request parameter below.

Request

Request Header

Syntax
    POST /<container>/<resource> HTTP/1.1
Host: <web-APIs URL>
Content-Type: application/json
X-v3io-function: Seek
<Authorization OR X-v3io-session-key>: <value>

    url = "http://<web-APIs URL>/<container>/<resource>"
headers = {
            "Content-Type": "application/json",
            "X-v3io-function": "Seek",
            "<Authorization OR X-v3io-session-key>": "<value>"
          }
    URL Resource Parameters

    The path to the target stream shard. The path includes the stream path and the shard ID. You can optionally set the stream name and shard ID, or only the shard ID, in the request's StreamName and ShardId JSON parameters instead of in the URL.

    Request Data

    Syntax
      {
    "StreamName":             "string",
    "ShardId":                number,
    "Type":                   "string",
    "TimestampSec":           number,
    "TimestampNSec":          number,
    "StartingSequenceNumber": number
}

      payload = {
            "StreamName":              "string",
            "ShardId":                 number,
            "Type":                    "string",
            "TimestampSec":            number,
            "TimestampNSec":           number,
            "StartingSequenceNumber":  number
          }
      Parameters
      StreamName

      The name of the stream that contains the shard resource.

      • Type: String
      • Requirement: Required if not set in the request URL
      ShardId

      The ID of the shard for which to obtain the requested location.
      The shard ID is an integer between 0 and one less than the stream's shard count.

      • Type: Number
      • Requirement: Required if not set in the request URL
      Type

      The seek type, which determines the location in the specified stream shard to retrieve.

      • Type: String
      • Requirement: Required

      The following seek types are supported:

      • "EARLIEST" — the location of the earliest ingested record in the shard.

      • "LATEST" — the location of the end of the shard.

      • "TIME" — the location of the earliest ingested record in the shard beginning at the base time set in the TimestampSec and TimestampNSec request parameters. If no matching record is found (i.e., if all records in the shard arrived before the specified base time) the operation returns the location of the end of the shard.

      • "SEQUENCE" — the location of the record whose sequence number matches the sequence number specified in the StartingSequenceNumber request parameter. If no match is found, the operation fails.

      TimestampSec

      The base time for a time-based seek operation (Type=TIME), as a Unix timestamp in seconds. For example, 1511260205 sets the search base time to 21 Nov 2017 at 10:30:05 AM UTC. The TimestampNSec request parameter sets the nanoseconds unit of the seek base time.
      When the TimestampSec and TimestampNSec parameters are set, the operation searches for the location of the earliest ingested record in the shard (the earliest record that arrived at the platform) beginning at the specified base time. If no matching record is found (i.e., if all records in the shard arrived before the specified base time), return the last location in the shard.

      • Type: Number

      • Requirement: Required when the value of the Type request parameter is TIME

      TimestampNSec

      The nanoseconds unit of the TimestampSec base-time timestamp for a time-based seek operation (Type=TIME). For example, if TimestampSec is 1511260205 and TimestampNSec is 500000000, seek should search for the earliest ingested record since 21 Nov 2017 at 10:30 AM and 5.5 seconds.

      • Type: Number

      • Requirement: Required when the value of the Type request parameter is TIME

      StartSequenceNumber

      Record sequence number for a sequence-number based seek operation — Type=SEQUENCE. When this parameter is set, the operation returns the location of the record whose sequence number matches the parameter.

      • Type: Number

      • Requirement: Required when the value of the Type request parameter is SEQUENCE

      Response

      Response Data

      Syntax
      {
    "Location": "blob"
}
      Elements
      Location

      The requested location within the specified stream shard (see the Type request parameter).

      • Type: Blob — a Base64 encoded string

      Errors

      In the event of an error, the response includes a JSON object with an ErrorCode element that contains a unique numeric error code, and an ErrorMessage element that contains one of the following API error messages:
      Error Message Description
      InvalidArgumentException A provided request parameter is not valid for this request.
      Permission denied The sender of the request does not have the required permissions to perform the operation.
      ResourceNotFoundException The specified resource does not exist.
      ShardIDOutOfRangeException The specified shard does not exist in this stream.

      Examples

      Obtain the location of the earliest ingested record in shard 199 of a MyStream stream:

      Request
        POST /mycontainer/MyDirectory/MyStream/199 HTTP/1.1
Host: https://default-tenant.app.mycluster.iguazio.com:8443
Content-Type: application/json
X-v3io-function: Seek
X-v3io-session-key: e8bd4ca2-537b-4175-bf01-8c74963e90bf

        {
    "Type": "EARLIEST"
}

        import requests

url = "https://default-tenant.app.mycluster.iguazio.com:8443/mycontainer/MyDirectory/MyStream/199"
headers = {
            "Content-Type": "application/json",
            "X-v3io-function": "Seek",
            "X-v3io-session-key": "e8bd4ca2-537b-4175-bf01-8c74963e90bf"
          }
payload = {"Type": "EARLIEST"}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
        Response
        HTTP/1.1 200 OK
Content-Type: application/json
...

        {"Location": "AQAAAAAAAAAAAAAAAAAAAA=="}