« blib/lib/Paws/DynamoDB/UpdateGlobalTableSettingsOutput.pm
↑ Summary
blib/lib/Paws/DynamoDB/UpdateItemOutput.pm »
| 1 | |||
| 2 | package Paws::DynamoDB::UpdateItem; | ||
| 3 | use Moose; | ||
| 4 | has AttributeUpdates => (is => 'ro', isa => 'Paws::DynamoDB::AttributeUpdates'); | ||
| 5 | has ConditionalOperator => (is => 'ro', isa => 'Str'); | ||
| 6 | has ConditionExpression => (is => 'ro', isa => 'Str'); | ||
| 7 | has Expected => (is => 'ro', isa => 'Paws::DynamoDB::ExpectedAttributeMap'); | ||
| 8 | has ExpressionAttributeNames => (is => 'ro', isa => 'Paws::DynamoDB::ExpressionAttributeNameMap'); | ||
| 9 | has ExpressionAttributeValues => (is => 'ro', isa => 'Paws::DynamoDB::ExpressionAttributeValueMap'); | ||
| 10 | has Key => (is => 'ro', isa => 'Paws::DynamoDB::Key', required => 1); | ||
| 11 | has ReturnConsumedCapacity => (is => 'ro', isa => 'Str'); | ||
| 12 | has ReturnItemCollectionMetrics => (is => 'ro', isa => 'Str'); | ||
| 13 | has ReturnValues => (is => 'ro', isa => 'Str'); | ||
| 14 | has TableName => (is => 'ro', isa => 'Str', required => 1); | ||
| 15 | has UpdateExpression => (is => 'ro', isa => 'Str'); | ||
| 16 | |||
| 17 | use MooseX::ClassAttribute; | ||
| 18 | |||
| 19 | class_has _api_call => (isa => 'Str', is => 'ro', default => 'UpdateItem'); | ||
| 20 | class_has _returns => (isa => 'Str', is => 'ro', default => 'Paws::DynamoDB::UpdateItemOutput'); | ||
| 21 | class_has _result_key => (isa => 'Str', is => 'ro'); | ||
| 22 | 1; | ||
| 23 | |||
| 24 | ### main pod documentation begin ### | ||
| 25 | |||
| 26 | =head1 NAME | ||
| 27 | |||
| 28 | Paws::DynamoDB::UpdateItem - Arguments for method UpdateItem on L<Paws::DynamoDB> | ||
| 29 | |||
| 30 | =head1 DESCRIPTION | ||
| 31 | |||
| 32 | This class represents the parameters used for calling the method UpdateItem on the | ||
| 33 | L<Amazon DynamoDB|Paws::DynamoDB> service. Use the attributes of this class | ||
| 34 | as arguments to method UpdateItem. | ||
| 35 | |||
| 36 | You shouldn't make instances of this class. Each attribute should be used as a named argument in the call to UpdateItem. | ||
| 37 | |||
| 38 | =head1 SYNOPSIS | ||
| 39 | |||
| 40 | my $dynamodb = Paws->service('DynamoDB'); | ||
| 41 | # To update an item in a table | ||
| 42 | # This example updates an item in the Music table. It adds a new attribute | ||
| 43 | # (Year) and modifies the AlbumTitle attribute. All of the attributes in the | ||
| 44 | # item, as they appear after the update, are returned in the response. | ||
| 45 | my $UpdateItemOutput = $dynamodb->UpdateItem( | ||
| 46 | 'ExpressionAttributeNames' => { | ||
| 47 | '#AT' => 'AlbumTitle', | ||
| 48 | '#Y' => 'Year' | ||
| 49 | }, | ||
| 50 | 'ExpressionAttributeValues' => { | ||
| 51 | ':t' => { | ||
| 52 | 'S' => 'Louder Than Ever' | ||
| 53 | }, | ||
| 54 | ':y' => { | ||
| 55 | 'N' => 2015 | ||
| 56 | } | ||
| 57 | }, | ||
| 58 | 'Key' => { | ||
| 59 | 'Artist' => { | ||
| 60 | 'S' => 'Acme Band' | ||
| 61 | }, | ||
| 62 | 'SongTitle' => { | ||
| 63 | 'S' => 'Happy Day' | ||
| 64 | } | ||
| 65 | }, | ||
| 66 | 'ReturnValues' => 'ALL_NEW', | ||
| 67 | 'TableName' => 'Music', | ||
| 68 | 'UpdateExpression' => 'SET #Y = :y, #AT = :t' | ||
| 69 | ); | ||
| 70 | |||
| 71 | # Results: | ||
| 72 | my $Attributes = $UpdateItemOutput->Attributes; | ||
| 73 | |||
| 74 | # Returns a L<Paws::DynamoDB::UpdateItemOutput> object. | ||
| 75 | |||
| 76 | Values for attributes that are native types (Int, String, Float, etc) can passed as-is (scalar values). Values for complex Types (objects) can be passed as a HashRef. The keys and values of the hashref will be used to instance the underlying object. | ||
| 77 | For the AWS API documentation, see L<https://docs.aws.amazon.com/goto/WebAPI/dynamodb/UpdateItem> | ||
| 78 | |||
| 79 | =head1 ATTRIBUTES | ||
| 80 | |||
| 81 | |||
| 82 | =head2 AttributeUpdates => L<Paws::DynamoDB::AttributeUpdates> | ||
| 83 | |||
| 84 | This is a legacy parameter. Use C<UpdateExpression> instead. For more | ||
| 85 | information, see AttributeUpdates | ||
| 86 | (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.AttributeUpdates.html) | ||
| 87 | in the I<Amazon DynamoDB Developer Guide>. | ||
| 88 | |||
| 89 | |||
| 90 | |||
| 91 | =head2 ConditionalOperator => Str | ||
| 92 | |||
| 93 | This is a legacy parameter. Use C<ConditionExpression> instead. For | ||
| 94 | more information, see ConditionalOperator | ||
| 95 | (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.ConditionalOperator.html) | ||
| 96 | in the I<Amazon DynamoDB Developer Guide>. | ||
| 97 | |||
| 98 | Valid values are: C<"AND">, C<"OR"> | ||
| 99 | |||
| 100 | =head2 ConditionExpression => Str | ||
| 101 | |||
| 102 | A condition that must be satisfied in order for a conditional update to | ||
| 103 | succeed. | ||
| 104 | |||
| 105 | An expression can contain any of the following: | ||
| 106 | |||
| 107 | =over | ||
| 108 | |||
| 109 | =item * | ||
| 110 | |||
| 111 | Functions: C<attribute_exists | attribute_not_exists | attribute_type | | ||
| 112 | contains | begins_with | size> | ||
| 113 | |||
| 114 | These function names are case-sensitive. | ||
| 115 | |||
| 116 | =item * | ||
| 117 | |||
| 118 | Comparison operators: C<= | E<lt>E<gt> | E<lt> | E<gt> | E<lt>= | | ||
| 119 | E<gt>= | BETWEEN | IN> | ||
| 120 | |||
| 121 | =item * | ||
| 122 | |||
| 123 | Logical operators: C<AND | OR | NOT> | ||
| 124 | |||
| 125 | =back | ||
| 126 | |||
| 127 | For more information about condition expressions, see Specifying | ||
| 128 | Conditions | ||
| 129 | (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.SpecifyingConditions.html) | ||
| 130 | in the I<Amazon DynamoDB Developer Guide>. | ||
| 131 | |||
| 132 | |||
| 133 | |||
| 134 | =head2 Expected => L<Paws::DynamoDB::ExpectedAttributeMap> | ||
| 135 | |||
| 136 | This is a legacy parameter. Use C<ConditionExpression> instead. For | ||
| 137 | more information, see Expected | ||
| 138 | (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.Expected.html) | ||
| 139 | in the I<Amazon DynamoDB Developer Guide>. | ||
| 140 | |||
| 141 | |||
| 142 | |||
| 143 | =head2 ExpressionAttributeNames => L<Paws::DynamoDB::ExpressionAttributeNameMap> | ||
| 144 | |||
| 145 | One or more substitution tokens for attribute names in an expression. | ||
| 146 | The following are some use cases for using C<ExpressionAttributeNames>: | ||
| 147 | |||
| 148 | =over | ||
| 149 | |||
| 150 | =item * | ||
| 151 | |||
| 152 | To access an attribute whose name conflicts with a DynamoDB reserved | ||
| 153 | word. | ||
| 154 | |||
| 155 | =item * | ||
| 156 | |||
| 157 | To create a placeholder for repeating occurrences of an attribute name | ||
| 158 | in an expression. | ||
| 159 | |||
| 160 | =item * | ||
| 161 | |||
| 162 | To prevent special characters in an attribute name from being | ||
| 163 | misinterpreted in an expression. | ||
| 164 | |||
| 165 | =back | ||
| 166 | |||
| 167 | Use the B<#> character in an expression to dereference an attribute | ||
| 168 | name. For example, consider the following attribute name: | ||
| 169 | |||
| 170 | =over | ||
| 171 | |||
| 172 | =item * | ||
| 173 | |||
| 174 | C<Percentile> | ||
| 175 | |||
| 176 | =back | ||
| 177 | |||
| 178 | The name of this attribute conflicts with a reserved word, so it cannot | ||
| 179 | be used directly in an expression. (For the complete list of reserved | ||
| 180 | words, see Reserved Words | ||
| 181 | (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ReservedWords.html) | ||
| 182 | in the I<Amazon DynamoDB Developer Guide>.) To work around this, you | ||
| 183 | could specify the following for C<ExpressionAttributeNames>: | ||
| 184 | |||
| 185 | =over | ||
| 186 | |||
| 187 | =item * | ||
| 188 | |||
| 189 | C<{"#P":"Percentile"}> | ||
| 190 | |||
| 191 | =back | ||
| 192 | |||
| 193 | You could then use this substitution in an expression, as in this | ||
| 194 | example: | ||
| 195 | |||
| 196 | =over | ||
| 197 | |||
| 198 | =item * | ||
| 199 | |||
| 200 | C<#P = :val> | ||
| 201 | |||
| 202 | =back | ||
| 203 | |||
| 204 | Tokens that begin with the B<:> character are I<expression attribute | ||
| 205 | values>, which are placeholders for the actual value at runtime. | ||
| 206 | |||
| 207 | For more information about expression attribute names, see Specifying | ||
| 208 | Item Attributes | ||
| 209 | (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.AccessingItemAttributes.html) | ||
| 210 | in the I<Amazon DynamoDB Developer Guide>. | ||
| 211 | |||
| 212 | |||
| 213 | |||
| 214 | =head2 ExpressionAttributeValues => L<Paws::DynamoDB::ExpressionAttributeValueMap> | ||
| 215 | |||
| 216 | One or more values that can be substituted in an expression. | ||
| 217 | |||
| 218 | Use the B<:> (colon) character in an expression to dereference an | ||
| 219 | attribute value. For example, suppose that you wanted to check whether | ||
| 220 | the value of the C<ProductStatus> attribute was one of the following: | ||
| 221 | |||
| 222 | C<Available | Backordered | Discontinued> | ||
| 223 | |||
| 224 | You would first need to specify C<ExpressionAttributeValues> as | ||
| 225 | follows: | ||
| 226 | |||
| 227 | C<{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, | ||
| 228 | ":disc":{"S":"Discontinued"} }> | ||
| 229 | |||
| 230 | You could then use these values in an expression, such as this: | ||
| 231 | |||
| 232 | C<ProductStatus IN (:avail, :back, :disc)> | ||
| 233 | |||
| 234 | For more information on expression attribute values, see Condition | ||
| 235 | Expressions | ||
| 236 | (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.SpecifyingConditions.html) | ||
| 237 | in the I<Amazon DynamoDB Developer Guide>. | ||
| 238 | |||
| 239 | |||
| 240 | |||
| 241 | =head2 B<REQUIRED> Key => L<Paws::DynamoDB::Key> | ||
| 242 | |||
| 243 | The primary key of the item to be updated. Each element consists of an | ||
| 244 | attribute name and a value for that attribute. | ||
| 245 | |||
| 246 | For the primary key, you must provide all of the attributes. For | ||
| 247 | example, with a simple primary key, you only need to provide a value | ||
| 248 | for the partition key. For a composite primary key, you must provide | ||
| 249 | values for both the partition key and the sort key. | ||
| 250 | |||
| 251 | |||
| 252 | |||
| 253 | =head2 ReturnConsumedCapacity => Str | ||
| 254 | |||
| 255 | |||
| 256 | |||
| 257 | Valid values are: C<"INDEXES">, C<"TOTAL">, C<"NONE"> | ||
| 258 | |||
| 259 | =head2 ReturnItemCollectionMetrics => Str | ||
| 260 | |||
| 261 | Determines whether item collection metrics are returned. If set to | ||
| 262 | C<SIZE>, the response includes statistics about item collections, if | ||
| 263 | any, that were modified during the operation are returned in the | ||
| 264 | response. If set to C<NONE> (the default), no statistics are returned. | ||
| 265 | |||
| 266 | Valid values are: C<"SIZE">, C<"NONE"> | ||
| 267 | |||
| 268 | =head2 ReturnValues => Str | ||
| 269 | |||
| 270 | Use C<ReturnValues> if you want to get the item attributes as they | ||
| 271 | appear before or after they are updated. For C<UpdateItem>, the valid | ||
| 272 | values are: | ||
| 273 | |||
| 274 | =over | ||
| 275 | |||
| 276 | =item * | ||
| 277 | |||
| 278 | C<NONE> - If C<ReturnValues> is not specified, or if its value is | ||
| 279 | C<NONE>, then nothing is returned. (This setting is the default for | ||
| 280 | C<ReturnValues>.) | ||
| 281 | |||
| 282 | =item * | ||
| 283 | |||
| 284 | C<ALL_OLD> - Returns all of the attributes of the item, as they | ||
| 285 | appeared before the UpdateItem operation. | ||
| 286 | |||
| 287 | =item * | ||
| 288 | |||
| 289 | C<UPDATED_OLD> - Returns only the updated attributes, as they appeared | ||
| 290 | before the UpdateItem operation. | ||
| 291 | |||
| 292 | =item * | ||
| 293 | |||
| 294 | C<ALL_NEW> - Returns all of the attributes of the item, as they appear | ||
| 295 | after the UpdateItem operation. | ||
| 296 | |||
| 297 | =item * | ||
| 298 | |||
| 299 | C<UPDATED_NEW> - Returns only the updated attributes, as they appear | ||
| 300 | after the UpdateItem operation. | ||
| 301 | |||
| 302 | =back | ||
| 303 | |||
| 304 | There is no additional cost associated with requesting a return value | ||
| 305 | aside from the small network and processing overhead of receiving a | ||
| 306 | larger response. No read capacity units are consumed. | ||
| 307 | |||
| 308 | The values returned are strongly consistent. | ||
| 309 | |||
| 310 | Valid values are: C<"NONE">, C<"ALL_OLD">, C<"UPDATED_OLD">, C<"ALL_NEW">, C<"UPDATED_NEW"> | ||
| 311 | |||
| 312 | =head2 B<REQUIRED> TableName => Str | ||
| 313 | |||
| 314 | The name of the table containing the item to update. | ||
| 315 | |||
| 316 | |||
| 317 | |||
| 318 | =head2 UpdateExpression => Str | ||
| 319 | |||
| 320 | An expression that defines one or more attributes to be updated, the | ||
| 321 | action to be performed on them, and new values for them. | ||
| 322 | |||
| 323 | The following action values are available for C<UpdateExpression>. | ||
| 324 | |||
| 325 | =over | ||
| 326 | |||
| 327 | =item * | ||
| 328 | |||
| 329 | C<SET> - Adds one or more attributes and values to an item. If any of | ||
| 330 | these attributes already exist, they are replaced by the new values. | ||
| 331 | You can also use C<SET> to add or subtract from an attribute that is of | ||
| 332 | type Number. For example: C<SET myNum = myNum + :val> | ||
| 333 | |||
| 334 | C<SET> supports the following functions: | ||
| 335 | |||
| 336 | =over | ||
| 337 | |||
| 338 | =item * | ||
| 339 | |||
| 340 | C<if_not_exists (path, operand)> - if the item does not contain an | ||
| 341 | attribute at the specified path, then C<if_not_exists> evaluates to | ||
| 342 | operand; otherwise, it evaluates to path. You can use this function to | ||
| 343 | avoid overwriting an attribute that may already be present in the item. | ||
| 344 | |||
| 345 | =item * | ||
| 346 | |||
| 347 | C<list_append (operand, operand)> - evaluates to a list with a new | ||
| 348 | element added to it. You can append the new element to the start or the | ||
| 349 | end of the list by reversing the order of the operands. | ||
| 350 | |||
| 351 | =back | ||
| 352 | |||
| 353 | These function names are case-sensitive. | ||
| 354 | |||
| 355 | =item * | ||
| 356 | |||
| 357 | C<REMOVE> - Removes one or more attributes from an item. | ||
| 358 | |||
| 359 | =item * | ||
| 360 | |||
| 361 | C<ADD> - Adds the specified value to the item, if the attribute does | ||
| 362 | not already exist. If the attribute does exist, then the behavior of | ||
| 363 | C<ADD> depends on the data type of the attribute: | ||
| 364 | |||
| 365 | =over | ||
| 366 | |||
| 367 | =item * | ||
| 368 | |||
| 369 | If the existing attribute is a number, and if C<Value> is also a | ||
| 370 | number, then C<Value> is mathematically added to the existing | ||
| 371 | attribute. If C<Value> is a negative number, then it is subtracted from | ||
| 372 | the existing attribute. | ||
| 373 | |||
| 374 | If you use C<ADD> to increment or decrement a number value for an item | ||
| 375 | that doesn't exist before the update, DynamoDB uses C<0> as the initial | ||
| 376 | value. | ||
| 377 | |||
| 378 | Similarly, if you use C<ADD> for an existing item to increment or | ||
| 379 | decrement an attribute value that doesn't exist before the update, | ||
| 380 | DynamoDB uses C<0> as the initial value. For example, suppose that the | ||
| 381 | item you want to update doesn't have an attribute named C<itemcount>, | ||
| 382 | but you decide to C<ADD> the number C<3> to this attribute anyway. | ||
| 383 | DynamoDB will create the C<itemcount> attribute, set its initial value | ||
| 384 | to C<0>, and finally add C<3> to it. The result will be a new | ||
| 385 | C<itemcount> attribute in the item, with a value of C<3>. | ||
| 386 | |||
| 387 | =item * | ||
| 388 | |||
| 389 | If the existing data type is a set and if C<Value> is also a set, then | ||
| 390 | C<Value> is added to the existing set. For example, if the attribute | ||
| 391 | value is the set C<[1,2]>, and the C<ADD> action specified C<[3]>, then | ||
| 392 | the final attribute value is C<[1,2,3]>. An error occurs if an C<ADD> | ||
| 393 | action is specified for a set attribute and the attribute type | ||
| 394 | specified does not match the existing set type. | ||
| 395 | |||
| 396 | Both sets must have the same primitive data type. For example, if the | ||
| 397 | existing data type is a set of strings, the C<Value> must also be a set | ||
| 398 | of strings. | ||
| 399 | |||
| 400 | =back | ||
| 401 | |||
| 402 | The C<ADD> action only supports Number and set data types. In addition, | ||
| 403 | C<ADD> can only be used on top-level attributes, not nested attributes. | ||
| 404 | |||
| 405 | =item * | ||
| 406 | |||
| 407 | C<DELETE> - Deletes an element from a set. | ||
| 408 | |||
| 409 | If a set of values is specified, then those values are subtracted from | ||
| 410 | the old set. For example, if the attribute value was the set C<[a,b,c]> | ||
| 411 | and the C<DELETE> action specifies C<[a,c]>, then the final attribute | ||
| 412 | value is C<[b]>. Specifying an empty set is an error. | ||
| 413 | |||
| 414 | The C<DELETE> action only supports set data types. In addition, | ||
| 415 | C<DELETE> can only be used on top-level attributes, not nested | ||
| 416 | attributes. | ||
| 417 | |||
| 418 | =back | ||
| 419 | |||
| 420 | You can have many actions in a single expression, such as the | ||
| 421 | following: C<SET a=:value1, b=:value2 DELETE :value3, :value4, :value5> | ||
| 422 | |||
| 423 | For more information on update expressions, see Modifying Items and | ||
| 424 | Attributes | ||
| 425 | (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html) | ||
| 426 | in the I<Amazon DynamoDB Developer Guide>. | ||
| 427 | |||
| 428 | |||
| 429 | |||
| 430 | |||
| 431 | =head1 SEE ALSO | ||
| 432 | |||
| 433 | This class forms part of L<Paws>, documenting arguments for method UpdateItem in L<Paws::DynamoDB> | ||
| 434 | |||
| 435 | =head1 BUGS and CONTRIBUTIONS | ||
| 436 | |||
| 437 | The source code is located here: L<https://github.com/pplu/aws-sdk-perl> | ||
| 438 | |||
| 439 | Please report bugs to: L<https://github.com/pplu/aws-sdk-perl/issues> | ||
| 440 | |||
| 441 | =cut | ||
| 442 |