Navigation Guide
You are on a Command (operation) page with structural examples. Use the navigation breadcrumb if you would like to return to the Client landing page.

GetShardIteratorCommand

Returns a shard iterator. A shard iterator provides information about how to retrieve the stream records from within a shard. Use the shard iterator in a subsequent GetRecords request to read the stream records from the shard.

A shard iterator expires 15 minutes after it is returned to the requester.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { DynamoDBStreamsClient, GetShardIteratorCommand } from "@aws-sdk/client-dynamodb-streams"; // ES Modules import
// const { DynamoDBStreamsClient, GetShardIteratorCommand } = require("@aws-sdk/client-dynamodb-streams"); // CommonJS import
const client = new DynamoDBStreamsClient(config);
const input = { // GetShardIteratorInput
  StreamArn: "STRING_VALUE", // required
  ShardId: "STRING_VALUE", // required
  ShardIteratorType: "TRIM_HORIZON" || "LATEST" || "AT_SEQUENCE_NUMBER" || "AFTER_SEQUENCE_NUMBER", // required
  SequenceNumber: "STRING_VALUE",
};
const command = new GetShardIteratorCommand(input);
const response = await client.send(command);
// { // GetShardIteratorOutput
//   ShardIterator: "STRING_VALUE",
// };

Example Usage

There was an error loading the code editor. Retry

GetShardIteratorCommand Input

See GetShardIteratorCommandInput for more details

Parameter	Type	Description
`ShardId` Required	`string \| undefined`	The identifier of the shard. The iterator will be returned for this shard ID.
`ShardIteratorType` Required	`ShardIteratorType \| undefined`	Determines how the shard iterator is used to start reading stream records from the shard: `AT_SEQUENCE_NUMBER` - Start reading exactly from the position denoted by a specific sequence number. `AFTER_SEQUENCE_NUMBER` - Start reading right after the position denoted by a specific sequence number. `TRIM_HORIZON` - Start reading at the last (untrimmed) stream record, which is the oldest record in the shard. In DynamoDB Streams, there is a 24 hour limit on data retention. Stream records whose age exceeds this limit are subject to removal (trimming) from the stream. `LATEST` - Start reading just after the most recent stream record in the shard, so that you always read the most recent data in the shard.
`StreamArn` Required	`string \| undefined`	The Amazon Resource Name (ARN) for the stream.
`SequenceNumber`	`string \| undefined`	The sequence number of a stream record in the shard from which to start reading.

GetShardIteratorCommand Output

See GetShardIteratorCommandOutput for details

Parameter	Type	Description
`$metadata` Required	`ResponseMetadata`	Metadata pertaining to this request.
`ShardIterator`	`string \| undefined`	The position in the shard from which to start reading stream records sequentially. A shard iterator specifies this position using the sequence number of a stream record in a shard.

Throws

Name	Fault	Details
InternalServerError	server	An error occurred on the server side.
ResourceNotFoundException	client	The operation tried to access a nonexistent table or index. The resource might not be specified correctly, or its status might not be `ACTIVE`.
TrimmedDataAccessException	client	The operation attempted to read past the oldest stream record in a shard. In DynamoDB Streams, there is a 24 hour limit on data retention. Stream records whose age exceeds this limit are subject to removal (trimming) from the stream. You might receive a TrimmedDataAccessException if: You request a shard iterator with a sequence number older than the trim point (24 hours). You obtain a shard iterator, but before you use the iterator in a `GetRecords` request, a stream record in the shard exceeds the 24 hour period and is trimmed. This causes the iterator to access a record that no longer exists.
DynamoDBStreamsServiceException		Base exception class for all service exceptions from DynamoDBStreams service.

Getting Started