import { Command as $Command } from "@smithy/smithy-client"; import type { MetadataBearer as __MetadataBearer } from "@smithy/types"; import type { DynamoDBClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../DynamoDBClient"; import type { BatchGetItemInput, BatchGetItemOutput } from "../models/models_0"; /** * @public */ export type { __MetadataBearer }; export { $Command }; /** * @public * * The input for {@link BatchGetItemCommand}. */ export interface BatchGetItemCommandInput extends BatchGetItemInput { } /** * @public * * The output of {@link BatchGetItemCommand}. */ export interface BatchGetItemCommandOutput extends BatchGetItemOutput, __MetadataBearer { } declare const BatchGetItemCommand_base: { new (input: BatchGetItemCommandInput): import("@smithy/smithy-client").CommandImpl; new (input: BatchGetItemCommandInput): import("@smithy/smithy-client").CommandImpl; getEndpointParameterInstructions(): import("@smithy/middleware-endpoint").EndpointParameterInstructions; }; /** *

The BatchGetItem operation returns the attributes of one or more items * from one or more tables. You identify requested items by primary key.

*

A single operation can retrieve up to 16 MB of data, which can contain as many as 100 * items. BatchGetItem returns a partial result if the response size limit is * exceeded, the table's provisioned throughput is exceeded, more than 1MB per partition is * requested, or an internal processing failure occurs. If a partial result is returned, * the operation returns a value for UnprocessedKeys. You can use this value * to retry the operation starting with the next item to get.

* *

If you request more than 100 items, BatchGetItem returns a * ValidationException with the message "Too many items requested for * the BatchGetItem call."

* *

For example, if you ask to retrieve 100 items, but each individual item is 300 KB in * size, the system returns 52 items (so as not to exceed the 16 MB limit). It also returns * an appropriate UnprocessedKeys value so you can get the next page of * results. If desired, your application can include its own logic to assemble the pages of * results into one dataset.

*

If none of the items can be processed due to insufficient * provisioned throughput on all of the tables in the request, then * BatchGetItem returns a * ProvisionedThroughputExceededException. If at least * one of the items is successfully processed, then * BatchGetItem completes successfully, while returning the keys of the * unread items in UnprocessedKeys.

* *

If DynamoDB returns any unprocessed items, you should retry the batch operation on * those items. However, we strongly recommend that you use an exponential * backoff algorithm. If you retry the batch operation immediately, the * underlying read or write requests can still fail due to throttling on the individual * tables. If you delay the batch operation using exponential backoff, the individual * requests in the batch are much more likely to succeed.

*

For more information, see Batch Operations and Error Handling in the Amazon DynamoDB * Developer Guide.

* *

By default, BatchGetItem performs eventually consistent reads on every * table in the request. If you want strongly consistent reads instead, you can set * ConsistentRead to true for any or all tables.

*

In order to minimize response latency, BatchGetItem may retrieve items in * parallel.

*

When designing your application, keep in mind that DynamoDB does not return items in * any particular order. To help parse the response by item, include the primary key values * for the items in your request in the ProjectionExpression parameter.

*

If a requested item does not exist, it is not returned in the result. Requests for * nonexistent items consume the minimum read capacity units according to the type of read. * For more information, see Working with Tables in the Amazon DynamoDB Developer * Guide.

* *

* BatchGetItem will result in a ValidationException if the * same key is specified multiple times.

* * @example * Use a bare-bones client and the command you need to make an API call. * ```javascript * import { DynamoDBClient, BatchGetItemCommand } from "@aws-sdk/client-dynamodb"; // ES Modules import * // const { DynamoDBClient, BatchGetItemCommand } = require("@aws-sdk/client-dynamodb"); // CommonJS import * // import type { DynamoDBClientConfig } from "@aws-sdk/client-dynamodb"; * const config = {}; // type is DynamoDBClientConfig * const client = new DynamoDBClient(config); * const input = { // BatchGetItemInput * RequestItems: { // BatchGetRequestMap // required * "": { // KeysAndAttributes * Keys: [ // KeyList // required * { // Key * "": { // AttributeValue Union: only one key present * S: "STRING_VALUE", * N: "STRING_VALUE", * B: new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("") * SS: [ // StringSetAttributeValue * "STRING_VALUE", * ], * NS: [ // NumberSetAttributeValue * "STRING_VALUE", * ], * BS: [ // BinarySetAttributeValue * new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("") * ], * M: { // MapAttributeValue * "": {// Union: only one key present * S: "STRING_VALUE", * N: "STRING_VALUE", * B: new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("") * SS: [ * "STRING_VALUE", * ], * NS: [ * "STRING_VALUE", * ], * BS: [ * new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("") * ], * M: { * "": "", * }, * L: [ // ListAttributeValue * "", * ], * NULL: true || false, * BOOL: true || false, * }, * }, * L: [ * "", * ], * NULL: true || false, * BOOL: true || false, * }, * }, * ], * AttributesToGet: [ // AttributeNameList * "STRING_VALUE", * ], * ConsistentRead: true || false, * ProjectionExpression: "STRING_VALUE", * ExpressionAttributeNames: { // ExpressionAttributeNameMap * "": "STRING_VALUE", * }, * }, * }, * ReturnConsumedCapacity: "INDEXES" || "TOTAL" || "NONE", * }; * const command = new BatchGetItemCommand(input); * const response = await client.send(command); * // { // BatchGetItemOutput * // Responses: { // BatchGetResponseMap * // "": [ // ItemList * // { // AttributeMap * // "": { // AttributeValue Union: only one key present * // S: "STRING_VALUE", * // N: "STRING_VALUE", * // B: new Uint8Array(), * // SS: [ // StringSetAttributeValue * // "STRING_VALUE", * // ], * // NS: [ // NumberSetAttributeValue * // "STRING_VALUE", * // ], * // BS: [ // BinarySetAttributeValue * // new Uint8Array(), * // ], * // M: { // MapAttributeValue * // "": {// Union: only one key present * // S: "STRING_VALUE", * // N: "STRING_VALUE", * // B: new Uint8Array(), * // SS: [ * // "STRING_VALUE", * // ], * // NS: [ * // "STRING_VALUE", * // ], * // BS: [ * // new Uint8Array(), * // ], * // M: { * // "": "", * // }, * // L: [ // ListAttributeValue * // "", * // ], * // NULL: true || false, * // BOOL: true || false, * // }, * // }, * // L: [ * // "", * // ], * // NULL: true || false, * // BOOL: true || false, * // }, * // }, * // ], * // }, * // UnprocessedKeys: { // BatchGetRequestMap * // "": { // KeysAndAttributes * // Keys: [ // KeyList // required * // { // Key * // "": "", * // }, * // ], * // AttributesToGet: [ // AttributeNameList * // "STRING_VALUE", * // ], * // ConsistentRead: true || false, * // ProjectionExpression: "STRING_VALUE", * // ExpressionAttributeNames: { // ExpressionAttributeNameMap * // "": "STRING_VALUE", * // }, * // }, * // }, * // ConsumedCapacity: [ // ConsumedCapacityMultiple * // { // ConsumedCapacity * // TableName: "STRING_VALUE", * // CapacityUnits: Number("double"), * // ReadCapacityUnits: Number("double"), * // WriteCapacityUnits: Number("double"), * // Table: { // Capacity * // ReadCapacityUnits: Number("double"), * // WriteCapacityUnits: Number("double"), * // CapacityUnits: Number("double"), * // }, * // LocalSecondaryIndexes: { // SecondaryIndexesCapacityMap * // "": { * // ReadCapacityUnits: Number("double"), * // WriteCapacityUnits: Number("double"), * // CapacityUnits: Number("double"), * // }, * // }, * // GlobalSecondaryIndexes: { * // "": { * // ReadCapacityUnits: Number("double"), * // WriteCapacityUnits: Number("double"), * // CapacityUnits: Number("double"), * // }, * // }, * // }, * // ], * // }; * * ``` * * @param BatchGetItemCommandInput - {@link BatchGetItemCommandInput} * @returns {@link BatchGetItemCommandOutput} * @see {@link BatchGetItemCommandInput} for command's `input` shape. * @see {@link BatchGetItemCommandOutput} for command's `response` shape. * @see {@link DynamoDBClientResolvedConfig | config} for DynamoDBClient's `config` shape. * * @throws {@link InternalServerError} (server fault) *

An error occurred on the server side.

* * @throws {@link InvalidEndpointException} (client fault) * * @throws {@link ProvisionedThroughputExceededException} (client fault) *

The request was denied due to request throttling. For detailed information about * why the request was throttled and the ARN of the impacted resource, find the ThrottlingReason field in the returned exception. The Amazon Web Services * SDKs for DynamoDB automatically retry requests that receive this exception. * Your request is eventually successful, unless your retry queue is too large to finish. * Reduce the frequency of requests and use exponential backoff. For more information, go * to Error Retries and Exponential Backoff in the Amazon DynamoDB Developer Guide.

* * @throws {@link RequestLimitExceeded} (client fault) *

Throughput exceeds the current throughput quota for your account. For detailed * information about why the request was throttled and the ARN of the impacted resource, * find the ThrottlingReason field in the returned exception. Contact Amazon Web Services Support to request a quota * increase.

* * @throws {@link ResourceNotFoundException} (client fault) *

The operation tried to access a nonexistent table or index. The resource might not * be specified correctly, or its status might not be ACTIVE.

* * @throws {@link ThrottlingException} (client fault) *

The request was denied due to request throttling. For detailed information about why * the request was throttled and the ARN of the impacted resource, find the ThrottlingReason field in the returned exception.

* * @throws {@link DynamoDBServiceException} *

Base exception class for all service exceptions from DynamoDB service.

* * * @example To retrieve multiple items from a table * ```javascript * // This example reads multiple items from the Music table using a batch of three GetItem requests. Only the AlbumTitle attribute is returned. * const input = { * RequestItems: { * Music: { * Keys: [ * { * Artist: { * S: "No One You Know" * }, * SongTitle: { * S: "Call Me Today" * } * }, * { * Artist: { * S: "Acme Band" * }, * SongTitle: { * S: "Happy Day" * } * }, * { * Artist: { * S: "No One You Know" * }, * SongTitle: { * S: "Scared of My Shadow" * } * } * ], * ProjectionExpression: "AlbumTitle" * } * } * }; * const command = new BatchGetItemCommand(input); * const response = await client.send(command); * /* response is * { * Responses: { * Music: [ * { * AlbumTitle: { * S: "Somewhat Famous" * } * }, * { * AlbumTitle: { * S: "Blue Sky Blues" * } * }, * { * AlbumTitle: { * S: "Louder Than Ever" * } * } * ] * } * } * *\/ * ``` * * @public */ export declare class BatchGetItemCommand extends BatchGetItemCommand_base { /** @internal type navigation helper, not in runtime. */ protected static __types: { api: { input: BatchGetItemInput; output: BatchGetItemOutput; }; sdk: { input: BatchGetItemCommandInput; output: BatchGetItemCommandOutput; }; }; }