1# Copyright (c) 2014 Amazon.com, Inc. or its affiliates. All Rights Reserved 2# 3# Permission is hereby granted, free of charge, to any person obtaining a 4# copy of this software and associated documentation files (the 5# "Software"), to deal in the Software without restriction, including 6# without limitation the rights to use, copy, modify, merge, publish, dis- 7# tribute, sublicense, and/or sell copies of the Software, and to permit 8# persons to whom the Software is furnished to do so, subject to the fol- 9# lowing conditions: 10# 11# The above copyright notice and this permission notice shall be included 12# in all copies or substantial portions of the Software. 13# 14# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 15# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL- 16# ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 17# SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 18# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 19# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 20# IN THE SOFTWARE. 21# 22from binascii import crc32 23 24import boto 25from boto.compat import json 26from boto.connection import AWSQueryConnection 27from boto.regioninfo import RegionInfo 28from boto.exception import JSONResponseError 29from boto.dynamodb2 import exceptions 30 31 32class DynamoDBConnection(AWSQueryConnection): 33 """ 34 Amazon DynamoDB 35 **Overview** 36 37 This is the Amazon DynamoDB API Reference. This guide provides 38 descriptions and samples of the low-level DynamoDB API. For 39 information about DynamoDB application development, go to the 40 `Amazon DynamoDB Developer Guide`_. 41 42 Instead of making the requests to the low-level DynamoDB API 43 directly from your application, we recommend that you use the AWS 44 Software Development Kits (SDKs). The easy-to-use libraries in the 45 AWS SDKs make it unnecessary to call the low-level DynamoDB API 46 directly from your application. The libraries take care of request 47 authentication, serialization, and connection management. For more 48 information, go to `Using the AWS SDKs with DynamoDB`_ in the 49 Amazon DynamoDB Developer Guide . 50 51 If you decide to code against the low-level DynamoDB API directly, 52 you will need to write the necessary code to authenticate your 53 requests. For more information on signing your requests, go to 54 `Using the DynamoDB API`_ in the Amazon DynamoDB Developer Guide . 55 56 The following are short descriptions of each low-level API action, 57 organized by function. 58 59 **Managing Tables** 60 61 62 + CreateTable - Creates a table with user-specified provisioned 63 throughput settings. You must designate one attribute as the hash 64 primary key for the table; you can optionally designate a second 65 attribute as the range primary key. DynamoDB creates indexes on 66 these key attributes for fast data access. Optionally, you can 67 create one or more secondary indexes, which provide fast data 68 access using non-key attributes. 69 + DescribeTable - Returns metadata for a table, such as table 70 size, status, and index information. 71 + UpdateTable - Modifies the provisioned throughput settings for a 72 table. Optionally, you can modify the provisioned throughput 73 settings for global secondary indexes on the table. 74 + ListTables - Returns a list of all tables associated with the 75 current AWS account and endpoint. 76 + DeleteTable - Deletes a table and all of its indexes. 77 78 79 For conceptual information about managing tables, go to `Working 80 with Tables`_ in the Amazon DynamoDB Developer Guide . 81 82 **Reading Data** 83 84 85 + GetItem - Returns a set of attributes for the item that has a 86 given primary key. By default, GetItem performs an eventually 87 consistent read; however, applications can specify a strongly 88 consistent read instead. 89 + BatchGetItem - Performs multiple GetItem requests for data items 90 using their primary keys, from one table or multiple tables. The 91 response from BatchGetItem has a size limit of 16 MB and returns a 92 maximum of 100 items. Both eventually consistent and strongly 93 consistent reads can be used. 94 + Query - Returns one or more items from a table or a secondary 95 index. You must provide a specific hash key value. You can narrow 96 the scope of the query using comparison operators against a range 97 key value, or on the index key. Query supports either eventual or 98 strong consistency. A single response has a size limit of 1 MB. 99 + Scan - Reads every item in a table; the result set is eventually 100 consistent. You can limit the number of items returned by 101 filtering the data attributes, using conditional expressions. Scan 102 can be used to enable ad-hoc querying of a table against non-key 103 attributes; however, since this is a full table scan without using 104 an index, Scan should not be used for any application query use 105 case that requires predictable performance. 106 107 108 For conceptual information about reading data, go to `Working with 109 Items`_ and `Query and Scan Operations`_ in the Amazon DynamoDB 110 Developer Guide . 111 112 **Modifying Data** 113 114 115 + PutItem - Creates a new item, or replaces an existing item with 116 a new item (including all the attributes). By default, if an item 117 in the table already exists with the same primary key, the new 118 item completely replaces the existing item. You can use 119 conditional operators to replace an item only if its attribute 120 values match certain conditions, or to insert a new item only if 121 that item doesn't already exist. 122 + UpdateItem - Modifies the attributes of an existing item. You 123 can also use conditional operators to perform an update only if 124 the item's attribute values match certain conditions. 125 + DeleteItem - Deletes an item in a table by primary key. You can 126 use conditional operators to perform a delete an item only if the 127 item's attribute values match certain conditions. 128 + BatchWriteItem - Performs multiple PutItem and DeleteItem 129 requests across multiple tables in a single request. A failure of 130 any request(s) in the batch will not cause the entire 131 BatchWriteItem operation to fail. Supports batches of up to 25 132 items to put or delete, with a maximum total request size of 16 133 MB. 134 135 136 For conceptual information about modifying data, go to `Working 137 with Items`_ and `Query and Scan Operations`_ in the Amazon 138 DynamoDB Developer Guide . 139 """ 140 APIVersion = "2012-08-10" 141 DefaultRegionName = "us-east-1" 142 DefaultRegionEndpoint = "dynamodb.us-east-1.amazonaws.com" 143 ServiceName = "DynamoDB" 144 TargetPrefix = "DynamoDB_20120810" 145 ResponseError = JSONResponseError 146 147 _faults = { 148 "ProvisionedThroughputExceededException": exceptions.ProvisionedThroughputExceededException, 149 "LimitExceededException": exceptions.LimitExceededException, 150 "ConditionalCheckFailedException": exceptions.ConditionalCheckFailedException, 151 "ResourceInUseException": exceptions.ResourceInUseException, 152 "ResourceNotFoundException": exceptions.ResourceNotFoundException, 153 "InternalServerError": exceptions.InternalServerError, 154 "ItemCollectionSizeLimitExceededException": exceptions.ItemCollectionSizeLimitExceededException, 155 } 156 157 NumberRetries = 10 158 159 160 def __init__(self, **kwargs): 161 region = kwargs.pop('region', None) 162 validate_checksums = kwargs.pop('validate_checksums', True) 163 if not region: 164 region_name = boto.config.get('DynamoDB', 'region', 165 self.DefaultRegionName) 166 for reg in boto.dynamodb2.regions(): 167 if reg.name == region_name: 168 region = reg 169 break 170 171 # Only set host if it isn't manually overwritten 172 if 'host' not in kwargs: 173 kwargs['host'] = region.endpoint 174 175 super(DynamoDBConnection, self).__init__(**kwargs) 176 self.region = region 177 self._validate_checksums = boto.config.getbool( 178 'DynamoDB', 'validate_checksums', validate_checksums) 179 self.throughput_exceeded_events = 0 180 181 def _required_auth_capability(self): 182 return ['hmac-v4'] 183 184 def batch_get_item(self, request_items, return_consumed_capacity=None): 185 """ 186 The BatchGetItem operation returns the attributes of one or 187 more items from one or more tables. You identify requested 188 items by primary key. 189 190 A single operation can retrieve up to 16 MB of data, which can 191 contain as many as 100 items. BatchGetItem will return a 192 partial result if the response size limit is exceeded, the 193 table's provisioned throughput is exceeded, or an internal 194 processing failure occurs. If a partial result is returned, 195 the operation returns a value for UnprocessedKeys . You can 196 use this value to retry the operation starting with the next 197 item to get. 198 199 For example, if you ask to retrieve 100 items, but each 200 individual item is 300 KB in size, the system returns 52 items 201 (so as not to exceed the 16 MB limit). It also returns an 202 appropriate UnprocessedKeys value so you can get the next page 203 of results. If desired, your application can include its own 204 logic to assemble the pages of results into one data set. 205 206 If none of the items can be processed due to insufficient 207 provisioned throughput on all of the tables in the request, 208 then BatchGetItem will return a 209 ProvisionedThroughputExceededException . If at least one of 210 the items is successfully processed, then BatchGetItem 211 completes successfully, while returning the keys of the unread 212 items in UnprocessedKeys . 213 214 If DynamoDB returns any unprocessed items, you should retry 215 the batch operation on those items. However, we strongly 216 recommend that you use an exponential backoff algorithm . If 217 you retry the batch operation immediately, the underlying read 218 or write requests can still fail due to throttling on the 219 individual tables. If you delay the batch operation using 220 exponential backoff, the individual requests in the batch are 221 much more likely to succeed. 222 223 For more information, go to `Batch Operations and Error 224 Handling`_ in the Amazon DynamoDB Developer Guide . 225 226 By default, BatchGetItem performs eventually consistent reads 227 on every table in the request. If you want strongly consistent 228 reads instead, you can set ConsistentRead to `True` for any or 229 all tables. 230 231 In order to minimize response latency, BatchGetItem retrieves 232 items in parallel. 233 234 When designing your application, keep in mind that DynamoDB 235 does not return attributes in any particular order. To help 236 parse the response by item, include the primary key values for 237 the items in your request in the AttributesToGet parameter. 238 239 If a requested item does not exist, it is not returned in the 240 result. Requests for nonexistent items consume the minimum 241 read capacity units according to the type of read. For more 242 information, see `Capacity Units Calculations`_ in the Amazon 243 DynamoDB Developer Guide . 244 245 :type request_items: map 246 :param request_items: 247 A map of one or more table names and, for each table, the corresponding 248 primary keys for the items to retrieve. Each table name can be 249 invoked only once. 250 251 Each element in the map consists of the following: 252 253 254 + Keys - An array of primary key attribute values that define specific 255 items in the table. For each primary key, you must provide all of 256 the key attributes. For example, with a hash type primary key, you 257 only need to specify the hash attribute. For a hash-and-range type 258 primary key, you must specify both the hash attribute and the range 259 attribute. 260 + AttributesToGet - One or more attributes to be retrieved from the 261 table. By default, all attributes are returned. If a specified 262 attribute is not found, it does not appear in the result. Note that 263 AttributesToGet has no effect on provisioned throughput 264 consumption. DynamoDB determines capacity units consumed based on 265 item size, not on the amount of data that is returned to an 266 application. 267 + ConsistentRead - If `True`, a strongly consistent read is used; if 268 `False` (the default), an eventually consistent read is used. 269 270 :type return_consumed_capacity: string 271 :param return_consumed_capacity: A value that if set to `TOTAL`, the 272 response includes ConsumedCapacity data for tables and indexes. If 273 set to `INDEXES`, the response includes ConsumedCapacity for 274 indexes. If set to `NONE` (the default), ConsumedCapacity is not 275 included in the response. 276 277 """ 278 params = {'RequestItems': request_items, } 279 if return_consumed_capacity is not None: 280 params['ReturnConsumedCapacity'] = return_consumed_capacity 281 return self.make_request(action='BatchGetItem', 282 body=json.dumps(params)) 283 284 def batch_write_item(self, request_items, return_consumed_capacity=None, 285 return_item_collection_metrics=None): 286 """ 287 The BatchWriteItem operation puts or deletes multiple items in 288 one or more tables. A single call to BatchWriteItem can write 289 up to 16 MB of data, which can comprise as many as 25 put or 290 delete requests. Individual items to be written can be as 291 large as 400 KB. 292 293 294 BatchWriteItem cannot update items. To update items, use the 295 UpdateItem API. 296 297 298 The individual PutItem and DeleteItem operations specified in 299 BatchWriteItem are atomic; however BatchWriteItem as a whole 300 is not. If any requested operations fail because the table's 301 provisioned throughput is exceeded or an internal processing 302 failure occurs, the failed operations are returned in the 303 UnprocessedItems response parameter. You can investigate and 304 optionally resend the requests. Typically, you would call 305 BatchWriteItem in a loop. Each iteration would check for 306 unprocessed items and submit a new BatchWriteItem request with 307 those unprocessed items until all items have been processed. 308 309 Note that if none of the items can be processed due to 310 insufficient provisioned throughput on all of the tables in 311 the request, then BatchWriteItem will return a 312 ProvisionedThroughputExceededException . 313 314 If DynamoDB returns any unprocessed items, you should retry 315 the batch operation on those items. However, we strongly 316 recommend that you use an exponential backoff algorithm . If 317 you retry the batch operation immediately, the underlying read 318 or write requests can still fail due to throttling on the 319 individual tables. If you delay the batch operation using 320 exponential backoff, the individual requests in the batch are 321 much more likely to succeed. 322 323 For more information, go to `Batch Operations and Error 324 Handling`_ in the Amazon DynamoDB Developer Guide . 325 326 With BatchWriteItem , you can efficiently write or delete 327 large amounts of data, such as from Amazon Elastic MapReduce 328 (EMR), or copy data from another database into DynamoDB. In 329 order to improve performance with these large-scale 330 operations, BatchWriteItem does not behave in the same way as 331 individual PutItem and DeleteItem calls would For example, you 332 cannot specify conditions on individual put and delete 333 requests, and BatchWriteItem does not return deleted items in 334 the response. 335 336 If you use a programming language that supports concurrency, 337 such as Java, you can use threads to write items in parallel. 338 Your application must include the necessary logic to manage 339 the threads. With languages that don't support threading, such 340 as PHP, you must update or delete the specified items one at a 341 time. In both situations, BatchWriteItem provides an 342 alternative where the API performs the specified put and 343 delete operations in parallel, giving you the power of the 344 thread pool approach without having to introduce complexity 345 into your application. 346 347 Parallel processing reduces latency, but each specified put 348 and delete request consumes the same number of write capacity 349 units whether it is processed in parallel or not. Delete 350 operations on nonexistent items consume one write capacity 351 unit. 352 353 If one or more of the following is true, DynamoDB rejects the 354 entire batch write operation: 355 356 357 + One or more tables specified in the BatchWriteItem request 358 does not exist. 359 + Primary key attributes specified on an item in the request 360 do not match those in the corresponding table's primary key 361 schema. 362 + You try to perform multiple operations on the same item in 363 the same BatchWriteItem request. For example, you cannot put 364 and delete the same item in the same BatchWriteItem request. 365 + There are more than 25 requests in the batch. 366 + Any individual item in a batch exceeds 400 KB. 367 + The total request size exceeds 16 MB. 368 369 :type request_items: map 370 :param request_items: 371 A map of one or more table names and, for each table, a list of 372 operations to be performed ( DeleteRequest or PutRequest ). Each 373 element in the map consists of the following: 374 375 376 + DeleteRequest - Perform a DeleteItem operation on the specified item. 377 The item to be deleted is identified by a Key subelement: 378 379 + Key - A map of primary key attribute values that uniquely identify 380 the ! item. Each entry in this map consists of an attribute name 381 and an attribute value. For each primary key, you must provide all 382 of the key attributes. For example, with a hash type primary key, 383 you only need to specify the hash attribute. For a hash-and-range 384 type primary key, you must specify both the hash attribute and the 385 range attribute. 386 387 + PutRequest - Perform a PutItem operation on the specified item. The 388 item to be put is identified by an Item subelement: 389 390 + Item - A map of attributes and their values. Each entry in this map 391 consists of an attribute name and an attribute value. Attribute 392 values must not be null; string and binary type attributes must 393 have lengths greater than zero; and set type attributes must not be 394 empty. Requests that contain empty values will be rejected with a 395 ValidationException exception. If you specify any attributes that 396 are part of an index key, then the data types for those attributes 397 must match those of the schema in the table's attribute definition. 398 399 :type return_consumed_capacity: string 400 :param return_consumed_capacity: A value that if set to `TOTAL`, the 401 response includes ConsumedCapacity data for tables and indexes. If 402 set to `INDEXES`, the response includes ConsumedCapacity for 403 indexes. If set to `NONE` (the default), ConsumedCapacity is not 404 included in the response. 405 406 :type return_item_collection_metrics: string 407 :param return_item_collection_metrics: A value that if set to `SIZE`, 408 the response includes statistics about item collections, if any, 409 that were modified during the operation are returned in the 410 response. If set to `NONE` (the default), no statistics are 411 returned. 412 413 """ 414 params = {'RequestItems': request_items, } 415 if return_consumed_capacity is not None: 416 params['ReturnConsumedCapacity'] = return_consumed_capacity 417 if return_item_collection_metrics is not None: 418 params['ReturnItemCollectionMetrics'] = return_item_collection_metrics 419 return self.make_request(action='BatchWriteItem', 420 body=json.dumps(params)) 421 422 def create_table(self, attribute_definitions, table_name, key_schema, 423 provisioned_throughput, local_secondary_indexes=None, 424 global_secondary_indexes=None): 425 """ 426 The CreateTable operation adds a new table to your account. In 427 an AWS account, table names must be unique within each region. 428 That is, you can have two tables with same name if you create 429 the tables in different regions. 430 431 CreateTable is an asynchronous operation. Upon receiving a 432 CreateTable request, DynamoDB immediately returns a response 433 with a TableStatus of `CREATING`. After the table is created, 434 DynamoDB sets the TableStatus to `ACTIVE`. You can perform 435 read and write operations only on an `ACTIVE` table. 436 437 You can optionally define secondary indexes on the new table, 438 as part of the CreateTable operation. If you want to create 439 multiple tables with secondary indexes on them, you must 440 create the tables sequentially. Only one table with secondary 441 indexes can be in the `CREATING` state at any given time. 442 443 You can use the DescribeTable API to check the table status. 444 445 :type attribute_definitions: list 446 :param attribute_definitions: An array of attributes that describe the 447 key schema for the table and indexes. 448 449 :type table_name: string 450 :param table_name: The name of the table to create. 451 452 :type key_schema: list 453 :param key_schema: Specifies the attributes that make up the primary 454 key for a table or an index. The attributes in KeySchema must also 455 be defined in the AttributeDefinitions array. For more information, 456 see `Data Model`_ in the Amazon DynamoDB Developer Guide . 457 Each KeySchemaElement in the array is composed of: 458 459 460 + AttributeName - The name of this key attribute. 461 + KeyType - Determines whether the key attribute is `HASH` or `RANGE`. 462 463 464 For a primary key that consists of a hash attribute, you must specify 465 exactly one element with a KeyType of `HASH`. 466 467 For a primary key that consists of hash and range attributes, you must 468 specify exactly two elements, in this order: The first element must 469 have a KeyType of `HASH`, and the second element must have a 470 KeyType of `RANGE`. 471 472 For more information, see `Specifying the Primary Key`_ in the Amazon 473 DynamoDB Developer Guide . 474 475 :type local_secondary_indexes: list 476 :param local_secondary_indexes: 477 One or more local secondary indexes (the maximum is five) to be created 478 on the table. Each index is scoped to a given hash key value. There 479 is a 10 GB size limit per hash key; otherwise, the size of a local 480 secondary index is unconstrained. 481 482 Each local secondary index in the array includes the following: 483 484 485 + IndexName - The name of the local secondary index. Must be unique 486 only for this table. 487 + KeySchema - Specifies the key schema for the local secondary index. 488 The key schema must begin with the same hash key attribute as the 489 table. 490 + Projection - Specifies attributes that are copied (projected) from 491 the table into the index. These are in addition to the primary key 492 attributes and index key attributes, which are automatically 493 projected. Each attribute specification is composed of: 494 495 + ProjectionType - One of the following: 496 497 + `KEYS_ONLY` - Only the index and primary keys are projected into the 498 index. 499 + `INCLUDE` - Only the specified table attributes are projected into 500 the index. The list of projected attributes are in NonKeyAttributes 501 . 502 + `ALL` - All of the table attributes are projected into the index. 503 504 + NonKeyAttributes - A list of one or more non-key attribute names that 505 are projected into the secondary index. The total count of 506 attributes specified in NonKeyAttributes , summed across all of the 507 secondary indexes, must not exceed 20. If you project the same 508 attribute into two different indexes, this counts as two distinct 509 attributes when determining the total. 510 511 :type global_secondary_indexes: list 512 :param global_secondary_indexes: 513 One or more global secondary indexes (the maximum is five) to be 514 created on the table. Each global secondary index in the array 515 includes the following: 516 517 518 + IndexName - The name of the global secondary index. Must be unique 519 only for this table. 520 + KeySchema - Specifies the key schema for the global secondary index. 521 + Projection - Specifies attributes that are copied (projected) from 522 the table into the index. These are in addition to the primary key 523 attributes and index key attributes, which are automatically 524 projected. Each attribute specification is composed of: 525 526 + ProjectionType - One of the following: 527 528 + `KEYS_ONLY` - Only the index and primary keys are projected into the 529 index. 530 + `INCLUDE` - Only the specified table attributes are projected into 531 the index. The list of projected attributes are in NonKeyAttributes 532 . 533 + `ALL` - All of the table attributes are projected into the index. 534 535 + NonKeyAttributes - A list of one or more non-key attribute names that 536 are projected into the secondary index. The total count of 537 attributes specified in NonKeyAttributes , summed across all of the 538 secondary indexes, must not exceed 20. If you project the same 539 attribute into two different indexes, this counts as two distinct 540 attributes when determining the total. 541 542 + ProvisionedThroughput - The provisioned throughput settings for the 543 global secondary index, consisting of read and write capacity 544 units. 545 546 :type provisioned_throughput: dict 547 :param provisioned_throughput: Represents the provisioned throughput 548 settings for a specified table or index. The settings can be 549 modified using the UpdateTable operation. 550 For current minimum and maximum provisioned throughput values, see 551 `Limits`_ in the Amazon DynamoDB Developer Guide . 552 553 """ 554 params = { 555 'AttributeDefinitions': attribute_definitions, 556 'TableName': table_name, 557 'KeySchema': key_schema, 558 'ProvisionedThroughput': provisioned_throughput, 559 } 560 if local_secondary_indexes is not None: 561 params['LocalSecondaryIndexes'] = local_secondary_indexes 562 if global_secondary_indexes is not None: 563 params['GlobalSecondaryIndexes'] = global_secondary_indexes 564 return self.make_request(action='CreateTable', 565 body=json.dumps(params)) 566 567 def delete_item(self, table_name, key, expected=None, 568 conditional_operator=None, return_values=None, 569 return_consumed_capacity=None, 570 return_item_collection_metrics=None, 571 condition_expression=None, 572 expression_attribute_names=None, 573 expression_attribute_values=None): 574 """ 575 Deletes a single item in a table by primary key. You can 576 perform a conditional delete operation that deletes the item 577 if it exists, or if it has an expected attribute value. 578 579 In addition to deleting an item, you can also return the 580 item's attribute values in the same operation, using the 581 ReturnValues parameter. 582 583 Unless you specify conditions, the DeleteItem is an idempotent 584 operation; running it multiple times on the same item or 585 attribute does not result in an error response. 586 587 Conditional deletes are useful for deleting items only if 588 specific conditions are met. If those conditions are met, 589 DynamoDB performs the delete. Otherwise, the item is not 590 deleted. 591 592 :type table_name: string 593 :param table_name: The name of the table from which to delete the item. 594 595 :type key: map 596 :param key: A map of attribute names to AttributeValue objects, 597 representing the primary key of the item to delete. 598 For the primary key, you must provide all of the attributes. For 599 example, with a hash type primary key, you only need to specify the 600 hash attribute. For a hash-and-range type primary key, you must 601 specify both the hash attribute and the range attribute. 602 603 :type expected: map 604 :param expected: 605 There is a newer parameter available. Use ConditionExpression instead. 606 Note that if you use Expected and ConditionExpression at the same 607 time, DynamoDB will return a ValidationException exception. 608 609 This parameter does not support lists or maps. 610 611 A map of attribute/condition pairs. Expected provides a conditional 612 block for the DeleteItem operation. 613 614 Each element of Expected consists of an attribute name, a comparison 615 operator, and one or more values. DynamoDB compares the attribute 616 with the value(s) you supplied, using the comparison operator. For 617 each Expected element, the result of the evaluation is either true 618 or false. 619 620 If you specify more than one element in the Expected map, then by 621 default all of the conditions must evaluate to true. In other 622 words, the conditions are ANDed together. (You can use the 623 ConditionalOperator parameter to OR the conditions instead. If you 624 do this, then at least one of the conditions must evaluate to true, 625 rather than all of them.) 626 627 If the Expected map evaluates to true, then the conditional operation 628 succeeds; otherwise, it fails. 629 630 Expected contains the following: 631 632 633 + AttributeValueList - One or more values to evaluate against the 634 supplied attribute. The number of values in the list depends on the 635 ComparisonOperator being used. For type Number, value comparisons 636 are numeric. String value comparisons for greater than, equals, or 637 less than are based on ASCII character code values. For example, 638 `a` is greater than `A`, and `a` is greater than `B`. For a list of 639 code values, see 640 `http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_. 641 For type Binary, DynamoDB treats each byte of the binary data as 642 unsigned when it compares binary values, for example when 643 evaluating query expressions. 644 + ComparisonOperator - A comparator for evaluating attributes in the 645 AttributeValueList . When performing the comparison, DynamoDB uses 646 strongly consistent reads. The following comparison operators are 647 available: `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | 648 CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN` The following 649 are descriptions of each comparison operator. 650 651 + `EQ` : Equal. `EQ` is supported for all datatypes, including lists 652 and maps. AttributeValueList can contain only one AttributeValue 653 element of type String, Number, Binary, String Set, Number Set, or 654 Binary Set. If an item contains an AttributeValue element of a 655 different type than the one specified in the request, the value 656 does not match. For example, `{"S":"6"}` does not equal 657 `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", 658 "1"]}`. > <li> 659 + `NE` : Not equal. `NE` is supported for all datatypes, including 660 lists and maps. AttributeValueList can contain only one 661 AttributeValue of type String, Number, Binary, String Set, Number 662 Set, or Binary Set. If an item contains an AttributeValue of a 663 different type than the one specified in the request, the value 664 does not match. For example, `{"S":"6"}` does not equal 665 `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", 666 "1"]}`. > <li> 667 + `LE` : Less than or equal. AttributeValueList can contain only one 668 AttributeValue element of type String, Number, or Binary (not a set 669 type). If an item contains an AttributeValue element of a different 670 type than the one specified in the request, the value does not 671 match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 672 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 673 + `LT` : Less than. AttributeValueList can contain only one 674 AttributeValue of type String, Number, or Binary (not a set type). 675 If an item contains an AttributeValue element of a different type 676 than the one specified in the request, the value does not match. 677 For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 678 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 679 + `GE` : Greater than or equal. AttributeValueList can contain only one 680 AttributeValue element of type String, Number, or Binary (not a set 681 type). If an item contains an AttributeValue element of a different 682 type than the one specified in the request, the value does not 683 match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 684 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 685 + `GT` : Greater than. AttributeValueList can contain only one 686 AttributeValue element of type String, Number, or Binary (not a set 687 type). If an item contains an AttributeValue element of a different 688 type than the one specified in the request, the value does not 689 match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 690 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 691 + `NOT_NULL` : The attribute exists. `NOT_NULL` is supported for all 692 datatypes, including lists and maps. This operator tests for the 693 existence of an attribute, not its data type. If the data type of 694 attribute " `a`" is null, and you evaluate it using `NOT_NULL`, the 695 result is a Boolean true . This result is because the attribute " 696 `a`" exists; its data type is not relevant to the `NOT_NULL` 697 comparison operator. 698 + `NULL` : The attribute does not exist. `NULL` is supported for all 699 datatypes, including lists and maps. This operator tests for the 700 nonexistence of an attribute, not its data type. If the data type 701 of attribute " `a`" is null, and you evaluate it using `NULL`, the 702 result is a Boolean false . This is because the attribute " `a`" 703 exists; its data type is not relevant to the `NULL` comparison 704 operator. 705 + `CONTAINS` : Checks for a subsequence, or value in a set. 706 AttributeValueList can contain only one AttributeValue element of 707 type String, Number, or Binary (not a set type). If the target 708 attribute of the comparison is of type String, then the operator 709 checks for a substring match. If the target attribute of the 710 comparison is of type Binary, then the operator looks for a 711 subsequence of the target that matches the input. If the target 712 attribute of the comparison is a set (" `SS`", " `NS`", or " 713 `BS`"), then the operator evaluates to true if it finds an exact 714 match with any member of the set. CONTAINS is supported for lists: 715 When evaluating " `a CONTAINS b`", " `a`" can be a list; however, " 716 `b`" cannot be a set, a map, or a list. 717 + `NOT_CONTAINS` : Checks for absence of a subsequence, or absence of a 718 value in a set. AttributeValueList can contain only one 719 AttributeValue element of type String, Number, or Binary (not a set 720 type). If the target attribute of the comparison is a String, then 721 the operator checks for the absence of a substring match. If the 722 target attribute of the comparison is Binary, then the operator 723 checks for the absence of a subsequence of the target that matches 724 the input. If the target attribute of the comparison is a set (" 725 `SS`", " `NS`", or " `BS`"), then the operator evaluates to true if 726 it does not find an exact match with any member of the set. 727 NOT_CONTAINS is supported for lists: When evaluating " `a NOT 728 CONTAINS b`", " `a`" can be a list; however, " `b`" cannot be a 729 set, a map, or a list. 730 + `BEGINS_WITH` : Checks for a prefix. AttributeValueList can contain 731 only one AttributeValue of type String or Binary (not a Number or a 732 set type). The target attribute of the comparison must be of type 733 String or Binary (not a Number or a set type). > <li> 734 + `IN` : Checks for matching elements within two sets. 735 AttributeValueList can contain one or more AttributeValue elements 736 of type String, Number, or Binary (not a set type). These 737 attributes are compared against an existing set type attribute of 738 an item. If any elements of the input set are present in the item 739 attribute, the expression evaluates to true. 740 + `BETWEEN` : Greater than or equal to the first value, and less than 741 or equal to the second value. AttributeValueList must contain two 742 AttributeValue elements of the same type, either String, Number, or 743 Binary (not a set type). A target attribute matches if the target 744 value is greater than, or equal to, the first element and less 745 than, or equal to, the second element. If an item contains an 746 AttributeValue element of a different type than the one specified 747 in the request, the value does not match. For example, `{"S":"6"}` 748 does not compare to `{"N":"6"}`. Also, `{"N":"6"}` does not compare 749 to `{"NS":["6", "2", "1"]}` 750 751 752 753 For usage examples of AttributeValueList and ComparisonOperator , see 754 `Legacy Conditional Parameters`_ in the Amazon DynamoDB Developer 755 Guide . 756 757 For backward compatibility with previous DynamoDB releases, the 758 following parameters can be used instead of AttributeValueList and 759 ComparisonOperator : 760 761 762 + Value - A value for DynamoDB to compare with an attribute. 763 + Exists - A Boolean value that causes DynamoDB to evaluate the value 764 before attempting the conditional operation: 765 766 + If Exists is `True`, DynamoDB will check to see if that attribute 767 value already exists in the table. If it is found, then the 768 condition evaluates to true; otherwise the condition evaluate to 769 false. 770 + If Exists is `False`, DynamoDB assumes that the attribute value does 771 not exist in the table. If in fact the value does not exist, then 772 the assumption is valid and the condition evaluates to true. If the 773 value is found, despite the assumption that it does not exist, the 774 condition evaluates to false. 775 Note that the default value for Exists is `True`. 776 777 778 The Value and Exists parameters are incompatible with 779 AttributeValueList and ComparisonOperator . Note that if you use 780 both sets of parameters at once, DynamoDB will return a 781 ValidationException exception. 782 783 :type conditional_operator: string 784 :param conditional_operator: 785 There is a newer parameter available. Use ConditionExpression instead. 786 Note that if you use ConditionalOperator and ConditionExpression at 787 the same time, DynamoDB will return a ValidationException 788 exception. 789 790 This parameter does not support lists or maps. 791 792 A logical operator to apply to the conditions in the Expected map: 793 794 795 + `AND` - If all of the conditions evaluate to true, then the entire 796 map evaluates to true. 797 + `OR` - If at least one of the conditions evaluate to true, then the 798 entire map evaluates to true. 799 800 801 If you omit ConditionalOperator , then `AND` is the default. 802 803 The operation will succeed only if the entire map evaluates to true. 804 805 :type return_values: string 806 :param return_values: 807 Use ReturnValues if you want to get the item attributes as they 808 appeared before they were deleted. For DeleteItem , the valid 809 values are: 810 811 812 + `NONE` - If ReturnValues is not specified, or if its value is `NONE`, 813 then nothing is returned. (This setting is the default for 814 ReturnValues .) 815 + `ALL_OLD` - The content of the old item is returned. 816 817 :type return_consumed_capacity: string 818 :param return_consumed_capacity: A value that if set to `TOTAL`, the 819 response includes ConsumedCapacity data for tables and indexes. If 820 set to `INDEXES`, the response includes ConsumedCapacity for 821 indexes. If set to `NONE` (the default), ConsumedCapacity is not 822 included in the response. 823 824 :type return_item_collection_metrics: string 825 :param return_item_collection_metrics: A value that if set to `SIZE`, 826 the response includes statistics about item collections, if any, 827 that were modified during the operation are returned in the 828 response. If set to `NONE` (the default), no statistics are 829 returned. 830 831 :type condition_expression: string 832 :param condition_expression: A condition that must be satisfied in 833 order for a conditional DeleteItem to succeed. 834 An expression can contain any of the following: 835 836 837 + Boolean functions: `attribute_exists | attribute_not_exists | 838 contains | begins_with` These function names are case-sensitive. 839 + Comparison operators: ` = | <> | < | > | <= 840 | >= | BETWEEN | IN` 841 + Logical operators: `AND | OR | NOT` 842 843 844 For more information on condition expressions, go to `Specifying 845 Conditions`_ in the Amazon DynamoDB Developer Guide . 846 847 :type expression_attribute_names: map 848 :param expression_attribute_names: One or more substitution tokens for 849 simplifying complex expressions. The following are some use cases 850 for using ExpressionAttributeNames : 851 852 + To shorten an attribute name that is very long or unwieldy in an 853 expression. 854 + To create a placeholder for repeating occurrences of an attribute 855 name in an expression. 856 + To prevent special characters in an attribute name from being 857 misinterpreted in an expression. 858 859 860 Use the **#** character in an expression to dereference an attribute 861 name. For example, consider the following expression: 862 863 864 + `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName 865 = "Jones"` 866 867 868 Now suppose that you specified the following for 869 ExpressionAttributeNames : 870 871 872 + `{"#name":"order.customerInfo.LastName"}` 873 874 875 The expression can now be simplified as follows: 876 877 878 + `#name = "Smith" OR #name = "Jones"` 879 880 881 For more information on expression attribute names, go to `Accessing 882 Item Attributes`_ in the Amazon DynamoDB Developer Guide . 883 884 :type expression_attribute_values: map 885 :param expression_attribute_values: One or more values that can be 886 substituted in an expression. 887 Use the **:** (colon) character in an expression to dereference an 888 attribute value. For example, suppose that you wanted to check 889 whether the value of the ProductStatus attribute was one of the 890 following: 891 892 `Available | Backordered | Discontinued` 893 894 You would first need to specify ExpressionAttributeValues as follows: 895 896 `{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, 897 ":disc":{"S":"Discontinued"} }` 898 899 You could then use these values in an expression, such as this: 900 901 `ProductStatus IN (:avail, :back, :disc)` 902 903 For more information on expression attribute values, go to `Specifying 904 Conditions`_ in the Amazon DynamoDB Developer Guide . 905 906 """ 907 params = {'TableName': table_name, 'Key': key, } 908 if expected is not None: 909 params['Expected'] = expected 910 if conditional_operator is not None: 911 params['ConditionalOperator'] = conditional_operator 912 if return_values is not None: 913 params['ReturnValues'] = return_values 914 if return_consumed_capacity is not None: 915 params['ReturnConsumedCapacity'] = return_consumed_capacity 916 if return_item_collection_metrics is not None: 917 params['ReturnItemCollectionMetrics'] = return_item_collection_metrics 918 if condition_expression is not None: 919 params['ConditionExpression'] = condition_expression 920 if expression_attribute_names is not None: 921 params['ExpressionAttributeNames'] = expression_attribute_names 922 if expression_attribute_values is not None: 923 params['ExpressionAttributeValues'] = expression_attribute_values 924 return self.make_request(action='DeleteItem', 925 body=json.dumps(params)) 926 927 def delete_table(self, table_name): 928 """ 929 The DeleteTable operation deletes a table and all of its 930 items. After a DeleteTable request, the specified table is in 931 the `DELETING` state until DynamoDB completes the deletion. If 932 the table is in the `ACTIVE` state, you can delete it. If a 933 table is in `CREATING` or `UPDATING` states, then DynamoDB 934 returns a ResourceInUseException . If the specified table does 935 not exist, DynamoDB returns a ResourceNotFoundException . If 936 table is already in the `DELETING` state, no error is 937 returned. 938 939 940 DynamoDB might continue to accept data read and write 941 operations, such as GetItem and PutItem , on a table in the 942 `DELETING` state until the table deletion is complete. 943 944 945 When you delete a table, any indexes on that table are also 946 deleted. 947 948 Use the DescribeTable API to check the status of the table. 949 950 :type table_name: string 951 :param table_name: The name of the table to delete. 952 953 """ 954 params = {'TableName': table_name, } 955 return self.make_request(action='DeleteTable', 956 body=json.dumps(params)) 957 958 def describe_table(self, table_name): 959 """ 960 Returns information about the table, including the current 961 status of the table, when it was created, the primary key 962 schema, and any indexes on the table. 963 964 965 If you issue a DescribeTable request immediately after a 966 CreateTable request, DynamoDB might return a 967 ResourceNotFoundException. This is because DescribeTable uses 968 an eventually consistent query, and the metadata for your 969 table might not be available at that moment. Wait for a few 970 seconds, and then try the DescribeTable request again. 971 972 :type table_name: string 973 :param table_name: The name of the table to describe. 974 975 """ 976 params = {'TableName': table_name, } 977 return self.make_request(action='DescribeTable', 978 body=json.dumps(params)) 979 980 def get_item(self, table_name, key, attributes_to_get=None, 981 consistent_read=None, return_consumed_capacity=None, 982 projection_expression=None, expression_attribute_names=None): 983 """ 984 The GetItem operation returns a set of attributes for the item 985 with the given primary key. If there is no matching item, 986 GetItem does not return any data. 987 988 GetItem provides an eventually consistent read by default. If 989 your application requires a strongly consistent read, set 990 ConsistentRead to `True`. Although a strongly consistent read 991 might take more time than an eventually consistent read, it 992 always returns the last updated value. 993 994 :type table_name: string 995 :param table_name: The name of the table containing the requested item. 996 997 :type key: map 998 :param key: A map of attribute names to AttributeValue objects, 999 representing the primary key of the item to retrieve. 1000 For the primary key, you must provide all of the attributes. For 1001 example, with a hash type primary key, you only need to specify the 1002 hash attribute. For a hash-and-range type primary key, you must 1003 specify both the hash attribute and the range attribute. 1004 1005 :type attributes_to_get: list 1006 :param attributes_to_get: 1007 There is a newer parameter available. Use ProjectionExpression instead. 1008 Note that if you use AttributesToGet and ProjectionExpression at 1009 the same time, DynamoDB will return a ValidationException 1010 exception. 1011 1012 This parameter allows you to retrieve lists or maps; however, it cannot 1013 retrieve individual list or map elements. 1014 1015 The names of one or more attributes to retrieve. If no attribute names 1016 are specified, then all attributes will be returned. If any of the 1017 requested attributes are not found, they will not appear in the 1018 result. 1019 1020 Note that AttributesToGet has no effect on provisioned throughput 1021 consumption. DynamoDB determines capacity units consumed based on 1022 item size, not on the amount of data that is returned to an 1023 application. 1024 1025 :type consistent_read: boolean 1026 :param consistent_read: A value that if set to `True`, then the 1027 operation uses strongly consistent reads; otherwise, eventually 1028 consistent reads are used. 1029 1030 :type return_consumed_capacity: string 1031 :param return_consumed_capacity: A value that if set to `TOTAL`, the 1032 response includes ConsumedCapacity data for tables and indexes. If 1033 set to `INDEXES`, the response includes ConsumedCapacity for 1034 indexes. If set to `NONE` (the default), ConsumedCapacity is not 1035 included in the response. 1036 1037 :type projection_expression: string 1038 :param projection_expression: A string that identifies one or more 1039 attributes to retrieve from the table. These attributes can include 1040 scalars, sets, or elements of a JSON document. The attributes in 1041 the expression must be separated by commas. 1042 If no attribute names are specified, then all attributes will be 1043 returned. If any of the requested attributes are not found, they 1044 will not appear in the result. 1045 1046 For more information on projection expressions, go to `Accessing Item 1047 Attributes`_ in the Amazon DynamoDB Developer Guide . 1048 1049 :type expression_attribute_names: map 1050 :param expression_attribute_names: One or more substitution tokens for 1051 simplifying complex expressions. The following are some use cases 1052 for using ExpressionAttributeNames : 1053 1054 + To shorten an attribute name that is very long or unwieldy in an 1055 expression. 1056 + To create a placeholder for repeating occurrences of an attribute 1057 name in an expression. 1058 + To prevent special characters in an attribute name from being 1059 misinterpreted in an expression. 1060 1061 1062 Use the **#** character in an expression to dereference an attribute 1063 name. For example, consider the following expression: 1064 1065 1066 + `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName 1067 = "Jones"` 1068 1069 1070 Now suppose that you specified the following for 1071 ExpressionAttributeNames : 1072 1073 1074 + `{"#name":"order.customerInfo.LastName"}` 1075 1076 1077 The expression can now be simplified as follows: 1078 1079 1080 + `#name = "Smith" OR #name = "Jones"` 1081 1082 1083 For more information on expression attribute names, go to `Accessing 1084 Item Attributes`_ in the Amazon DynamoDB Developer Guide . 1085 1086 """ 1087 params = {'TableName': table_name, 'Key': key, } 1088 if attributes_to_get is not None: 1089 params['AttributesToGet'] = attributes_to_get 1090 if consistent_read is not None: 1091 params['ConsistentRead'] = consistent_read 1092 if return_consumed_capacity is not None: 1093 params['ReturnConsumedCapacity'] = return_consumed_capacity 1094 if projection_expression is not None: 1095 params['ProjectionExpression'] = projection_expression 1096 if expression_attribute_names is not None: 1097 params['ExpressionAttributeNames'] = expression_attribute_names 1098 return self.make_request(action='GetItem', 1099 body=json.dumps(params)) 1100 1101 def list_tables(self, exclusive_start_table_name=None, limit=None): 1102 """ 1103 Returns an array of table names associated with the current 1104 account and endpoint. The output from ListTables is paginated, 1105 with each page returning a maximum of 100 table names. 1106 1107 :type exclusive_start_table_name: string 1108 :param exclusive_start_table_name: The first table name that this 1109 operation will evaluate. Use the value that was returned for 1110 LastEvaluatedTableName in a previous operation, so that you can 1111 obtain the next page of results. 1112 1113 :type limit: integer 1114 :param limit: A maximum number of table names to return. If this 1115 parameter is not specified, the limit is 100. 1116 1117 """ 1118 params = {} 1119 if exclusive_start_table_name is not None: 1120 params['ExclusiveStartTableName'] = exclusive_start_table_name 1121 if limit is not None: 1122 params['Limit'] = limit 1123 return self.make_request(action='ListTables', 1124 body=json.dumps(params)) 1125 1126 def put_item(self, table_name, item, expected=None, return_values=None, 1127 return_consumed_capacity=None, 1128 return_item_collection_metrics=None, 1129 conditional_operator=None, condition_expression=None, 1130 expression_attribute_names=None, 1131 expression_attribute_values=None): 1132 """ 1133 Creates a new item, or replaces an old item with a new item. 1134 If an item that has the same primary key as the new item 1135 already exists in the specified table, the new item completely 1136 replaces the existing item. You can perform a conditional put 1137 operation (add a new item if one with the specified primary 1138 key doesn't exist), or replace an existing item if it has 1139 certain attribute values. 1140 1141 In addition to putting an item, you can also return the item's 1142 attribute values in the same operation, using the ReturnValues 1143 parameter. 1144 1145 When you add an item, the primary key attribute(s) are the 1146 only required attributes. Attribute values cannot be null. 1147 String and Binary type attributes must have lengths greater 1148 than zero. Set type attributes cannot be empty. Requests with 1149 empty values will be rejected with a ValidationException 1150 exception. 1151 1152 You can request that PutItem return either a copy of the 1153 original item (before the update) or a copy of the updated 1154 item (after the update). For more information, see the 1155 ReturnValues description below. 1156 1157 1158 To prevent a new item from replacing an existing item, use a 1159 conditional put operation with ComparisonOperator set to 1160 `NULL` for the primary key attribute, or attributes. 1161 1162 1163 For more information about using this API, see `Working with 1164 Items`_ in the Amazon DynamoDB Developer Guide . 1165 1166 :type table_name: string 1167 :param table_name: The name of the table to contain the item. 1168 1169 :type item: map 1170 :param item: A map of attribute name/value pairs, one for each 1171 attribute. Only the primary key attributes are required; you can 1172 optionally provide other attribute name-value pairs for the item. 1173 You must provide all of the attributes for the primary key. For 1174 example, with a hash type primary key, you only need to specify the 1175 hash attribute. For a hash-and-range type primary key, you must 1176 specify both the hash attribute and the range attribute. 1177 1178 If you specify any attributes that are part of an index key, then the 1179 data types for those attributes must match those of the schema in 1180 the table's attribute definition. 1181 1182 For more information about primary keys, see `Primary Key`_ in the 1183 Amazon DynamoDB Developer Guide . 1184 1185 Each element in the Item map is an AttributeValue object. 1186 1187 :type expected: map 1188 :param expected: 1189 There is a newer parameter available. Use ConditionExpression instead. 1190 Note that if you use Expected and ConditionExpression at the same 1191 time, DynamoDB will return a ValidationException exception. 1192 1193 This parameter does not support lists or maps. 1194 1195 A map of attribute/condition pairs. Expected provides a conditional 1196 block for the PutItem operation. 1197 1198 Each element of Expected consists of an attribute name, a comparison 1199 operator, and one or more values. DynamoDB compares the attribute 1200 with the value(s) you supplied, using the comparison operator. For 1201 each Expected element, the result of the evaluation is either true 1202 or false. 1203 1204 If you specify more than one element in the Expected map, then by 1205 default all of the conditions must evaluate to true. In other 1206 words, the conditions are ANDed together. (You can use the 1207 ConditionalOperator parameter to OR the conditions instead. If you 1208 do this, then at least one of the conditions must evaluate to true, 1209 rather than all of them.) 1210 1211 If the Expected map evaluates to true, then the conditional operation 1212 succeeds; otherwise, it fails. 1213 1214 Expected contains the following: 1215 1216 1217 + AttributeValueList - One or more values to evaluate against the 1218 supplied attribute. The number of values in the list depends on the 1219 ComparisonOperator being used. For type Number, value comparisons 1220 are numeric. String value comparisons for greater than, equals, or 1221 less than are based on ASCII character code values. For example, 1222 `a` is greater than `A`, and `a` is greater than `B`. For a list of 1223 code values, see 1224 `http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_. 1225 For type Binary, DynamoDB treats each byte of the binary data as 1226 unsigned when it compares binary values, for example when 1227 evaluating query expressions. 1228 + ComparisonOperator - A comparator for evaluating attributes in the 1229 AttributeValueList . When performing the comparison, DynamoDB uses 1230 strongly consistent reads. The following comparison operators are 1231 available: `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | 1232 CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN` The following 1233 are descriptions of each comparison operator. 1234 1235 + `EQ` : Equal. `EQ` is supported for all datatypes, including lists 1236 and maps. AttributeValueList can contain only one AttributeValue 1237 element of type String, Number, Binary, String Set, Number Set, or 1238 Binary Set. If an item contains an AttributeValue element of a 1239 different type than the one specified in the request, the value 1240 does not match. For example, `{"S":"6"}` does not equal 1241 `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", 1242 "1"]}`. > <li> 1243 + `NE` : Not equal. `NE` is supported for all datatypes, including 1244 lists and maps. AttributeValueList can contain only one 1245 AttributeValue of type String, Number, Binary, String Set, Number 1246 Set, or Binary Set. If an item contains an AttributeValue of a 1247 different type than the one specified in the request, the value 1248 does not match. For example, `{"S":"6"}` does not equal 1249 `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", 1250 "1"]}`. > <li> 1251 + `LE` : Less than or equal. AttributeValueList can contain only one 1252 AttributeValue element of type String, Number, or Binary (not a set 1253 type). If an item contains an AttributeValue element of a different 1254 type than the one specified in the request, the value does not 1255 match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 1256 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 1257 + `LT` : Less than. AttributeValueList can contain only one 1258 AttributeValue of type String, Number, or Binary (not a set type). 1259 If an item contains an AttributeValue element of a different type 1260 than the one specified in the request, the value does not match. 1261 For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 1262 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 1263 + `GE` : Greater than or equal. AttributeValueList can contain only one 1264 AttributeValue element of type String, Number, or Binary (not a set 1265 type). If an item contains an AttributeValue element of a different 1266 type than the one specified in the request, the value does not 1267 match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 1268 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 1269 + `GT` : Greater than. AttributeValueList can contain only one 1270 AttributeValue element of type String, Number, or Binary (not a set 1271 type). If an item contains an AttributeValue element of a different 1272 type than the one specified in the request, the value does not 1273 match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 1274 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 1275 + `NOT_NULL` : The attribute exists. `NOT_NULL` is supported for all 1276 datatypes, including lists and maps. This operator tests for the 1277 existence of an attribute, not its data type. If the data type of 1278 attribute " `a`" is null, and you evaluate it using `NOT_NULL`, the 1279 result is a Boolean true . This result is because the attribute " 1280 `a`" exists; its data type is not relevant to the `NOT_NULL` 1281 comparison operator. 1282 + `NULL` : The attribute does not exist. `NULL` is supported for all 1283 datatypes, including lists and maps. This operator tests for the 1284 nonexistence of an attribute, not its data type. If the data type 1285 of attribute " `a`" is null, and you evaluate it using `NULL`, the 1286 result is a Boolean false . This is because the attribute " `a`" 1287 exists; its data type is not relevant to the `NULL` comparison 1288 operator. 1289 + `CONTAINS` : Checks for a subsequence, or value in a set. 1290 AttributeValueList can contain only one AttributeValue element of 1291 type String, Number, or Binary (not a set type). If the target 1292 attribute of the comparison is of type String, then the operator 1293 checks for a substring match. If the target attribute of the 1294 comparison is of type Binary, then the operator looks for a 1295 subsequence of the target that matches the input. If the target 1296 attribute of the comparison is a set (" `SS`", " `NS`", or " 1297 `BS`"), then the operator evaluates to true if it finds an exact 1298 match with any member of the set. CONTAINS is supported for lists: 1299 When evaluating " `a CONTAINS b`", " `a`" can be a list; however, " 1300 `b`" cannot be a set, a map, or a list. 1301 + `NOT_CONTAINS` : Checks for absence of a subsequence, or absence of a 1302 value in a set. AttributeValueList can contain only one 1303 AttributeValue element of type String, Number, or Binary (not a set 1304 type). If the target attribute of the comparison is a String, then 1305 the operator checks for the absence of a substring match. If the 1306 target attribute of the comparison is Binary, then the operator 1307 checks for the absence of a subsequence of the target that matches 1308 the input. If the target attribute of the comparison is a set (" 1309 `SS`", " `NS`", or " `BS`"), then the operator evaluates to true if 1310 it does not find an exact match with any member of the set. 1311 NOT_CONTAINS is supported for lists: When evaluating " `a NOT 1312 CONTAINS b`", " `a`" can be a list; however, " `b`" cannot be a 1313 set, a map, or a list. 1314 + `BEGINS_WITH` : Checks for a prefix. AttributeValueList can contain 1315 only one AttributeValue of type String or Binary (not a Number or a 1316 set type). The target attribute of the comparison must be of type 1317 String or Binary (not a Number or a set type). > <li> 1318 + `IN` : Checks for matching elements within two sets. 1319 AttributeValueList can contain one or more AttributeValue elements 1320 of type String, Number, or Binary (not a set type). These 1321 attributes are compared against an existing set type attribute of 1322 an item. If any elements of the input set are present in the item 1323 attribute, the expression evaluates to true. 1324 + `BETWEEN` : Greater than or equal to the first value, and less than 1325 or equal to the second value. AttributeValueList must contain two 1326 AttributeValue elements of the same type, either String, Number, or 1327 Binary (not a set type). A target attribute matches if the target 1328 value is greater than, or equal to, the first element and less 1329 than, or equal to, the second element. If an item contains an 1330 AttributeValue element of a different type than the one specified 1331 in the request, the value does not match. For example, `{"S":"6"}` 1332 does not compare to `{"N":"6"}`. Also, `{"N":"6"}` does not compare 1333 to `{"NS":["6", "2", "1"]}` 1334 1335 1336 1337 For usage examples of AttributeValueList and ComparisonOperator , see 1338 `Legacy Conditional Parameters`_ in the Amazon DynamoDB Developer 1339 Guide . 1340 1341 For backward compatibility with previous DynamoDB releases, the 1342 following parameters can be used instead of AttributeValueList and 1343 ComparisonOperator : 1344 1345 1346 + Value - A value for DynamoDB to compare with an attribute. 1347 + Exists - A Boolean value that causes DynamoDB to evaluate the value 1348 before attempting the conditional operation: 1349 1350 + If Exists is `True`, DynamoDB will check to see if that attribute 1351 value already exists in the table. If it is found, then the 1352 condition evaluates to true; otherwise the condition evaluate to 1353 false. 1354 + If Exists is `False`, DynamoDB assumes that the attribute value does 1355 not exist in the table. If in fact the value does not exist, then 1356 the assumption is valid and the condition evaluates to true. If the 1357 value is found, despite the assumption that it does not exist, the 1358 condition evaluates to false. 1359 Note that the default value for Exists is `True`. 1360 1361 1362 The Value and Exists parameters are incompatible with 1363 AttributeValueList and ComparisonOperator . Note that if you use 1364 both sets of parameters at once, DynamoDB will return a 1365 ValidationException exception. 1366 1367 :type return_values: string 1368 :param return_values: 1369 Use ReturnValues if you want to get the item attributes as they 1370 appeared before they were updated with the PutItem request. For 1371 PutItem , the valid values are: 1372 1373 1374 + `NONE` - If ReturnValues is not specified, or if its value is `NONE`, 1375 then nothing is returned. (This setting is the default for 1376 ReturnValues .) 1377 + `ALL_OLD` - If PutItem overwrote an attribute name-value pair, then 1378 the content of the old item is returned. 1379 1380 :type return_consumed_capacity: string 1381 :param return_consumed_capacity: A value that if set to `TOTAL`, the 1382 response includes ConsumedCapacity data for tables and indexes. If 1383 set to `INDEXES`, the response includes ConsumedCapacity for 1384 indexes. If set to `NONE` (the default), ConsumedCapacity is not 1385 included in the response. 1386 1387 :type return_item_collection_metrics: string 1388 :param return_item_collection_metrics: A value that if set to `SIZE`, 1389 the response includes statistics about item collections, if any, 1390 that were modified during the operation are returned in the 1391 response. If set to `NONE` (the default), no statistics are 1392 returned. 1393 1394 :type conditional_operator: string 1395 :param conditional_operator: 1396 There is a newer parameter available. Use ConditionExpression instead. 1397 Note that if you use ConditionalOperator and ConditionExpression at 1398 the same time, DynamoDB will return a ValidationException 1399 exception. 1400 1401 This parameter does not support lists or maps. 1402 1403 A logical operator to apply to the conditions in the Expected map: 1404 1405 1406 + `AND` - If all of the conditions evaluate to true, then the entire 1407 map evaluates to true. 1408 + `OR` - If at least one of the conditions evaluate to true, then the 1409 entire map evaluates to true. 1410 1411 1412 If you omit ConditionalOperator , then `AND` is the default. 1413 1414 The operation will succeed only if the entire map evaluates to true. 1415 1416 :type condition_expression: string 1417 :param condition_expression: A condition that must be satisfied in 1418 order for a conditional PutItem operation to succeed. 1419 An expression can contain any of the following: 1420 1421 1422 + Boolean functions: `attribute_exists | attribute_not_exists | 1423 contains | begins_with` These function names are case-sensitive. 1424 + Comparison operators: ` = | <> | < | > | <= 1425 | >= | BETWEEN | IN` 1426 + Logical operators: `AND | OR | NOT` 1427 1428 1429 For more information on condition expressions, go to `Specifying 1430 Conditions`_ in the Amazon DynamoDB Developer Guide . 1431 1432 :type expression_attribute_names: map 1433 :param expression_attribute_names: One or more substitution tokens for 1434 simplifying complex expressions. The following are some use cases 1435 for using ExpressionAttributeNames : 1436 1437 + To shorten an attribute name that is very long or unwieldy in an 1438 expression. 1439 + To create a placeholder for repeating occurrences of an attribute 1440 name in an expression. 1441 + To prevent special characters in an attribute name from being 1442 misinterpreted in an expression. 1443 1444 1445 Use the **#** character in an expression to dereference an attribute 1446 name. For example, consider the following expression: 1447 1448 1449 + `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName 1450 = "Jones"` 1451 1452 1453 Now suppose that you specified the following for 1454 ExpressionAttributeNames : 1455 1456 1457 + `{"#name":"order.customerInfo.LastName"}` 1458 1459 1460 The expression can now be simplified as follows: 1461 1462 1463 + `#name = "Smith" OR #name = "Jones"` 1464 1465 1466 For more information on expression attribute names, go to `Accessing 1467 Item Attributes`_ in the Amazon DynamoDB Developer Guide . 1468 1469 :type expression_attribute_values: map 1470 :param expression_attribute_values: One or more values that can be 1471 substituted in an expression. 1472 Use the **:** (colon) character in an expression to dereference an 1473 attribute value. For example, suppose that you wanted to check 1474 whether the value of the ProductStatus attribute was one of the 1475 following: 1476 1477 `Available | Backordered | Discontinued` 1478 1479 You would first need to specify ExpressionAttributeValues as follows: 1480 1481 `{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, 1482 ":disc":{"S":"Discontinued"} }` 1483 1484 You could then use these values in an expression, such as this: 1485 1486 `ProductStatus IN (:avail, :back, :disc)` 1487 1488 For more information on expression attribute values, go to `Specifying 1489 Conditions`_ in the Amazon DynamoDB Developer Guide . 1490 1491 """ 1492 params = {'TableName': table_name, 'Item': item, } 1493 if expected is not None: 1494 params['Expected'] = expected 1495 if return_values is not None: 1496 params['ReturnValues'] = return_values 1497 if return_consumed_capacity is not None: 1498 params['ReturnConsumedCapacity'] = return_consumed_capacity 1499 if return_item_collection_metrics is not None: 1500 params['ReturnItemCollectionMetrics'] = return_item_collection_metrics 1501 if conditional_operator is not None: 1502 params['ConditionalOperator'] = conditional_operator 1503 if condition_expression is not None: 1504 params['ConditionExpression'] = condition_expression 1505 if expression_attribute_names is not None: 1506 params['ExpressionAttributeNames'] = expression_attribute_names 1507 if expression_attribute_values is not None: 1508 params['ExpressionAttributeValues'] = expression_attribute_values 1509 return self.make_request(action='PutItem', 1510 body=json.dumps(params)) 1511 1512 def query(self, table_name, key_conditions, index_name=None, select=None, 1513 attributes_to_get=None, limit=None, consistent_read=None, 1514 query_filter=None, conditional_operator=None, 1515 scan_index_forward=None, exclusive_start_key=None, 1516 return_consumed_capacity=None, projection_expression=None, 1517 filter_expression=None, expression_attribute_names=None, 1518 expression_attribute_values=None): 1519 """ 1520 A Query operation directly accesses items from a table using 1521 the table primary key, or from an index using the index key. 1522 You must provide a specific hash key value. You can narrow the 1523 scope of the query by using comparison operators on the range 1524 key value, or on the index key. You can use the 1525 ScanIndexForward parameter to get results in forward or 1526 reverse order, by range key or by index key. 1527 1528 Queries that do not return results consume the minimum number 1529 of read capacity units for that type of read operation. 1530 1531 If the total number of items meeting the query criteria 1532 exceeds the result set size limit of 1 MB, the query stops and 1533 results are returned to the user with LastEvaluatedKey to 1534 continue the query in a subsequent operation. Unlike a Scan 1535 operation, a Query operation never returns both an empty 1536 result set and a LastEvaluatedKey . The LastEvaluatedKey is 1537 only provided if the results exceed 1 MB, or if you have used 1538 Limit . 1539 1540 You can query a table, a local secondary index, or a global 1541 secondary index. For a query on a table or on a local 1542 secondary index, you can set ConsistentRead to true and obtain 1543 a strongly consistent result. Global secondary indexes support 1544 eventually consistent reads only, so do not specify 1545 ConsistentRead when querying a global secondary index. 1546 1547 :type table_name: string 1548 :param table_name: The name of the table containing the requested 1549 items. 1550 1551 :type index_name: string 1552 :param index_name: The name of an index to query. This index can be any 1553 local secondary index or global secondary index on the table. 1554 1555 :type select: string 1556 :param select: The attributes to be returned in the result. You can 1557 retrieve all item attributes, specific item attributes, the count 1558 of matching items, or in the case of an index, some or all of the 1559 attributes projected into the index. 1560 1561 + `ALL_ATTRIBUTES` - Returns all of the item attributes from the 1562 specified table or index. If you query a local secondary index, 1563 then for each matching item in the index DynamoDB will fetch the 1564 entire item from the parent table. If the index is configured to 1565 project all item attributes, then all of the data can be obtained 1566 from the local secondary index, and no fetching is required. 1567 + `ALL_PROJECTED_ATTRIBUTES` - Allowed only when querying an index. 1568 Retrieves all attributes that have been projected into the index. 1569 If the index is configured to project all attributes, this return 1570 value is equivalent to specifying `ALL_ATTRIBUTES`. 1571 + `COUNT` - Returns the number of matching items, rather than the 1572 matching items themselves. 1573 + `SPECIFIC_ATTRIBUTES` - Returns only the attributes listed in 1574 AttributesToGet . This return value is equivalent to specifying 1575 AttributesToGet without specifying any value for Select . If you 1576 query a local secondary index and request only attributes that are 1577 projected into that index, the operation will read only the index 1578 and not the table. If any of the requested attributes are not 1579 projected into the local secondary index, DynamoDB will fetch each 1580 of these attributes from the parent table. This extra fetching 1581 incurs additional throughput cost and latency. If you query a 1582 global secondary index, you can only request attributes that are 1583 projected into the index. Global secondary index queries cannot 1584 fetch attributes from the parent table. 1585 1586 1587 If neither Select nor AttributesToGet are specified, DynamoDB defaults 1588 to `ALL_ATTRIBUTES` when accessing a table, and 1589 `ALL_PROJECTED_ATTRIBUTES` when accessing an index. You cannot use 1590 both Select and AttributesToGet together in a single request, 1591 unless the value for Select is `SPECIFIC_ATTRIBUTES`. (This usage 1592 is equivalent to specifying AttributesToGet without any value for 1593 Select .) 1594 1595 :type attributes_to_get: list 1596 :param attributes_to_get: 1597 There is a newer parameter available. Use ProjectionExpression instead. 1598 Note that if you use AttributesToGet and ProjectionExpression at 1599 the same time, DynamoDB will return a ValidationException 1600 exception. 1601 1602 This parameter allows you to retrieve lists or maps; however, it cannot 1603 retrieve individual list or map elements. 1604 1605 The names of one or more attributes to retrieve. If no attribute names 1606 are specified, then all attributes will be returned. If any of the 1607 requested attributes are not found, they will not appear in the 1608 result. 1609 1610 Note that AttributesToGet has no effect on provisioned throughput 1611 consumption. DynamoDB determines capacity units consumed based on 1612 item size, not on the amount of data that is returned to an 1613 application. 1614 1615 You cannot use both AttributesToGet and Select together in a Query 1616 request, unless the value for Select is `SPECIFIC_ATTRIBUTES`. 1617 (This usage is equivalent to specifying AttributesToGet without any 1618 value for Select .) 1619 1620 If you query a local secondary index and request only attributes that 1621 are projected into that index, the operation will read only the 1622 index and not the table. If any of the requested attributes are not 1623 projected into the local secondary index, DynamoDB will fetch each 1624 of these attributes from the parent table. This extra fetching 1625 incurs additional throughput cost and latency. 1626 1627 If you query a global secondary index, you can only request attributes 1628 that are projected into the index. Global secondary index queries 1629 cannot fetch attributes from the parent table. 1630 1631 :type limit: integer 1632 :param limit: The maximum number of items to evaluate (not necessarily 1633 the number of matching items). If DynamoDB processes the number of 1634 items up to the limit while processing the results, it stops the 1635 operation and returns the matching values up to that point, and a 1636 key in LastEvaluatedKey to apply in a subsequent operation, so that 1637 you can pick up where you left off. Also, if the processed data set 1638 size exceeds 1 MB before DynamoDB reaches this limit, it stops the 1639 operation and returns the matching values up to the limit, and a 1640 key in LastEvaluatedKey to apply in a subsequent operation to 1641 continue the operation. For more information, see `Query and Scan`_ 1642 in the Amazon DynamoDB Developer Guide . 1643 1644 :type consistent_read: boolean 1645 :param consistent_read: A value that if set to `True`, then the 1646 operation uses strongly consistent reads; otherwise, eventually 1647 consistent reads are used. 1648 Strongly consistent reads are not supported on global secondary 1649 indexes. If you query a global secondary index with ConsistentRead 1650 set to `True`, you will receive an error message. 1651 1652 :type key_conditions: map 1653 :param key_conditions: The selection criteria for the query. For a 1654 query on a table, you can have conditions only on the table primary 1655 key attributes. You must specify the hash key attribute name and 1656 value as an `EQ` condition. You can optionally specify a second 1657 condition, referring to the range key attribute. If you do not 1658 specify a range key condition, all items under the hash key will be 1659 fetched and processed. Any filters will applied after this. 1660 For a query on an index, you can have conditions only on the index key 1661 attributes. You must specify the index hash attribute name and 1662 value as an EQ condition. You can optionally specify a second 1663 condition, referring to the index key range attribute. 1664 1665 Each KeyConditions element consists of an attribute name to compare, 1666 along with the following: 1667 1668 1669 + AttributeValueList - One or more values to evaluate against the 1670 supplied attribute. The number of values in the list depends on the 1671 ComparisonOperator being used. For type Number, value comparisons 1672 are numeric. String value comparisons for greater than, equals, or 1673 less than are based on ASCII character code values. For example, 1674 `a` is greater than `A`, and `a` is greater than `B`. For a list of 1675 code values, see 1676 `http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_. 1677 For Binary, DynamoDB treats each byte of the binary data as 1678 unsigned when it compares binary values, for example when 1679 evaluating query expressions. 1680 + ComparisonOperator - A comparator for evaluating attributes, for 1681 example, equals, greater than, less than, and so on. For 1682 KeyConditions , only the following comparison operators are 1683 supported: `EQ | LE | LT | GE | GT | BEGINS_WITH | BETWEEN` The 1684 following are descriptions of these comparison operators. 1685 1686 + `EQ` : Equal. AttributeValueList can contain only one AttributeValue 1687 of type String, Number, or Binary (not a set type). If an item 1688 contains an AttributeValue element of a different type than the one 1689 specified in the request, the value does not match. For example, 1690 `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not 1691 equal `{"NS":["6", "2", "1"]}`. 1692 + `LE` : Less than or equal. AttributeValueList can contain only one 1693 AttributeValue element of type String, Number, or Binary (not a set 1694 type). If an item contains an AttributeValue element of a different 1695 type than the one specified in the request, the value does not 1696 match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 1697 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 1698 + `LT` : Less than. AttributeValueList can contain only one 1699 AttributeValue of type String, Number, or Binary (not a set type). 1700 If an item contains an AttributeValue element of a different type 1701 than the one specified in the request, the value does not match. 1702 For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 1703 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 1704 + `GE` : Greater than or equal. AttributeValueList can contain only one 1705 AttributeValue element of type String, Number, or Binary (not a set 1706 type). If an item contains an AttributeValue element of a different 1707 type than the one specified in the request, the value does not 1708 match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 1709 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 1710 + `GT` : Greater than. AttributeValueList can contain only one 1711 AttributeValue element of type String, Number, or Binary (not a set 1712 type). If an item contains an AttributeValue element of a different 1713 type than the one specified in the request, the value does not 1714 match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 1715 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 1716 + `BEGINS_WITH` : Checks for a prefix. AttributeValueList can contain 1717 only one AttributeValue of type String or Binary (not a Number or a 1718 set type). The target attribute of the comparison must be of type 1719 String or Binary (not a Number or a set type). > <li> 1720 + `BETWEEN` : Greater than or equal to the first value, and less than 1721 or equal to the second value. AttributeValueList must contain two 1722 AttributeValue elements of the same type, either String, Number, or 1723 Binary (not a set type). A target attribute matches if the target 1724 value is greater than, or equal to, the first element and less 1725 than, or equal to, the second element. If an item contains an 1726 AttributeValue element of a different type than the one specified 1727 in the request, the value does not match. For example, `{"S":"6"}` 1728 does not compare to `{"N":"6"}`. Also, `{"N":"6"}` does not compare 1729 to `{"NS":["6", "2", "1"]}` 1730 1731 1732 1733 For usage examples of AttributeValueList and ComparisonOperator , see 1734 `Legacy Conditional Parameters`_ in the Amazon DynamoDB Developer 1735 Guide . 1736 1737 :type query_filter: map 1738 :param query_filter: 1739 There is a newer parameter available. Use FilterExpression instead. 1740 Note that if you use QueryFilter and FilterExpression at the same 1741 time, DynamoDB will return a ValidationException exception. 1742 1743 This parameter does not support lists or maps. 1744 1745 A condition that evaluates the query results after the items are read 1746 and returns only the desired values. 1747 Query filters are applied after the items are read, so they do not 1748 limit the capacity used. 1749 If you specify more than one condition in the QueryFilter map, then by 1750 default all of the conditions must evaluate to true. In other 1751 words, the conditions are ANDed together. (You can use the 1752 ConditionalOperator parameter to OR the conditions instead. If you 1753 do this, then at least one of the conditions must evaluate to true, 1754 rather than all of them.) 1755 1756 1757 QueryFilter does not allow key attributes. You cannot define a filter 1758 condition on a hash key or range key. 1759 1760 1761 Each QueryFilter element consists of an attribute name to compare, 1762 along with the following: 1763 1764 1765 + AttributeValueList - One or more values to evaluate against the 1766 supplied attribute. The number of values in the list depends on the 1767 operator specified in ComparisonOperator . For type Number, value 1768 comparisons are numeric. String value comparisons for greater than, 1769 equals, or less than are based on ASCII character code values. For 1770 example, `a` is greater than `A`, and `a` is greater than `B`. For 1771 a list of code values, see 1772 `http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_. 1773 For type Binary, DynamoDB treats each byte of the binary data as 1774 unsigned when it compares binary values, for example when 1775 evaluating query expressions. For information on specifying data 1776 types in JSON, see `JSON Data Format`_ in the Amazon DynamoDB 1777 Developer Guide . 1778 + ComparisonOperator - A comparator for evaluating attributes. For 1779 example, equals, greater than, less than, etc. The following 1780 comparison operators are available: `EQ | NE | LE | LT | GE | GT | 1781 NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | 1782 BETWEEN` For complete descriptions of all comparison operators, see 1783 `API_Condition.html`_. 1784 1785 :type conditional_operator: string 1786 :param conditional_operator: 1787 This parameter does not support lists or maps. 1788 1789 A logical operator to apply to the conditions in the QueryFilter map: 1790 1791 1792 + `AND` - If all of the conditions evaluate to true, then the entire 1793 map evaluates to true. 1794 + `OR` - If at least one of the conditions evaluate to true, then the 1795 entire map evaluates to true. 1796 1797 1798 If you omit ConditionalOperator , then `AND` is the default. 1799 1800 The operation will succeed only if the entire map evaluates to true. 1801 1802 :type scan_index_forward: boolean 1803 :param scan_index_forward: A value that specifies ascending (true) or 1804 descending (false) traversal of the index. DynamoDB returns results 1805 reflecting the requested order determined by the range key. If the 1806 data type is Number, the results are returned in numeric order. For 1807 type String, the results are returned in order of ASCII character 1808 code values. For type Binary, DynamoDB treats each byte of the 1809 binary data as unsigned when it compares binary values. 1810 If ScanIndexForward is not specified, the results are returned in 1811 ascending order. 1812 1813 :type exclusive_start_key: map 1814 :param exclusive_start_key: The primary key of the first item that this 1815 operation will evaluate. Use the value that was returned for 1816 LastEvaluatedKey in the previous operation. 1817 The data type for ExclusiveStartKey must be String, Number or Binary. 1818 No set data types are allowed. 1819 1820 :type return_consumed_capacity: string 1821 :param return_consumed_capacity: A value that if set to `TOTAL`, the 1822 response includes ConsumedCapacity data for tables and indexes. If 1823 set to `INDEXES`, the response includes ConsumedCapacity for 1824 indexes. If set to `NONE` (the default), ConsumedCapacity is not 1825 included in the response. 1826 1827 :type projection_expression: string 1828 :param projection_expression: A string that identifies one or more 1829 attributes to retrieve from the table. These attributes can include 1830 scalars, sets, or elements of a JSON document. The attributes in 1831 the expression must be separated by commas. 1832 If no attribute names are specified, then all attributes will be 1833 returned. If any of the requested attributes are not found, they 1834 will not appear in the result. 1835 1836 For more information on projection expressions, go to `Accessing Item 1837 Attributes`_ in the Amazon DynamoDB Developer Guide . 1838 1839 :type filter_expression: string 1840 :param filter_expression: A condition that evaluates the query results 1841 after the items are read and returns only the desired values. 1842 The condition you specify is applied to the items queried; any items 1843 that do not match the expression are not returned. 1844 Filter expressions are applied after the items are read, so they do not 1845 limit the capacity used. 1846 A FilterExpression has the same syntax as a ConditionExpression . For 1847 more information on expression syntax, go to `Specifying 1848 Conditions`_ in the Amazon DynamoDB Developer Guide . 1849 1850 :type expression_attribute_names: map 1851 :param expression_attribute_names: One or more substitution tokens for 1852 simplifying complex expressions. The following are some use cases 1853 for using ExpressionAttributeNames : 1854 1855 + To shorten an attribute name that is very long or unwieldy in an 1856 expression. 1857 + To create a placeholder for repeating occurrences of an attribute 1858 name in an expression. 1859 + To prevent special characters in an attribute name from being 1860 misinterpreted in an expression. 1861 1862 1863 Use the **#** character in an expression to dereference an attribute 1864 name. For example, consider the following expression: 1865 1866 1867 + `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName 1868 = "Jones"` 1869 1870 1871 Now suppose that you specified the following for 1872 ExpressionAttributeNames : 1873 1874 1875 + `{"#name":"order.customerInfo.LastName"}` 1876 1877 1878 The expression can now be simplified as follows: 1879 1880 1881 + `#name = "Smith" OR #name = "Jones"` 1882 1883 1884 For more information on expression attribute names, go to `Accessing 1885 Item Attributes`_ in the Amazon DynamoDB Developer Guide . 1886 1887 :type expression_attribute_values: map 1888 :param expression_attribute_values: One or more values that can be 1889 substituted in an expression. 1890 Use the **:** (colon) character in an expression to dereference an 1891 attribute value. For example, suppose that you wanted to check 1892 whether the value of the ProductStatus attribute was one of the 1893 following: 1894 1895 `Available | Backordered | Discontinued` 1896 1897 You would first need to specify ExpressionAttributeValues as follows: 1898 1899 `{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, 1900 ":disc":{"S":"Discontinued"} }` 1901 1902 You could then use these values in an expression, such as this: 1903 1904 `ProductStatus IN (:avail, :back, :disc)` 1905 1906 For more information on expression attribute values, go to `Specifying 1907 Conditions`_ in the Amazon DynamoDB Developer Guide . 1908 1909 """ 1910 params = { 1911 'TableName': table_name, 1912 'KeyConditions': key_conditions, 1913 } 1914 if index_name is not None: 1915 params['IndexName'] = index_name 1916 if select is not None: 1917 params['Select'] = select 1918 if attributes_to_get is not None: 1919 params['AttributesToGet'] = attributes_to_get 1920 if limit is not None: 1921 params['Limit'] = limit 1922 if consistent_read is not None: 1923 params['ConsistentRead'] = consistent_read 1924 if query_filter is not None: 1925 params['QueryFilter'] = query_filter 1926 if conditional_operator is not None: 1927 params['ConditionalOperator'] = conditional_operator 1928 if scan_index_forward is not None: 1929 params['ScanIndexForward'] = scan_index_forward 1930 if exclusive_start_key is not None: 1931 params['ExclusiveStartKey'] = exclusive_start_key 1932 if return_consumed_capacity is not None: 1933 params['ReturnConsumedCapacity'] = return_consumed_capacity 1934 if projection_expression is not None: 1935 params['ProjectionExpression'] = projection_expression 1936 if filter_expression is not None: 1937 params['FilterExpression'] = filter_expression 1938 if expression_attribute_names is not None: 1939 params['ExpressionAttributeNames'] = expression_attribute_names 1940 if expression_attribute_values is not None: 1941 params['ExpressionAttributeValues'] = expression_attribute_values 1942 return self.make_request(action='Query', 1943 body=json.dumps(params)) 1944 1945 def scan(self, table_name, attributes_to_get=None, limit=None, 1946 select=None, scan_filter=None, conditional_operator=None, 1947 exclusive_start_key=None, return_consumed_capacity=None, 1948 total_segments=None, segment=None, projection_expression=None, 1949 filter_expression=None, expression_attribute_names=None, 1950 expression_attribute_values=None): 1951 """ 1952 The Scan operation returns one or more items and item 1953 attributes by accessing every item in the table. To have 1954 DynamoDB return fewer items, you can provide a ScanFilter 1955 operation. 1956 1957 If the total number of scanned items exceeds the maximum data 1958 set size limit of 1 MB, the scan stops and results are 1959 returned to the user as a LastEvaluatedKey value to continue 1960 the scan in a subsequent operation. The results also include 1961 the number of items exceeding the limit. A scan can result in 1962 no table data meeting the filter criteria. 1963 1964 The result set is eventually consistent. 1965 1966 By default, Scan operations proceed sequentially; however, for 1967 faster performance on large tables, applications can request a 1968 parallel Scan operation by specifying the Segment and 1969 TotalSegments parameters. For more information, see `Parallel 1970 Scan`_ in the Amazon DynamoDB Developer Guide . 1971 1972 :type table_name: string 1973 :param table_name: The name of the table containing the requested 1974 items. 1975 1976 :type attributes_to_get: list 1977 :param attributes_to_get: 1978 There is a newer parameter available. Use ProjectionExpression instead. 1979 Note that if you use AttributesToGet and ProjectionExpression at 1980 the same time, DynamoDB will return a ValidationException 1981 exception. 1982 1983 This parameter allows you to retrieve lists or maps; however, it cannot 1984 retrieve individual list or map elements. 1985 1986 The names of one or more attributes to retrieve. If no attribute names 1987 are specified, then all attributes will be returned. If any of the 1988 requested attributes are not found, they will not appear in the 1989 result. 1990 1991 Note that AttributesToGet has no effect on provisioned throughput 1992 consumption. DynamoDB determines capacity units consumed based on 1993 item size, not on the amount of data that is returned to an 1994 application. 1995 1996 :type limit: integer 1997 :param limit: The maximum number of items to evaluate (not necessarily 1998 the number of matching items). If DynamoDB processes the number of 1999 items up to the limit while processing the results, it stops the 2000 operation and returns the matching values up to that point, and a 2001 key in LastEvaluatedKey to apply in a subsequent operation, so that 2002 you can pick up where you left off. Also, if the processed data set 2003 size exceeds 1 MB before DynamoDB reaches this limit, it stops the 2004 operation and returns the matching values up to the limit, and a 2005 key in LastEvaluatedKey to apply in a subsequent operation to 2006 continue the operation. For more information, see `Query and Scan`_ 2007 in the Amazon DynamoDB Developer Guide . 2008 2009 :type select: string 2010 :param select: The attributes to be returned in the result. You can 2011 retrieve all item attributes, specific item attributes, or the 2012 count of matching items. 2013 2014 + `ALL_ATTRIBUTES` - Returns all of the item attributes. 2015 + `COUNT` - Returns the number of matching items, rather than the 2016 matching items themselves. 2017 + `SPECIFIC_ATTRIBUTES` - Returns only the attributes listed in 2018 AttributesToGet . This return value is equivalent to specifying 2019 AttributesToGet without specifying any value for Select . 2020 2021 2022 If neither Select nor AttributesToGet are specified, DynamoDB defaults 2023 to `ALL_ATTRIBUTES`. You cannot use both AttributesToGet and Select 2024 together in a single request, unless the value for Select is 2025 `SPECIFIC_ATTRIBUTES`. (This usage is equivalent to specifying 2026 AttributesToGet without any value for Select .) 2027 2028 :type scan_filter: map 2029 :param scan_filter: 2030 There is a newer parameter available. Use FilterExpression instead. 2031 Note that if you use ScanFilter and FilterExpression at the same 2032 time, DynamoDB will return a ValidationException exception. 2033 2034 This parameter does not support lists or maps. 2035 2036 A condition that evaluates the scan results and returns only the 2037 desired values. 2038 2039 If you specify more than one condition in the ScanFilter map, then by 2040 default all of the conditions must evaluate to true. In other 2041 words, the conditions are ANDed together. (You can use the 2042 ConditionalOperator parameter to OR the conditions instead. If you 2043 do this, then at least one of the conditions must evaluate to true, 2044 rather than all of them.) 2045 2046 Each ScanFilter element consists of an attribute name to compare, along 2047 with the following: 2048 2049 2050 + AttributeValueList - One or more values to evaluate against the 2051 supplied attribute. The number of values in the list depends on the 2052 operator specified in ComparisonOperator . For type Number, value 2053 comparisons are numeric. String value comparisons for greater than, 2054 equals, or less than are based on ASCII character code values. For 2055 example, `a` is greater than `A`, and `a` is greater than `B`. For 2056 a list of code values, see 2057 `http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_. 2058 For Binary, DynamoDB treats each byte of the binary data as 2059 unsigned when it compares binary values, for example when 2060 evaluating query expressions. For information on specifying data 2061 types in JSON, see `JSON Data Format`_ in the Amazon DynamoDB 2062 Developer Guide . 2063 + ComparisonOperator - A comparator for evaluating attributes. For 2064 example, equals, greater than, less than, etc. The following 2065 comparison operators are available: `EQ | NE | LE | LT | GE | GT | 2066 NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | 2067 BETWEEN` For complete descriptions of all comparison operators, see 2068 `Condition`_. 2069 2070 :type conditional_operator: string 2071 :param conditional_operator: 2072 There is a newer parameter available. Use ConditionExpression instead. 2073 Note that if you use ConditionalOperator and ConditionExpression at 2074 the same time, DynamoDB will return a ValidationException 2075 exception. 2076 2077 This parameter does not support lists or maps. 2078 2079 A logical operator to apply to the conditions in the ScanFilter map: 2080 2081 2082 + `AND` - If all of the conditions evaluate to true, then the entire 2083 map evaluates to true. 2084 + `OR` - If at least one of the conditions evaluate to true, then the 2085 entire map evaluates to true. 2086 2087 2088 If you omit ConditionalOperator , then `AND` is the default. 2089 2090 The operation will succeed only if the entire map evaluates to true. 2091 2092 :type exclusive_start_key: map 2093 :param exclusive_start_key: The primary key of the first item that this 2094 operation will evaluate. Use the value that was returned for 2095 LastEvaluatedKey in the previous operation. 2096 The data type for ExclusiveStartKey must be String, Number or Binary. 2097 No set data types are allowed. 2098 2099 In a parallel scan, a Scan request that includes ExclusiveStartKey must 2100 specify the same segment whose previous Scan returned the 2101 corresponding value of LastEvaluatedKey . 2102 2103 :type return_consumed_capacity: string 2104 :param return_consumed_capacity: A value that if set to `TOTAL`, the 2105 response includes ConsumedCapacity data for tables and indexes. If 2106 set to `INDEXES`, the response includes ConsumedCapacity for 2107 indexes. If set to `NONE` (the default), ConsumedCapacity is not 2108 included in the response. 2109 2110 :type total_segments: integer 2111 :param total_segments: For a parallel Scan request, TotalSegments 2112 represents the total number of segments into which the Scan 2113 operation will be divided. The value of TotalSegments corresponds 2114 to the number of application workers that will perform the parallel 2115 scan. For example, if you want to scan a table using four 2116 application threads, specify a TotalSegments value of 4. 2117 The value for TotalSegments must be greater than or equal to 1, and 2118 less than or equal to 1000000. If you specify a TotalSegments value 2119 of 1, the Scan operation will be sequential rather than parallel. 2120 2121 If you specify TotalSegments , you must also specify Segment . 2122 2123 :type segment: integer 2124 :param segment: For a parallel Scan request, Segment identifies an 2125 individual segment to be scanned by an application worker. 2126 Segment IDs are zero-based, so the first segment is always 0. For 2127 example, if you want to scan a table using four application 2128 threads, the first thread specifies a Segment value of 0, the 2129 second thread specifies 1, and so on. 2130 2131 The value of LastEvaluatedKey returned from a parallel Scan request 2132 must be used as ExclusiveStartKey with the same segment ID in a 2133 subsequent Scan operation. 2134 2135 The value for Segment must be greater than or equal to 0, and less than 2136 the value provided for TotalSegments . 2137 2138 If you specify Segment , you must also specify TotalSegments . 2139 2140 :type projection_expression: string 2141 :param projection_expression: A string that identifies one or more 2142 attributes to retrieve from the table. These attributes can include 2143 scalars, sets, or elements of a JSON document. The attributes in 2144 the expression must be separated by commas. 2145 If no attribute names are specified, then all attributes will be 2146 returned. If any of the requested attributes are not found, they 2147 will not appear in the result. 2148 2149 For more information on projection expressions, go to `Accessing Item 2150 Attributes`_ in the Amazon DynamoDB Developer Guide . 2151 2152 :type filter_expression: string 2153 :param filter_expression: A condition that evaluates the scan results 2154 and returns only the desired values. 2155 The condition you specify is applied to the items scanned; any items 2156 that do not match the expression are not returned. 2157 2158 :type expression_attribute_names: map 2159 :param expression_attribute_names: One or more substitution tokens for 2160 simplifying complex expressions. The following are some use cases 2161 for using ExpressionAttributeNames : 2162 2163 + To shorten an attribute name that is very long or unwieldy in an 2164 expression. 2165 + To create a placeholder for repeating occurrences of an attribute 2166 name in an expression. 2167 + To prevent special characters in an attribute name from being 2168 misinterpreted in an expression. 2169 2170 2171 Use the **#** character in an expression to dereference an attribute 2172 name. For example, consider the following expression: 2173 2174 2175 + `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName 2176 = "Jones"` 2177 2178 2179 Now suppose that you specified the following for 2180 ExpressionAttributeNames : 2181 2182 2183 + `{"#name":"order.customerInfo.LastName"}` 2184 2185 2186 The expression can now be simplified as follows: 2187 2188 2189 + `#name = "Smith" OR #name = "Jones"` 2190 2191 2192 For more information on expression attribute names, go to `Accessing 2193 Item Attributes`_ in the Amazon DynamoDB Developer Guide . 2194 2195 :type expression_attribute_values: map 2196 :param expression_attribute_values: One or more values that can be 2197 substituted in an expression. 2198 Use the **:** (colon) character in an expression to dereference an 2199 attribute value. For example, suppose that you wanted to check 2200 whether the value of the ProductStatus attribute was one of the 2201 following: 2202 2203 `Available | Backordered | Discontinued` 2204 2205 You would first need to specify ExpressionAttributeValues as follows: 2206 2207 `{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, 2208 ":disc":{"S":"Discontinued"} }` 2209 2210 You could then use these values in an expression, such as this: 2211 2212 `ProductStatus IN (:avail, :back, :disc)` 2213 2214 For more information on expression attribute values, go to `Specifying 2215 Conditions`_ in the Amazon DynamoDB Developer Guide . 2216 2217 """ 2218 params = {'TableName': table_name, } 2219 if attributes_to_get is not None: 2220 params['AttributesToGet'] = attributes_to_get 2221 if limit is not None: 2222 params['Limit'] = limit 2223 if select is not None: 2224 params['Select'] = select 2225 if scan_filter is not None: 2226 params['ScanFilter'] = scan_filter 2227 if conditional_operator is not None: 2228 params['ConditionalOperator'] = conditional_operator 2229 if exclusive_start_key is not None: 2230 params['ExclusiveStartKey'] = exclusive_start_key 2231 if return_consumed_capacity is not None: 2232 params['ReturnConsumedCapacity'] = return_consumed_capacity 2233 if total_segments is not None: 2234 params['TotalSegments'] = total_segments 2235 if segment is not None: 2236 params['Segment'] = segment 2237 if projection_expression is not None: 2238 params['ProjectionExpression'] = projection_expression 2239 if filter_expression is not None: 2240 params['FilterExpression'] = filter_expression 2241 if expression_attribute_names is not None: 2242 params['ExpressionAttributeNames'] = expression_attribute_names 2243 if expression_attribute_values is not None: 2244 params['ExpressionAttributeValues'] = expression_attribute_values 2245 return self.make_request(action='Scan', 2246 body=json.dumps(params)) 2247 2248 def update_item(self, table_name, key, attribute_updates=None, 2249 expected=None, conditional_operator=None, 2250 return_values=None, return_consumed_capacity=None, 2251 return_item_collection_metrics=None, 2252 update_expression=None, condition_expression=None, 2253 expression_attribute_names=None, 2254 expression_attribute_values=None): 2255 """ 2256 Edits an existing item's attributes, or adds a new item to the 2257 table if it does not already exist. You can put, delete, or 2258 add attribute values. You can also perform a conditional 2259 update (insert a new attribute name-value pair if it doesn't 2260 exist, or replace an existing name-value pair if it has 2261 certain expected attribute values). 2262 2263 You can also return the item's attribute values in the same 2264 UpdateItem operation using the ReturnValues parameter. 2265 2266 :type table_name: string 2267 :param table_name: The name of the table containing the item to update. 2268 2269 :type key: map 2270 :param key: The primary key of the item to be updated. Each element 2271 consists of an attribute name and a value for that attribute. 2272 For the primary key, you must provide all of the attributes. For 2273 example, with a hash type primary key, you only need to specify the 2274 hash attribute. For a hash-and-range type primary key, you must 2275 specify both the hash attribute and the range attribute. 2276 2277 :type attribute_updates: map 2278 :param attribute_updates: 2279 There is a newer parameter available. Use UpdateExpression instead. 2280 Note that if you use AttributeUpdates and UpdateExpression at the 2281 same time, DynamoDB will return a ValidationException exception. 2282 2283 This parameter can be used for modifying top-level attributes; however, 2284 it does not support individual list or map elements. 2285 2286 The names of attributes to be modified, the action to perform on each, 2287 and the new value for each. If you are updating an attribute that 2288 is an index key attribute for any indexes on that table, the 2289 attribute type must match the index key type defined in the 2290 AttributesDefinition of the table description. You can use 2291 UpdateItem to update any nonkey attributes. 2292 2293 Attribute values cannot be null. String and Binary type attributes must 2294 have lengths greater than zero. Set type attributes must not be 2295 empty. Requests with empty values will be rejected with a 2296 ValidationException exception. 2297 2298 Each AttributeUpdates element consists of an attribute name to modify, 2299 along with the following: 2300 2301 2302 + Value - The new value, if applicable, for this attribute. 2303 + Action - A value that specifies how to perform the update. This 2304 action is only valid for an existing attribute whose data type is 2305 Number or is a set; do not use `ADD` for other data types. If an 2306 item with the specified primary key is found in the table, the 2307 following values perform the following actions: 2308 2309 + `PUT` - Adds the specified attribute to the item. If the attribute 2310 already exists, it is replaced by the new value. 2311 + `DELETE` - Removes the attribute and its value, if no value is 2312 specified for `DELETE`. The data type of the specified value must 2313 match the existing value's data type. If a set of values is 2314 specified, then those values are subtracted from the old set. For 2315 example, if the attribute value was the set `[a,b,c]` and the 2316 `DELETE` action specifies `[a,c]`, then the final attribute value 2317 is `[b]`. Specifying an empty set is an error. 2318 + `ADD` - Adds the specified value to the item, if the attribute does 2319 not already exist. If the attribute does exist, then the behavior 2320 of `ADD` depends on the data type of the attribute: 2321 2322 + If the existing attribute is a number, and if Value is also a number, 2323 then Value is mathematically added to the existing attribute. If 2324 Value is a negative number, then it is subtracted from the existing 2325 attribute. If you use `ADD` to increment or decrement a number 2326 value for an item that doesn't exist before the update, DynamoDB 2327 uses 0 as the initial value. Similarly, if you use `ADD` for an 2328 existing item to increment or decrement an attribute value that 2329 doesn't exist before the update, DynamoDB uses `0` as the initial 2330 value. For example, suppose that the item you want to update 2331 doesn't have an attribute named itemcount , but you decide to `ADD` 2332 the number `3` to this attribute anyway. DynamoDB will create the 2333 itemcount attribute, set its initial value to `0`, and finally add 2334 `3` to it. The result will be a new itemcount attribute, with a 2335 value of `3`. 2336 + If the existing data type is a set, and if Value is also a set, then 2337 Value is appended to the existing set. For example, if the 2338 attribute value is the set `[1,2]`, and the `ADD` action specified 2339 `[3]`, then the final attribute value is `[1,2,3]`. An error occurs 2340 if an `ADD` action is specified for a set attribute and the 2341 attribute type specified does not match the existing set type. Both 2342 sets must have the same primitive data type. For example, if the 2343 existing data type is a set of strings, Value must also be a set of 2344 strings. 2345 2346 If no item with the specified key is found in the table, the following 2347 values perform the following actions: 2348 2349 + `PUT` - Causes DynamoDB to create a new item with the specified 2350 primary key, and then adds the attribute. 2351 + `DELETE` - Nothing happens, because attributes cannot be deleted from 2352 a nonexistent item. The operation succeeds, but DynamoDB does not 2353 create a new item. 2354 + `ADD` - Causes DynamoDB to create an item with the supplied primary 2355 key and number (or set of numbers) for the attribute value. The 2356 only data types allowed are Number and Number Set. 2357 2358 2359 2360 If you specify any attributes that are part of an index key, then the 2361 data types for those attributes must match those of the schema in 2362 the table's attribute definition. 2363 2364 :type expected: map 2365 :param expected: 2366 There is a newer parameter available. Use ConditionExpression instead. 2367 Note that if you use Expected and ConditionExpression at the same 2368 time, DynamoDB will return a ValidationException exception. 2369 2370 This parameter does not support lists or maps. 2371 2372 A map of attribute/condition pairs. Expected provides a conditional 2373 block for the UpdateItem operation. 2374 2375 Each element of Expected consists of an attribute name, a comparison 2376 operator, and one or more values. DynamoDB compares the attribute 2377 with the value(s) you supplied, using the comparison operator. For 2378 each Expected element, the result of the evaluation is either true 2379 or false. 2380 2381 If you specify more than one element in the Expected map, then by 2382 default all of the conditions must evaluate to true. In other 2383 words, the conditions are ANDed together. (You can use the 2384 ConditionalOperator parameter to OR the conditions instead. If you 2385 do this, then at least one of the conditions must evaluate to true, 2386 rather than all of them.) 2387 2388 If the Expected map evaluates to true, then the conditional operation 2389 succeeds; otherwise, it fails. 2390 2391 Expected contains the following: 2392 2393 2394 + AttributeValueList - One or more values to evaluate against the 2395 supplied attribute. The number of values in the list depends on the 2396 ComparisonOperator being used. For type Number, value comparisons 2397 are numeric. String value comparisons for greater than, equals, or 2398 less than are based on ASCII character code values. For example, 2399 `a` is greater than `A`, and `a` is greater than `B`. For a list of 2400 code values, see 2401 `http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_. 2402 For type Binary, DynamoDB treats each byte of the binary data as 2403 unsigned when it compares binary values, for example when 2404 evaluating query expressions. 2405 + ComparisonOperator - A comparator for evaluating attributes in the 2406 AttributeValueList . When performing the comparison, DynamoDB uses 2407 strongly consistent reads. The following comparison operators are 2408 available: `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | 2409 CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN` The following 2410 are descriptions of each comparison operator. 2411 2412 + `EQ` : Equal. `EQ` is supported for all datatypes, including lists 2413 and maps. AttributeValueList can contain only one AttributeValue 2414 element of type String, Number, Binary, String Set, Number Set, or 2415 Binary Set. If an item contains an AttributeValue element of a 2416 different type than the one specified in the request, the value 2417 does not match. For example, `{"S":"6"}` does not equal 2418 `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", 2419 "1"]}`. > <li> 2420 + `NE` : Not equal. `NE` is supported for all datatypes, including 2421 lists and maps. AttributeValueList can contain only one 2422 AttributeValue of type String, Number, Binary, String Set, Number 2423 Set, or Binary Set. If an item contains an AttributeValue of a 2424 different type than the one specified in the request, the value 2425 does not match. For example, `{"S":"6"}` does not equal 2426 `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", 2427 "1"]}`. > <li> 2428 + `LE` : Less than or equal. AttributeValueList can contain only one 2429 AttributeValue element of type String, Number, or Binary (not a set 2430 type). If an item contains an AttributeValue element of a different 2431 type than the one specified in the request, the value does not 2432 match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 2433 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 2434 + `LT` : Less than. AttributeValueList can contain only one 2435 AttributeValue of type String, Number, or Binary (not a set type). 2436 If an item contains an AttributeValue element of a different type 2437 than the one specified in the request, the value does not match. 2438 For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 2439 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 2440 + `GE` : Greater than or equal. AttributeValueList can contain only one 2441 AttributeValue element of type String, Number, or Binary (not a set 2442 type). If an item contains an AttributeValue element of a different 2443 type than the one specified in the request, the value does not 2444 match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 2445 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 2446 + `GT` : Greater than. AttributeValueList can contain only one 2447 AttributeValue element of type String, Number, or Binary (not a set 2448 type). If an item contains an AttributeValue element of a different 2449 type than the one specified in the request, the value does not 2450 match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, 2451 `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> 2452 + `NOT_NULL` : The attribute exists. `NOT_NULL` is supported for all 2453 datatypes, including lists and maps. This operator tests for the 2454 existence of an attribute, not its data type. If the data type of 2455 attribute " `a`" is null, and you evaluate it using `NOT_NULL`, the 2456 result is a Boolean true . This result is because the attribute " 2457 `a`" exists; its data type is not relevant to the `NOT_NULL` 2458 comparison operator. 2459 + `NULL` : The attribute does not exist. `NULL` is supported for all 2460 datatypes, including lists and maps. This operator tests for the 2461 nonexistence of an attribute, not its data type. If the data type 2462 of attribute " `a`" is null, and you evaluate it using `NULL`, the 2463 result is a Boolean false . This is because the attribute " `a`" 2464 exists; its data type is not relevant to the `NULL` comparison 2465 operator. 2466 + `CONTAINS` : Checks for a subsequence, or value in a set. 2467 AttributeValueList can contain only one AttributeValue element of 2468 type String, Number, or Binary (not a set type). If the target 2469 attribute of the comparison is of type String, then the operator 2470 checks for a substring match. If the target attribute of the 2471 comparison is of type Binary, then the operator looks for a 2472 subsequence of the target that matches the input. If the target 2473 attribute of the comparison is a set (" `SS`", " `NS`", or " 2474 `BS`"), then the operator evaluates to true if it finds an exact 2475 match with any member of the set. CONTAINS is supported for lists: 2476 When evaluating " `a CONTAINS b`", " `a`" can be a list; however, " 2477 `b`" cannot be a set, a map, or a list. 2478 + `NOT_CONTAINS` : Checks for absence of a subsequence, or absence of a 2479 value in a set. AttributeValueList can contain only one 2480 AttributeValue element of type String, Number, or Binary (not a set 2481 type). If the target attribute of the comparison is a String, then 2482 the operator checks for the absence of a substring match. If the 2483 target attribute of the comparison is Binary, then the operator 2484 checks for the absence of a subsequence of the target that matches 2485 the input. If the target attribute of the comparison is a set (" 2486 `SS`", " `NS`", or " `BS`"), then the operator evaluates to true if 2487 it does not find an exact match with any member of the set. 2488 NOT_CONTAINS is supported for lists: When evaluating " `a NOT 2489 CONTAINS b`", " `a`" can be a list; however, " `b`" cannot be a 2490 set, a map, or a list. 2491 + `BEGINS_WITH` : Checks for a prefix. AttributeValueList can contain 2492 only one AttributeValue of type String or Binary (not a Number or a 2493 set type). The target attribute of the comparison must be of type 2494 String or Binary (not a Number or a set type). > <li> 2495 + `IN` : Checks for matching elements within two sets. 2496 AttributeValueList can contain one or more AttributeValue elements 2497 of type String, Number, or Binary (not a set type). These 2498 attributes are compared against an existing set type attribute of 2499 an item. If any elements of the input set are present in the item 2500 attribute, the expression evaluates to true. 2501 + `BETWEEN` : Greater than or equal to the first value, and less than 2502 or equal to the second value. AttributeValueList must contain two 2503 AttributeValue elements of the same type, either String, Number, or 2504 Binary (not a set type). A target attribute matches if the target 2505 value is greater than, or equal to, the first element and less 2506 than, or equal to, the second element. If an item contains an 2507 AttributeValue element of a different type than the one specified 2508 in the request, the value does not match. For example, `{"S":"6"}` 2509 does not compare to `{"N":"6"}`. Also, `{"N":"6"}` does not compare 2510 to `{"NS":["6", "2", "1"]}` 2511 2512 2513 2514 For usage examples of AttributeValueList and ComparisonOperator , see 2515 `Legacy Conditional Parameters`_ in the Amazon DynamoDB Developer 2516 Guide . 2517 2518 For backward compatibility with previous DynamoDB releases, the 2519 following parameters can be used instead of AttributeValueList and 2520 ComparisonOperator : 2521 2522 2523 + Value - A value for DynamoDB to compare with an attribute. 2524 + Exists - A Boolean value that causes DynamoDB to evaluate the value 2525 before attempting the conditional operation: 2526 2527 + If Exists is `True`, DynamoDB will check to see if that attribute 2528 value already exists in the table. If it is found, then the 2529 condition evaluates to true; otherwise the condition evaluate to 2530 false. 2531 + If Exists is `False`, DynamoDB assumes that the attribute value does 2532 not exist in the table. If in fact the value does not exist, then 2533 the assumption is valid and the condition evaluates to true. If the 2534 value is found, despite the assumption that it does not exist, the 2535 condition evaluates to false. 2536 Note that the default value for Exists is `True`. 2537 2538 2539 The Value and Exists parameters are incompatible with 2540 AttributeValueList and ComparisonOperator . Note that if you use 2541 both sets of parameters at once, DynamoDB will return a 2542 ValidationException exception. 2543 2544 :type conditional_operator: string 2545 :param conditional_operator: 2546 There is a newer parameter available. Use ConditionExpression instead. 2547 Note that if you use ConditionalOperator and ConditionExpression at 2548 the same time, DynamoDB will return a ValidationException 2549 exception. 2550 2551 This parameter does not support lists or maps. 2552 2553 A logical operator to apply to the conditions in the Expected map: 2554 2555 2556 + `AND` - If all of the conditions evaluate to true, then the entire 2557 map evaluates to true. 2558 + `OR` - If at least one of the conditions evaluate to true, then the 2559 entire map evaluates to true. 2560 2561 2562 If you omit ConditionalOperator , then `AND` is the default. 2563 2564 The operation will succeed only if the entire map evaluates to true. 2565 2566 :type return_values: string 2567 :param return_values: 2568 Use ReturnValues if you want to get the item attributes as they 2569 appeared either before or after they were updated. For UpdateItem , 2570 the valid values are: 2571 2572 2573 + `NONE` - If ReturnValues is not specified, or if its value is `NONE`, 2574 then nothing is returned. (This setting is the default for 2575 ReturnValues .) 2576 + `ALL_OLD` - If UpdateItem overwrote an attribute name-value pair, 2577 then the content of the old item is returned. 2578 + `UPDATED_OLD` - The old versions of only the updated attributes are 2579 returned. 2580 + `ALL_NEW` - All of the attributes of the new version of the item are 2581 returned. 2582 + `UPDATED_NEW` - The new versions of only the updated attributes are 2583 returned. 2584 2585 :type return_consumed_capacity: string 2586 :param return_consumed_capacity: A value that if set to `TOTAL`, the 2587 response includes ConsumedCapacity data for tables and indexes. If 2588 set to `INDEXES`, the response includes ConsumedCapacity for 2589 indexes. If set to `NONE` (the default), ConsumedCapacity is not 2590 included in the response. 2591 2592 :type return_item_collection_metrics: string 2593 :param return_item_collection_metrics: A value that if set to `SIZE`, 2594 the response includes statistics about item collections, if any, 2595 that were modified during the operation are returned in the 2596 response. If set to `NONE` (the default), no statistics are 2597 returned. 2598 2599 :type update_expression: string 2600 :param update_expression: An expression that defines one or more 2601 attributes to be updated, the action to be performed on them, and 2602 new value(s) for them. 2603 The following action values are available for UpdateExpression . 2604 2605 2606 + `SET` - Adds one or more attributes and values to an item. If any of 2607 these attribute already exist, they are replaced by the new values. 2608 You can also use `SET` to add or subtract from an attribute that is 2609 of type Number. `SET` supports the following functions: 2610 2611 + `if_not_exists (path, operand)` - if the item does not contain an 2612 attribute at the specified path, then `if_not_exists` evaluates to 2613 operand; otherwise, it evaluates to path. You can use this function 2614 to avoid overwriting an attribute that may already be present in 2615 the item. 2616 + `list_append (operand, operand)` - evaluates to a list with a new 2617 element added to it. You can append the new element to the start or 2618 the end of the list by reversing the order of the operands. 2619 These function names are case-sensitive. 2620 + `REMOVE` - Removes one or more attributes from an item. 2621 + `ADD` - Adds the specified value to the item, if the attribute does 2622 not already exist. If the attribute does exist, then the behavior 2623 of `ADD` depends on the data type of the attribute: 2624 2625 + If the existing attribute is a number, and if Value is also a number, 2626 then Value is mathematically added to the existing attribute. If 2627 Value is a negative number, then it is subtracted from the existing 2628 attribute. If you use `ADD` to increment or decrement a number 2629 value for an item that doesn't exist before the update, DynamoDB 2630 uses `0` as the initial value. Similarly, if you use `ADD` for an 2631 existing item to increment or decrement an attribute value that 2632 doesn't exist before the update, DynamoDB uses `0` as the initial 2633 value. For example, suppose that the item you want to update 2634 doesn't have an attribute named itemcount , but you decide to `ADD` 2635 the number `3` to this attribute anyway. DynamoDB will create the 2636 itemcount attribute, set its initial value to `0`, and finally add 2637 `3` to it. The result will be a new itemcount attribute in the 2638 item, with a value of `3`. 2639 + If the existing data type is a set and if Value is also a set, then 2640 Value is added to the existing set. For example, if the attribute 2641 value is the set `[1,2]`, and the `ADD` action specified `[3]`, 2642 then the final attribute value is `[1,2,3]`. An error occurs if an 2643 `ADD` action is specified for a set attribute and the attribute 2644 type specified does not match the existing set type. Both sets must 2645 have the same primitive data type. For example, if the existing 2646 data type is a set of strings, the Value must also be a set of 2647 strings. 2648 The `ADD` action only supports Number and set data types. In addition, 2649 `ADD` can only be used on top-level attributes, not nested 2650 attributes. 2651 + `DELETE` - Deletes an element from a set. If a set of values is 2652 specified, then those values are subtracted from the old set. For 2653 example, if the attribute value was the set `[a,b,c]` and the 2654 `DELETE` action specifies `[a,c]`, then the final attribute value 2655 is `[b]`. Specifying an empty set is an error. The `DELETE` action 2656 only supports Number and set data types. In addition, `DELETE` can 2657 only be used on top-level attributes, not nested attributes. 2658 2659 2660 You can have many actions in a single expression, such as the 2661 following: `SET a=:value1, b=:value2 DELETE :value3, :value4, 2662 :value5` 2663 2664 For more information on update expressions, go to `Modifying Items and 2665 Attributes`_ in the Amazon DynamoDB Developer Guide . 2666 2667 :type condition_expression: string 2668 :param condition_expression: A condition that must be satisfied in 2669 order for a conditional update to succeed. 2670 An expression can contain any of the following: 2671 2672 2673 + Boolean functions: `attribute_exists | attribute_not_exists | 2674 contains | begins_with` These function names are case-sensitive. 2675 + Comparison operators: ` = | <> | < | > | <= 2676 | >= | BETWEEN | IN` 2677 + Logical operators: `AND | OR | NOT` 2678 2679 2680 For more information on condition expressions, go to `Specifying 2681 Conditions`_ in the Amazon DynamoDB Developer Guide . 2682 2683 :type expression_attribute_names: map 2684 :param expression_attribute_names: One or more substitution tokens for 2685 simplifying complex expressions. The following are some use cases 2686 for using ExpressionAttributeNames : 2687 2688 + To shorten an attribute name that is very long or unwieldy in an 2689 expression. 2690 + To create a placeholder for repeating occurrences of an attribute 2691 name in an expression. 2692 + To prevent special characters in an attribute name from being 2693 misinterpreted in an expression. 2694 2695 2696 Use the **#** character in an expression to dereference an attribute 2697 name. For example, consider the following expression: 2698 2699 2700 + `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName 2701 = "Jones"` 2702 2703 2704 Now suppose that you specified the following for 2705 ExpressionAttributeNames : 2706 2707 2708 + `{"#name":"order.customerInfo.LastName"}` 2709 2710 2711 The expression can now be simplified as follows: 2712 2713 2714 + `#name = "Smith" OR #name = "Jones"` 2715 2716 2717 For more information on expression attribute names, go to `Accessing 2718 Item Attributes`_ in the Amazon DynamoDB Developer Guide . 2719 2720 :type expression_attribute_values: map 2721 :param expression_attribute_values: One or more values that can be 2722 substituted in an expression. 2723 Use the **:** (colon) character in an expression to dereference an 2724 attribute value. For example, suppose that you wanted to check 2725 whether the value of the ProductStatus attribute was one of the 2726 following: 2727 2728 `Available | Backordered | Discontinued` 2729 2730 You would first need to specify ExpressionAttributeValues as follows: 2731 2732 `{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, 2733 ":disc":{"S":"Discontinued"} }` 2734 2735 You could then use these values in an expression, such as this: 2736 2737 `ProductStatus IN (:avail, :back, :disc)` 2738 2739 For more information on expression attribute values, go to `Specifying 2740 Conditions`_ in the Amazon DynamoDB Developer Guide . 2741 2742 """ 2743 params = {'TableName': table_name, 'Key': key, } 2744 if attribute_updates is not None: 2745 params['AttributeUpdates'] = attribute_updates 2746 if expected is not None: 2747 params['Expected'] = expected 2748 if conditional_operator is not None: 2749 params['ConditionalOperator'] = conditional_operator 2750 if return_values is not None: 2751 params['ReturnValues'] = return_values 2752 if return_consumed_capacity is not None: 2753 params['ReturnConsumedCapacity'] = return_consumed_capacity 2754 if return_item_collection_metrics is not None: 2755 params['ReturnItemCollectionMetrics'] = return_item_collection_metrics 2756 if update_expression is not None: 2757 params['UpdateExpression'] = update_expression 2758 if condition_expression is not None: 2759 params['ConditionExpression'] = condition_expression 2760 if expression_attribute_names is not None: 2761 params['ExpressionAttributeNames'] = expression_attribute_names 2762 if expression_attribute_values is not None: 2763 params['ExpressionAttributeValues'] = expression_attribute_values 2764 return self.make_request(action='UpdateItem', 2765 body=json.dumps(params)) 2766 2767 def update_table(self, table_name, provisioned_throughput=None, 2768 global_secondary_index_updates=None, 2769 attribute_definitions=None): 2770 """ 2771 Updates the provisioned throughput for the given table, or 2772 manages the global secondary indexes on the table. 2773 2774 You can increase or decrease the table's provisioned 2775 throughput values within the maximums and minimums listed in 2776 the `Limits`_ section in the Amazon DynamoDB Developer Guide . 2777 2778 In addition, you can use UpdateTable to add, modify or delete 2779 global secondary indexes on the table. For more information, 2780 see `Managing Global Secondary Indexes`_ in the Amazon 2781 DynamoDB Developer Guide . 2782 2783 The table must be in the `ACTIVE` state for UpdateTable to 2784 succeed. UpdateTable is an asynchronous operation; while 2785 executing the operation, the table is in the `UPDATING` state. 2786 While the table is in the `UPDATING` state, the table still 2787 has the provisioned throughput from before the call. The 2788 table's new provisioned throughput settings go into effect 2789 when the table returns to the `ACTIVE` state; at that point, 2790 the UpdateTable operation is complete. 2791 2792 :type attribute_definitions: list 2793 :param attribute_definitions: An array of attributes that describe the 2794 key schema for the table and indexes. If you are adding a new 2795 global secondary index to the table, AttributeDefinitions must 2796 include the key element(s) of the new index. 2797 2798 :type table_name: string 2799 :param table_name: The name of the table to be updated. 2800 2801 :type provisioned_throughput: dict 2802 :param provisioned_throughput: Represents the provisioned throughput 2803 settings for a specified table or index. The settings can be 2804 modified using the UpdateTable operation. 2805 For current minimum and maximum provisioned throughput values, see 2806 `Limits`_ in the Amazon DynamoDB Developer Guide . 2807 2808 :type global_secondary_index_updates: list 2809 :param global_secondary_index_updates: 2810 An array of one or more global secondary indexes for the table. For 2811 each index in the array, you can specify one action: 2812 2813 2814 + Create - add a new global secondary index to the table. 2815 + Update - modify the provisioned throughput settings of an existing 2816 global secondary index. 2817 + Delete - remove a global secondary index from the table. 2818 2819 """ 2820 params = {'TableName': table_name, } 2821 if attribute_definitions is not None: 2822 params['AttributeDefinitions'] = attribute_definitions 2823 if provisioned_throughput is not None: 2824 params['ProvisionedThroughput'] = provisioned_throughput 2825 if global_secondary_index_updates is not None: 2826 params['GlobalSecondaryIndexUpdates'] = global_secondary_index_updates 2827 return self.make_request(action='UpdateTable', 2828 body=json.dumps(params)) 2829 2830 def make_request(self, action, body): 2831 headers = { 2832 'X-Amz-Target': '%s.%s' % (self.TargetPrefix, action), 2833 'Host': self.host, 2834 'Content-Type': 'application/x-amz-json-1.0', 2835 'Content-Length': str(len(body)), 2836 } 2837 http_request = self.build_base_http_request( 2838 method='POST', path='/', auth_path='/', params={}, 2839 headers=headers, data=body, host=self.host) 2840 response = self._mexe(http_request, sender=None, 2841 override_num_retries=self.NumberRetries, 2842 retry_handler=self._retry_handler) 2843 response_body = response.read().decode('utf-8') 2844 boto.log.debug(response_body) 2845 if response.status == 200: 2846 if response_body: 2847 return json.loads(response_body) 2848 else: 2849 json_body = json.loads(response_body) 2850 fault_name = json_body.get('__type', None) 2851 exception_class = self._faults.get(fault_name, self.ResponseError) 2852 raise exception_class(response.status, response.reason, 2853 body=json_body) 2854 2855 def _retry_handler(self, response, i, next_sleep): 2856 status = None 2857 boto.log.debug("Saw HTTP status: %s" % response.status) 2858 if response.status == 400: 2859 response_body = response.read().decode('utf-8') 2860 boto.log.debug(response_body) 2861 data = json.loads(response_body) 2862 if 'ProvisionedThroughputExceededException' in data.get('__type'): 2863 self.throughput_exceeded_events += 1 2864 msg = "%s, retry attempt %s" % ( 2865 'ProvisionedThroughputExceededException', 2866 i 2867 ) 2868 next_sleep = self._truncated_exponential_time(i) 2869 i += 1 2870 status = (msg, i, next_sleep) 2871 if i == self.NumberRetries: 2872 # If this was our last retry attempt, raise 2873 # a specific error saying that the throughput 2874 # was exceeded. 2875 raise exceptions.ProvisionedThroughputExceededException( 2876 response.status, response.reason, data) 2877 elif 'ConditionalCheckFailedException' in data.get('__type'): 2878 raise exceptions.ConditionalCheckFailedException( 2879 response.status, response.reason, data) 2880 elif 'ValidationException' in data.get('__type'): 2881 raise exceptions.ValidationException( 2882 response.status, response.reason, data) 2883 else: 2884 raise self.ResponseError(response.status, response.reason, 2885 data) 2886 expected_crc32 = response.getheader('x-amz-crc32') 2887 if self._validate_checksums and expected_crc32 is not None: 2888 boto.log.debug('Validating crc32 checksum for body: %s', 2889 response.read()) 2890 actual_crc32 = crc32(response.read()) & 0xffffffff 2891 expected_crc32 = int(expected_crc32) 2892 if actual_crc32 != expected_crc32: 2893 msg = ("The calculated checksum %s did not match the expected " 2894 "checksum %s" % (actual_crc32, expected_crc32)) 2895 status = (msg, i + 1, self._truncated_exponential_time(i)) 2896 return status 2897 2898 def _truncated_exponential_time(self, i): 2899 if i == 0: 2900 next_sleep = 0 2901 else: 2902 next_sleep = min(0.05 * (2 ** i), 2903 boto.config.get('Boto', 'max_retry_delay', 60)) 2904 return next_sleep 2905