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 { PutItemInput, PutItemOutput } from "../models/models_0"; /** * @public */ export type { __MetadataBearer }; export { $Command }; /** * @public * * The input for {@link PutItemCommand}. */ export interface PutItemCommandInput extends PutItemInput { } /** * @public * * The output of {@link PutItemCommand}. */ export interface PutItemCommandOutput extends PutItemOutput, __MetadataBearer { } declare const PutItemCommand_base: { new (input: PutItemCommandInput): import("@smithy/smithy-client").CommandImpl; new (input: PutItemCommandInput): import("@smithy/smithy-client").CommandImpl; getEndpointParameterInstructions(): import("@smithy/middleware-endpoint").EndpointParameterInstructions; }; /** *

Creates a new item, or replaces an old item with a new item. If an item that has the * same primary key as the new item already exists in the specified table, the new item * completely replaces the existing item. You can perform a conditional put operation (add * a new item if one with the specified primary key doesn't exist), or replace an existing * item if it has certain attribute values. You can return the item's attribute values in * the same operation, using the ReturnValues parameter.

*

When you add an item, the primary key attributes are the only required attributes.

*

Empty String and Binary attribute values are allowed. Attribute values of type String * and Binary must have a length greater than zero if the attribute is used as a key * attribute for a table or index. Set type attributes cannot be empty.

*

Invalid Requests with empty values will be rejected with a * ValidationException exception.

* *

To prevent a new item from replacing an existing item, use a conditional * expression that contains the attribute_not_exists function with the * name of the attribute being used as the partition key for the table. Since every * record must contain that attribute, the attribute_not_exists function * will only succeed if no matching item exists.

* * *

To determine whether PutItem overwrote an existing item, use * ReturnValues set to ALL_OLD. If the response includes * the Attributes element, an existing item was overwritten.

* *

For more information about PutItem, see Working with * Items in the Amazon DynamoDB Developer Guide.

* @example * Use a bare-bones client and the command you need to make an API call. * ```javascript * import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb"; // ES Modules import * // const { DynamoDBClient, PutItemCommand } = 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 = { // PutItemInput * TableName: "STRING_VALUE", // required * Item: { // PutItemInputAttributeMap // required * "": { // 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, * }, * }, * Expected: { // ExpectedAttributeMap * "": { // ExpectedAttributeValue * Value: "", * Exists: true || false, * ComparisonOperator: "EQ" || "NE" || "IN" || "LE" || "LT" || "GE" || "GT" || "BETWEEN" || "NOT_NULL" || "NULL" || "CONTAINS" || "NOT_CONTAINS" || "BEGINS_WITH", * AttributeValueList: [ // AttributeValueList * "", * ], * }, * }, * ReturnValues: "NONE" || "ALL_OLD" || "UPDATED_OLD" || "ALL_NEW" || "UPDATED_NEW", * ReturnConsumedCapacity: "INDEXES" || "TOTAL" || "NONE", * ReturnItemCollectionMetrics: "SIZE" || "NONE", * ConditionalOperator: "AND" || "OR", * ConditionExpression: "STRING_VALUE", * ExpressionAttributeNames: { // ExpressionAttributeNameMap * "": "STRING_VALUE", * }, * ExpressionAttributeValues: { // ExpressionAttributeValueMap * "": "", * }, * ReturnValuesOnConditionCheckFailure: "ALL_OLD" || "NONE", * }; * const command = new PutItemCommand(input); * const response = await client.send(command); * // { // PutItemOutput * // Attributes: { // 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, * // }, * // }, * // ConsumedCapacity: { // 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"), * // }, * // }, * // }, * // ItemCollectionMetrics: { // ItemCollectionMetrics * // ItemCollectionKey: { // ItemCollectionKeyAttributeMap * // "": "", * // }, * // SizeEstimateRangeGB: [ // ItemCollectionSizeEstimateRange * // Number("double"), * // ], * // }, * // }; * * ``` * * @param PutItemCommandInput - {@link PutItemCommandInput} * @returns {@link PutItemCommandOutput} * @see {@link PutItemCommandInput} for command's `input` shape. * @see {@link PutItemCommandOutput} for command's `response` shape. * @see {@link DynamoDBClientResolvedConfig | config} for DynamoDBClient's `config` shape. * * @throws {@link ConditionalCheckFailedException} (client fault) *

A condition specified in the operation failed to be evaluated.

* * @throws {@link InternalServerError} (server fault) *

An error occurred on the server side.

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

An item collection is too large. This exception is only returned for tables that * have one or more local secondary indexes.

* * @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 ReplicatedWriteConflictException} (client fault) *

The request was rejected because one or more items in the request are being modified * by a request in another Region.

* * @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 TransactionConflictException} (client fault) *

Operation was rejected because there is an ongoing transaction for the * item.

* * @throws {@link DynamoDBServiceException} *

Base exception class for all service exceptions from DynamoDB service.

* * * @example To add an item to a table * ```javascript * // This example adds a new item to the Music table. * const input = { * Item: { * AlbumTitle: { * S: "Somewhat Famous" * }, * Artist: { * S: "No One You Know" * }, * SongTitle: { * S: "Call Me Today" * } * }, * ReturnConsumedCapacity: "TOTAL", * TableName: "Music" * }; * const command = new PutItemCommand(input); * const response = await client.send(command); * /* response is * { * ConsumedCapacity: { * CapacityUnits: 1, * TableName: "Music" * } * } * *\/ * ``` * * @public */ export declare class PutItemCommand extends PutItemCommand_base { /** @internal type navigation helper, not in runtime. */ protected static __types: { api: { input: PutItemInput; output: PutItemOutput; }; sdk: { input: PutItemCommandInput; output: PutItemCommandOutput; }; }; }