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 or Select request (read) immediately after a DeleteAttributes or 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.
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 |
|---|---|---|
|
|
The name of the attribute. X can be any positive integer or 0. Type: String. |
Yes |
|
|
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 |
|
|
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: |
No |
DomainName
|
The name of the domain in which to perform the operation. Type: String |
Yes |
|
|
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 Can only be used with single-valued attributes. |
Conditional |
|
|
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 Can only be used with single-valued attributes. |
Conditional |
|
|
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 Can only be used with single-valued attributes. |
Conditional |
Response Elements
Special Errors
| Error | Description |
|---|---|
AttributeDoesNotExist
|
Attribute ("+ name + ") does not exist |
ConditionalCheckFailed
|
Conditional check failed. Attribute (" + name + ") value exists. |
ConditionalCheckFailed
|
Conditional check failed. Attribute ("+ name +") value is ("+ value +") but was expected ("+ expValue +") |
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 (" + value + ") for parameter Expected.Exists is invalid. Expected.Exists should be either true or false.
|
InvalidParameterValue
|
Value (" + value + ") for parameter Name is invalid.The empty string is an illegal attribute name |
InvalidParameterValue
|
Value (" + value + ") for parameter Value is invalid. Value exceeds maximum length of 1024. |
InvalidParameterValue
|
Value (" + value + ") for parameter Name is invalid. Value exceeds maximum length of 1024. |
InvalidParameterValue
|
Value (" + value + ") for parameter Value is invalid. Value exceeds maximum length of 1024. |
InvalidParameterValue
|
Value (" + value + ") for parameter Item is invalid. Value exceeds max length of 1024. |
InvalidParameterValue
|
Value (" + value + ") for parameter Replace is invalid. The Replace flag
should be either true or false. |
InvalidWSDLVersion
|
Parameter (" + parameterName +") 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='<attribute
name>'. |
MissingParameter
|
Attribute.Name missing for Attribute.Value='<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 (" + name + ") 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
<PutAttributesResponse> <ResponseMetadata> <RequestId>490206ce-8292-456c-a00f-61b335eb202b</RequestId> <BoxUsage>0.0000219907</BoxUsage> </ResponseMetadata> </PutAttributesResponse>
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.
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.
<PutAttributesResponse> <ResponseMetadata> <RequestId>490206ce-8292-456c-a00f-61b335eb202b</RequestId> <BoxUsage>0.0000219907</BoxUsage> </ResponseMetadata> </PutAttributesResponse>
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
