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>

Copy

Copied to clipboard

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

Copy

Copied to clipboard

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
}

Copy

Copied to clipboard

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

Copy

Copied to clipboard

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"
}

Copy

Copied to clipboard

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

Copy

Copied to clipboard

{
    "Type": "EARLIEST"
}

Copy

Copied to clipboard

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)

Copy

Copied to clipboard

Response

HTTP/1.1 200 OK
Content-Type: application/json
...

Copy

Copied to clipboard

{"Location": "AQAAAAAAAAAAAAAAAAAAAA=="}

Copy

Copied to clipboard