# Scan **Important** ***This section refers to API version 2011-12-05, which is deprecated and should not be used for new applications.*** **For documentation on the current low-level API, see the [Amazon DynamoDB API Reference](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).** ## Description The `Scan` operation returns one or more items and its attributes by performing a full scan of a table. Provide a `ScanFilter` to get more specific results. **Note** If the total number of scanned items exceeds the 1MB limit, the scan stops and results are returned to the user with a `LastEvaluatedKey` to continue the scan in a subsequent operation. The results also include the number of items exceeding the limit. A scan can result in no table data meeting the filter criteria. The result set is eventually consistent. ## Requests ### Syntax ``` // This header is abbreviated. // For a sample of a complete header, see DynamoDB low-level API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Scan content-type: application/x-amz-json-1.0 {"TableName":"Table1", "Limit": 2, "ScanFilter":{ "AttributeName1":{"AttributeValueList":[{"S":"AttributeValue"}],"ComparisonOperator":"EQ"} }, "ExclusiveStartKey":{ "HashKeyElement":{"S":"AttributeName1"}, "RangeKeyElement":{"N":"AttributeName2"} }, "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]}, } ``` **** | Name | Description | Required | | --- | --- | --- | | TableName | The name of the table containing the requested items. Type: String | Yes | | AttributesToGet | Array of Attribute names. If attribute names are not specified then all attributes will be returned. If some attributes are not found, they will not appear in the result.Type: Array | No | | Limit | The maximum number of items to evaluate (not necessarily the number of matching items). If DynamoDB processes the number of items up to the limit while processing the results, it stops and returns the matching values up to that point, and a `LastEvaluatedKey` to apply in a subsequent operation to continue retrieving items. Also, if the scanned data set size exceeds 1MB before DynamoDB reaches this limit, it stops the scan and returns the matching values up to the limit, and a `LastEvaluatedKey` to apply in a subsequent operation to continue the scan.Type: Number | No | | Count | If set to `true`, DynamoDB returns a total number of items for the Scan operation, even if the operation has no matching items for the assigned filter. You can apply the Limit parameter to count-only scans. Do not set `Count` to `true` while providing a list of `AttributesToGet`, otherwise DynamoDB returns a validation error. For more information, see [Counting the items in the results](Scan.md#Scan.Count).Type: Boolean | No | | ScanFilter | Evaluates the scan results and returns only the desired values. Multiple conditions are treated as "AND" operations: all conditions must be met to be included in the results. Type: A map of attribute names to values with comparison operators. | No | | ScanFilter:AttributeValueList | The values and conditions to evaluate the scan results for the filter.Type: A map of `AttributeValue` to a `Condition`. | No | | ScanFilter:​ ComparisonOperator | The criteria for evaluating the provided attributes, such as equals, greater-than, etc. The following are valid comparison operators for a scan operation. String value comparisons for greater than, equals, or less than are based on ASCII character code values. For example, `a` is greater than `A`, and `aa` is greater than `B`. For a list of code values, see [http://en.wikipedia.org/wiki/ASCII\$1ASCII\$1printable\$1characters](http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters). For Binary, DynamoDB treats each byte of the binary data as unsigned when it compares binary values, for example when evaluating query expressions. Type: String or Binary | No | |   | `EQ` : Equal. For `EQ`, `AttributeValueList` can contain only one `AttributeValue` of type String, Number, or Binary (not a set). If an item contains an `AttributeValue` of a different type than the one specified in the request, the value does not match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", "1"]}`. |   | |   | `NE` : Not Equal. For `NE`, `AttributeValueList` can contain only one `AttributeValue` of type String, Number, or Binary (not a set). If an item contains an `AttributeValue` of a different type than the one specified in the request, the value does not match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", "1"]}`. |   | |   | `LE` : Less than or equal. For `LE`, `AttributeValueList` can contain only one `AttributeValue` of type String, Number, or Binary (not a set). If an item contains an `AttributeValue` of a different type than the one specified in the request, the value does not match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. |   | |   | `LT` : Less than. For `LT`, `AttributeValueList` can contain only one `AttributeValue` of type String, Number, or Binary (not a set). If an item contains an `AttributeValue` of a different type than the one specified in the request, the value does not match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. |   | |   | `GE` : Greater than or equal. For `GE`, `AttributeValueList` can contain only one `AttributeValue` of type String, Number, or Binary (not a set). If an item contains an `AttributeValue` of a different type than the one specified in the request, the value does not match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. |   | |   | `GT` : Greater than. For `GT`, `AttributeValueList` can contain only one `AttributeValue` of type String, Number, or Binary (not a set). If an item contains an `AttributeValue` of a different type than the one specified in the request, the value does not match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. |   | |   | `NOT_NULL` : Attribute exists. |   | |   | `NULL` : Attribute does not exist. |   | |   | `CONTAINS` : checks for a subsequence, or value in a set. For `CONTAINS`, `AttributeValueList` can contain only one `AttributeValue` of type String, Number, or Binary (not a set). If the target attribute of the comparison is a String, then the operation checks for a substring match. If the target attribute of the comparison is Binary, then the operation looks for a subsequence of the target that matches the input. If the target attribute of the comparison is a set ("SS", "NS", or "BS"), then the operation checks for a member of the set (not as a substring). |   | |   | `NOT_CONTAINS` : checks for absence of a subsequence, or absence of a value in a set. For `NOT_CONTAINS`, `AttributeValueList` can contain only one `AttributeValue` of type String, Number, or Binary (not a set). If the target attribute of the comparison is a String, then the operation checks for the absence of a substring match. If the target attribute of the comparison is Binary, then the operation checks for the absence of a subsequence of the target that matches the input. If the target attribute of the comparison is a set ("SS", "NS", or "BS"), then the operation checks for the absence of a member of the set (not as a substring). |   | |   | `BEGINS_WITH` : checks for a prefix. For `BEGINS_WITH`, `AttributeValueList` can contain only one `AttributeValue` of type String or Binary (not a Number or a set). The target attribute of the comparison must be a String or Binary (not a Number or a set). |   | |   | `IN` : checks for exact matches. For `IN`, `AttributeValueList` can contain more than one `AttributeValue` of type String, Number, or Binary (not a set). The target attribute of the comparison must be of the same type and exact value to match. A String never matches a String set. |   | |   | `BETWEEN` : Greater than, or equal to, the first value and less than, or equal to, the second value. For `BETWEEN`, `AttributeValueList` must contain two `AttributeValue` elements of the same type, either String, Number, or Binary (not a set). A target attribute matches if the target value is greater than, or equal to, the first element and less than, or equal to, the second element. If an item contains an `AttributeValue` of a different type than the one specified in the request, the value does not match. For example, `{"S":"6"}` does not compare to `{"N":"6"}`. Also, `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. |   | | ExclusiveStartKey | Primary key of the item from which to continue an earlier scan. An earlier scan might provide this value if that scan operation was interrupted before scanning the entire table; either because of the result set size or the `Limit` parameter. The `LastEvaluatedKey` can be passed back in a new scan request to continue the operation from that point.Type: `HashKeyElement`, or `HashKeyElement` and `RangeKeyElement` for a composite primary key. | No | ## Responses ### Syntax ``` HTTP/1.1 200 x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 content-type: application/x-amz-json-1.0 content-length: 229 {"Count":2,"Items":[{ "AttributeName1":{"S":"AttributeValue1"}, "AttributeName2":{"S":"AttributeValue2"}, "AttributeName3":{"S":"AttributeValue3"} },{ "AttributeName1":{"S":"AttributeValue4"}, "AttributeName2":{"S":"AttributeValue5"}, "AttributeName3":{"S":"AttributeValue6"}, "AttributeName5":{"B":"dmFsdWU="} }], "LastEvaluatedKey": {"HashKeyElement":{"S":"AttributeName1"}, "RangeKeyElement":{"N":"AttributeName2"}, "ConsumedCapacityUnits":1, "ScannedCount":2} } ``` **** | Name | Description | | --- | --- | | Items | Container for the attributes meeting the operation parameters.Type: Map of attribute names to and their data types and values. | | Count | Number of items in the response. For more information, see [Counting the items in the results](Scan.md#Scan.Count). Type: Number | | ScannedCount | Number of items in the complete scan before any filters are applied. A high `ScannedCount` value with few, or no, `Count` results indicates an inefficient Scan operation. For more information, see [Counting the items in the results](Scan.md#Scan.Count).Type: Number | | LastEvaluatedKey | Primary key of the item where the scan operation stopped. Provide this value in a subsequent scan operation to continue the operation from that point.The `LastEvaluatedKey` is `null` when the entire scan result set is complete (i.e. the operation processed the “last page”). | | ConsumedCapacityUnits | The number of read capacity units consumed by the operation. This value shows the number applied toward your provisioned throughput. For more information see [DynamoDB provisioned capacity mode](provisioned-capacity-mode.md). Type: Number | ## Special errors **** | Error | Description | | --- | --- | | ResourceNotFoundException | The specified table was not found. | ## Examples For examples using the AWS SDK, see [Scanning tables in DynamoDB](Scan.md). ### Sample request ``` // This header is abbreviated. For a sample of a complete header, see DynamoDB low-level API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Scan content-type: application/x-amz-json-1.0 {"TableName":"1-hash-rangetable","ScanFilter":{}} ``` ### Sample response ``` HTTP/1.1 200 x-amzn-RequestId: 4e8a5fa9-71e7-11e0-a498-71d736f27375 content-type: application/x-amz-json-1.0 content-length: 465 {"Count":4,"Items":[{ "date":{"S":"1980"}, "fans":{"SS":["Dave","Aaron"]}, "name":{"S":"Airplane"}, "rating":{"S":"***"} },{ "date":{"S":"1999"}, "fans":{"SS":["Ziggy","Laura","Dean"]}, "name":{"S":"Matrix"}, "rating":{"S":"*****"} },{ "date":{"S":"1976"}, "fans":{"SS":["Riley"]}," name":{"S":"The Shaggy D.A."}, "rating":{"S":"**"} },{ "date":{"S":"1985"}, "fans":{"SS":["Fox","Lloyd"]}, "name":{"S":"Back To The Future"}, "rating":{"S":"****"} }], "ConsumedCapacityUnits":0.5 "ScannedCount":4} ``` ### Sample request ``` // This header is abbreviated. For a sample of a complete header, see DynamoDB low-level API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Scan content-type: application/x-amz-json-1.0 content-length: 125 {"TableName":"comp5", "ScanFilter": {"time": {"AttributeValueList":[{"N":"400"}], "ComparisonOperator":"GT"} } } ``` ### Sample response ``` HTTP/1.1 200 OK x-amzn-RequestId: PD1CQK9QCTERLTJP20VALJ60TRVV4KQNSO5AEMVJF66Q9ASUAAJG content-type: application/x-amz-json-1.0 content-length: 262 Date: Mon, 15 Aug 2011 16:52:02 GMT {"Count":2, "Items":[ {"friends":{"SS":["Dave","Ziggy","Barrie"]}, "status":{"S":"chatting"}, "time":{"N":"2000"}, "user":{"S":"Casey"}}, {"friends":{"SS":["Dave","Ziggy","Barrie"]}, "status":{"S":"chatting"}, "time":{"N":"2000"}, "user":{"S":"Fredy"} }], "ConsumedCapacityUnits":0.5 "ScannedCount":4 } ``` ### Sample request ``` // This header is abbreviated. For a sample of a complete header, see DynamoDB low-level API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Scan content-type: application/x-amz-json-1.0 {"TableName":"comp5", "Limit":2, "ScanFilter": {"time": {"AttributeValueList":[{"N":"400"}], "ComparisonOperator":"GT"} }, "ExclusiveStartKey": {"HashKeyElement":{"S":"Fredy"},"RangeKeyElement":{"N":"2000"}} } ``` ### Sample response ``` HTTP/1.1 200 OK x-amzn-RequestId: PD1CQK9QCTERLTJP20VALJ60TRVV4KQNSO5AEMVJF66Q9ASUAAJG content-type: application/x-amz-json-1.0 content-length: 232 Date: Mon, 15 Aug 2011 16:52:02 GMT {"Count":1, "Items":[ {"friends":{"SS":["Jane","James","John"]}, "status":{"S":"exercising"}, "time":{"N":"2200"}, "user":{"S":"Roger"}} ], "LastEvaluatedKey":{"HashKeyElement":{"S":"Riley"},"RangeKeyElement":{"N":"250"}}, "ConsumedCapacityUnits":0.5 "ScannedCount":2 } ``` ## Related actions + [Query](API_Query_v20111205.md) + [BatchGetItem](API_BatchGetItem_v20111205.md)