Menu
Documentationbreadcrumb arrow Grafana k6breadcrumb arrow JavaScript APIbreadcrumb arrow jslibbreadcrumb arrow awsbreadcrumb arrow KinesisClientbreadcrumb arrow getShardIterator
Open source

getShardIterator

KinesisClient.getShardIterator(streamName, shardId, shardIteratorType, [options]) gets a shard iterator for reading records from a Kinesis stream shard.

Parameters

ParameterTypeDescription
streamNamestringThe name of the Kinesis stream.
shardIdstringThe shard ID for which to get the iterator.
shardIteratorTypestringThe type of shard iterator to get.
optionsobjectOptional configuration for the shard iterator.

Shard Iterator Types

TypeDescription
TRIM_HORIZONStart reading at the last untrimmed record in the shard.
LATESTStart reading just after the most recent record in the shard.
AT_SEQUENCE_NUMBERStart reading from the position denoted by a specific sequence number.
AFTER_SEQUENCE_NUMBERStart reading right after the position denoted by a specific sequence number.
AT_TIMESTAMPStart reading from the position denoted by a specific timestamp.

Options

ParameterTypeDescription
startingSequenceNumberstringThe sequence number to start from (required for AT_SEQUENCE_NUMBER and AFTER_SEQUENCE_NUMBER types).
timestampDateThe timestamp to start from (required for AT_TIMESTAMP type).

Returns

TypeDescription
Promise<Object>A Promise that fulfills with the shard iterator response.

Returns object

PropertyTypeDescription
shardIteratorstringThe shard iterator to use for reading records.

Example

JavaScript 
import {
  AWSConfig,
  KinesisClient,
} from 'https://jslib.k6.io/aws/0.14.0/kinesis.js';

const awsConfig = new AWSConfig({
  region: __ENV.AWS_REGION,
  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
});

const kinesis = new KinesisClient(awsConfig);

export default async function () {
  const streamName = 'my-test-stream';

  // First, get the shards for the stream
  const shards = await kinesis.listShards(streamName);

  if (shards.shards.length > 0) {
    const shardId = shards.shards[0].shardId;

    // Get a shard iterator starting from the beginning
    const trimHorizonIterator = await kinesis.getShardIterator(streamName, shardId, 'TRIM_HORIZON');
    console.log('Trim horizon iterator:', trimHorizonIterator.shardIterator);

    // Get a shard iterator starting from the latest records
    const latestIterator = await kinesis.getShardIterator(streamName, shardId, 'LATEST');
    console.log('Latest iterator:', latestIterator.shardIterator);

    // Get a shard iterator starting from a specific timestamp
    const timestampIterator = await kinesis.getShardIterator(streamName, shardId, 'AT_TIMESTAMP', {
      timestamp: new Date(Date.now() - 3600000), // 1 hour ago
    });
    console.log('Timestamp iterator:', timestampIterator.shardIterator);

    // Use the iterator to read records
    const records = await kinesis.getRecords(trimHorizonIterator.shardIterator);
    console.log('Records retrieved:', records.records.length);

    // If we have records, we can get an iterator starting after a specific sequence number
    if (records.records.length > 0) {
      const sequenceNumber = records.records[0].sequenceNumber;
      const afterSequenceIterator = await kinesis.getShardIterator(
        streamName,
        shardId,
        'AFTER_SEQUENCE_NUMBER',
        {
          startingSequenceNumber: sequenceNumber,
        }
      );
      console.log('After sequence iterator:', afterSequenceIterator.shardIterator);
    }
  }
}