# PutAttributes ## Description The `PutAttributes` operation creates or replaces attributes in an item. You specify new attributes using a combination of the `Attribute.X.Name` and `Attribute.X.Value` parameters. You specify the first attribute by the parameters `Attribute.1.Name` and `Attribute.1.Value`, the second attribute by the parameters `Attribute.2.Name` and `Attribute.2.Value`, and so on. Attributes are uniquely identified in an item by their name/value combination. For example, a single item can have the attributes `{ "first_name", "first_value" }` and ` { "first_name", second_value" }`. However, it cannot have two attribute instances where both the `Attribute.X.Name` and `Attribute.X.Value` are the same. Optionally, the requester can supply the `Replace` parameter for each individual attribute. Setting this value to `true` causes the new attribute value to replace the existing attribute value(s). For example, if an item has the attributes `{ 'a', '1' }`, `{ 'b', '2'}` and `{ 'b', '3' }` and the requester calls `PutAttributes` using the attributes `{ 'b', '4' }` with the `Replace` parameter set to `true`, the final attributes of the item are changed to `{ 'a', '1' }` and `{ 'b', '4' }`, which replaces the previous values of the `'b'` attribute with the new value. Conditional updates are useful for ensuring multiple processes do not overwrite each other. To prevent this from occurring, you can specify the expected attribute name and value. If they match, Amazon SimpleDB performs the update. Otherwise, the update does not occur. **Note** Using `PutAttributes` to replace attribute values that do not exist will *not* result in an error response. You cannot specify an empty string as an attribute name. When using eventually consistent reads, a [GetAttributes](SDB_API_GetAttributes.md) or [Select](SDB_API_Select.md) request (read) immediately after a [DeleteAttributes](SDB_API_DeleteAttributes.md) or [PutAttributes](#SDB_API_PutAttributes) request (write) might not return the updated data. A consistent read always reflects all writes that received a successful response prior to the read. For more information, see [Consistency](ConsistencySummary.md). You can perform the expected conditional check on one attribute per operation. The following limitations are enforced for this operation: + 256 total attribute name-value pairs per item + One billion attributes per domain + 10 GB of total user data storage per domain ## Request Parameters | Name | Description | Required | | --- | --- | --- | | `Attribute.X.Name` | The name of the attribute. X can be any positive integer or 0. Type: String. | Yes | | `Attribute.X.Value` | The value of the attribute. X can be any positive integer or 0. Type: String. | Yes | | ItemName | The name of the item. Type: String. | Yes | | `Attribute.X.Replace` | Flag to specify whether to replace the Attribute/Value or to add a new Attribute/Value. X can be any positive integer or 0. Type: Boolean. Default: `false`. | No | | DomainName | The name of the domain in which to perform the operation. Type: String | Yes | | `Expected.Name` | Name of the attribute to check. Type: String. Conditions: Must be used with the expected value or expected exists parameter. When used with the expected value parameter, you specify the value to check. When expected exists is set to `true` and it is used with the expected value parameter, it performs similarly to just using the expected value parameter. When expected exists is set to `false`, the operation is performed if the expected attribute is not present. Can only be used with single-valued attributes. | Conditional | | `Expected.Value` | Value of the attribute to check. Type: String. Conditions: Must be used with the expected name parameter. Can be used with the expected exists parameter if that parameter is set to `true`. Can only be used with single-valued attributes. | Conditional | | `Expected.Exists` | Flag to test the existence of an attribute while performing conditional updates. Type: Boolean. Conditions: Must be used with the expected name parameter. When set to `true`, this must be used with the expected value parameter. When set to `false`, this cannot be used with the expected value parameter. Can only be used with single-valued attributes. | Conditional | ## Response Elements See [Common Response Elements](SDB_API_CommonResponseElements.md). ## Special Errors | Error | Description | | --- | --- | | AttributeDoesNotExist | Attribute ("\$1 name \$1 ") does not exist | | ConditionalCheckFailed | Conditional check failed. Attribute (" \$1 name \$1 ") value exists. | | ConditionalCheckFailed | Conditional check failed. Attribute ("\$1 name \$1") value is ("\$1 value \$1") but was expected ("\$1 expValue \$1") | | ExistsAndExpectedValue | Expected.Exists=false and Expected.Value cannot be specified together | | IncompleteExpectedExpression | If Expected.Exists=true or unspecified, then Expected.Value has to be specified | | InvalidParameterValue | Value (" \$1 value \$1 ") for parameter Expected.Exists is invalid. Expected.Exists should be either true or false. | | InvalidParameterValue | Value (" \$1 value \$1 ") for parameter Name is invalid.The empty string is an illegal attribute name | | InvalidParameterValue | Value (" \$1 value \$1 ") for parameter Value is invalid. Value exceeds maximum length of 1024. | | InvalidParameterValue | Value (" \$1 value \$1 ") for parameter Name is invalid. Value exceeds maximum length of 1024. | | InvalidParameterValue | Value (" \$1 value \$1 ") for parameter Value is invalid. Value exceeds maximum length of 1024. | | InvalidParameterValue | Value (" \$1 value \$1 ") for parameter Item is invalid. Value exceeds max length of 1024. | | InvalidParameterValue | Value (" \$1 value \$1 ") for parameter Replace is invalid. The Replace flag should be either true or false. | | InvalidWSDLVersion | Parameter (" \$1 parameterName \$1") is only supported in WSDL version 2009-04-15 or beyond. Please upgrade to new version | | MissingParameter | The request must contain the parameter Name | | MissingParameter | The request must contain the parameter DomainName. | | MissingParameter | The request must contain the parameter ItemName. | | MissingParameter | Attribute.Value missing for Attribute.Name=''. | | MissingParameter | Attribute.Name missing for Attribute.Value=''. | | MultipleExistsConditions | Only one Exists condition can be specified | | MultipleExpectedNames | Only one Expected.Name can be specified | | MultipleExpectedValues | Only one Expected.Value can be specified | | MultiValuedAttribute | Attribute (" \$1 name \$1 ") is multi-valued. Conditional check can only be performed on a single-valued attribute | | NoSuchDomain | The specified domain does not exist. | | NumberItemAttributesExceeded | Too many attributes in this item. | | NumberDomainAttributesExceeded | Too many attributes in this domain. | | NumberDomainBytesExceeded | Too many bytes in this domain. | ## Examples ### Sample Request The following example uses `PutAttributes` on `Item123`, which has attributes `(Color=Blue)`, `(Size=Med)`, and `(Price=0014.99)` in `MyDomain`. If `Item123` already had the `Price` attribute, this operation would replace the values for that attribute. ``` https://sdb.amazonaws.com/ ?Action=PutAttributes &Attribute.1.Name=Color &Attribute.1.Value=Blue &Attribute.2.Name=Size &Attribute.2.Value=Med &Attribute.3.Name=Price &Attribute.3.Value=0014.99 &Attribute.3.Replace=true &AWSAccessKeyId=[valid access key id] &DomainName=MyDomain &ItemName=Item123 &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Timestamp=2010-01-25T15%3A03%3A05-07%3A00 &Version=2009-04-15 &Signature=[valid signature] ``` ### Sample Response ``` 490206ce-8292-456c-a00f-61b335eb202b 0.0000219907 ``` ### Sample Request The following example uses conditional updates to ensure that multiple processes do not overwrite each other’s settings. For example, if two people are buying the `JumboFez` item at the same time, the following ensures that the inventory is decremented correctly. **Note** For more examples of conditional operations, see [Conditionally Putting and Deleting Data](ConditionalPutDelete.md). ``` https://sdb.amazonaws.com/ ?Action=PutAttributes &DomainName=MyDomain &ItemName=JumboFez &Attribute.1.Name=quantity &Attribute.1.Value=14 &Attribute.1.Replace=true &Expected.Name=quantity &Expected.Value=15 &AWSAccessKeyId=[valid access key id] &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Timestamp=2010-01-25T15%3A03%3A05-07%3A00 &Version=2009-04-15 &Signature=[valid signature] ``` ### Sample Response If the update condition is met, Amazon SimpleDB returns output similar to the following. ``` 490206ce-8292-456c-a00f-61b335eb202b 0.0000219907 ``` In this example, one of the servers updates the value and the other receives an error. The server that receives the error resubmits the request specifying a value of 13 and an expected value of 14, ensuring that the inventory is correctly set. ## Related Actions + [DeleteAttributes](SDB_API_DeleteAttributes.md) + [GetAttributes](SDB_API_GetAttributes.md)