Amazon DynamoDB
开发人员指南 (API Version 2012-08-10)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

扫描

重要

本节引用 API 版本 2011-12-05,此版本已被弃用且不应该用于新应用程序。

有关当前低级 API 的文档,请参阅 Amazon DynamoDB API Reference

说明

Scan 操作通过对表执行完全扫描返回一个或多个项目及其属性。提供 ScanFilter,用于获取更特定的结果。

注意

如果扫描的项目总数超过 1MB 的限制,扫描将停止,并且会向用户返回结果和 LastEvaluatedKey,以便在后续操作中继续此扫描。结果还包含超过该限制的项目数。扫描可能不会产生满足筛选条件的表数据。

结果集是最终一致的。

请求

语法

Copy
// This header is abbreviated. // For a sample of a complete header, see DynamoDB 低级 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"]}, }

名称 描述 必需
TableName

包含所请求项目的表的名称。

类型:字符串

AttributesToGet

属性名称数组。如果未指定属性名称,则将返回所有属性。如果未找到某些属性,则不会在结果中显示这些属性。

类型:数组

Limit

要评估的最大项目数 (不一定是匹配项目数)。如果 DynamoDB 在处理结果时处理的项目数达到上限,则它将停止处理并返回达到上限时已找到的所有匹配值,以及为了继续检索项目而要在后续操作中应用的 LastEvaluatedKey。另外,如果在 DynamoDB 达到此限制前已扫描的数据集大小超过 1MB,则它将停止扫描,并返回达到此限制时已找到的所有匹配值,以及为了继续扫描而要在后续操作中应用的 LastEvaluatedKey

类型:数字

Count

如果设置为 true,则 DynamoDB 返回要进行扫描操作的项目总数,即使该操作对于分配的筛选条件没有匹配项目。可以对“仅计数”扫描应用 Limit 参数。

提供 Count 列表时请勿将 true 设置为 AttributesToGet;否则,DynamoDB 会返回验证错误。有关更多信息,请参阅 对结果中的项目进行计数

类型:布尔值

ScanFilter

评估扫描结果并仅返回所需的值。多个条件被视为“AND”操作:必须满足所有条件才能包含在结果中。

类型:属性名称到带有比较运算符的值的映射。

ScanFilter:AttributeValueList

用于评估筛选条件的扫描结果的值和条件。

类型:AttributeValueCondition 的映射。

ScanFilter:​ ComparisonOperator

用于评估提供的属性的标准,如“等于”、“大于”等。以下是扫描操作的有效比较运算符。

注意

大于、等于或小于的字符串值比较基于 ASCII 字符代码值。例如,a 大于 A,而 aa 大于 B。若要获取代码值的列表,请访问 http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters

对于二进制,DynamoDB 在比较二进制值 (如,计算查询表达式) 时会将二进制数据的每个字节视为无符号数据。

类型:字符串或二进制

 

EQ:等于。

对于 EQAttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的 AttributeValue。如果项目包含的 AttributeValue 的类型不同于请求中指定的类型,则值不匹配。例如,{"S":"6"} 不等于 {"N":"6"}。此外,{"N":"6"} 不等于 {"NS":["6", "2", "1"]}

 
 

NE:不等于。

对于 NEAttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的 AttributeValue。如果项目包含的 AttributeValue 的类型不同于请求中指定的类型,则值不匹配。例如,{"S":"6"} 不等于 {"N":"6"}。此外,{"N":"6"} 不等于 {"NS":["6", "2", "1"]}

 
 

LE:小于或等于。

对于 LEAttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的 AttributeValue。如果项目包含的 AttributeValue 的类型不同于请求中指定的类型,则值不匹配。例如,{"S":"6"} 不等于 {"N":"6"}。此外,{"N":"6"} 不能与 {"NS":["6", "2", "1"]} 进行比较。

 
 

LT:小于。

对于 LTAttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的 AttributeValue。如果项目包含的 AttributeValue 的类型不同于请求中指定的类型,则值不匹配。例如,{"S":"6"} 不等于 {"N":"6"}。此外,{"N":"6"} 不能与 {"NS":["6", "2", "1"]} 进行比较。

 
 

GE:大于或等于。

对于 GEAttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的 AttributeValue。如果项目包含的 AttributeValue 的类型不同于请求中指定的类型,则值不匹配。例如,{"S":"6"} 不等于 {"N":"6"}。此外,{"N":"6"} 不能与 {"NS":["6", "2", "1"]} 进行比较。

 
 

GT : 大于。

对于 GTAttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的 AttributeValue。如果项目包含的 AttributeValue 的类型不同于请求中指定的类型,则值不匹配。例如,{"S":"6"} 不等于 {"N":"6"}。此外,{"N":"6"} 不能与 {"NS":["6", "2", "1"]} 进行比较。

 
 

NOT_NULL:属性存在。

 
 

NULL:属性不存在。

 
 

CONTAINS:检查集中的子序列或值。

对于 CONTAINSAttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的 AttributeValue。如果比较的目标属性是字符串,则此操作将查找匹配的子字符串。如果比较的目标属性是二进制,则此操作将在目标中查找匹配输入的子序列。如果比较的目标属性是集合 (“SS”、“NS”或“BS”),则此操作将查找集合的成员 (不作为子字符串)。

 
 

NOT_CONTAINS:检查集中是否缺少某个子序列或缺少某个值。

对于 NOT_CONTAINSAttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的 AttributeValue。如果比较的目标属性是字符串,则此操作将检查某个子字符串的匹配项是否不存在。如果比较的目标属性是二进制,则此操作将检查目标中是否不存在与输入匹配的子序列。如果比较的目标属性是集合 (“SS”、“NS”或“BS”),则此操作将检查集合的成员是否不存在 (不作为子字符串)。

 
 

BEGINS_WITH:检查前缀。

对于 BEGINS_WITHAttributeValueList 只能包含一个类型为字符串或二进制 (不是数字或集) 的 AttributeValue。比较的目标属性必须是字符串或二进制 (非数字或集合)。

 
 

IN:检查完全匹配项。

对于 INAttributeValueList 可以包含多个类型为字符串、数字或二进制 (非集) 的 AttributeValue。比较的目标属性必须属于同一类型,并且具有完全相同的值才能匹配。字符串从不与字符串集匹配。

 
 

BETWEEN:大于或等于第一个值并且小于或等于第二个值。

对于 BETWEENAttributeValueList 必须包含两个相同类型 (字符串、数字或二进制 (非集) ) 的 AttributeValue 元素。如果目标值大于或等于第一个元素并且小于或等于第二个元素,则目标属性匹配。如果项目包含的 AttributeValue 的类型不同于请求中指定的类型,则值不匹配。例如,{"S":"6"} 不能与 {"N":"6"} 进行比较。此外,{"N":"6"} 不能与 {"NS":["6", "2", "1"]} 进行比较。

 
ExclusiveStartKey

从其开始继续以前的扫描的项目主键。如果以前的扫描操作在扫描整个表之前由于结果集大小或 Limit 参数而中断,则以前的扫描可能会提供此值。可以在新的扫描请求中重新传入 LastEvaluatedKey 以从该点继续操作。

类型:HashKeyElement 或复合主键的 HashKeyElementRangeKeyElement

响应

语法

Copy
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} }

名称 描述
Items

满足操作参数的属性的容器。

类型:属性名称到其数据类型和值的映射。

Count

响应中的项目数。有关更多信息,请参阅 对结果中的项目进行计数

类型:数字

ScannedCount

在应用任何筛选条件之前完成的扫描中的项目数。 ScannedCount 值很高但 Count 结果很少或为零,指示扫描操作效率低下。有关更多信息,请参阅 对结果中的项目进行计数

类型:数字

LastEvaluatedKey 扫描操作停止于的项目的主键。在后续扫描操作中提供此值可从该点继续操作。

如果整个扫描结果集是完整的 (即该操作已处理“最后一页”),则 LastEvaluatedKeynull

ConsumedCapacityUnits

操作占用的读取容量单位数。此值显示根据预置吞吐量应用的数量。有关更多信息,请参阅 读取和写入的吞吐量设置

类型:数字

特殊错误

错误 说明
ResourceNotFoundException 找不到指定的表。

示例

有关使用 AWS 开发工具包的示例,请参阅 使用扫描

示例请求

Copy
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低级 API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Scan content-type: application/x-amz-json-1.0 {"TableName":"1-hash-rangetable","ScanFilter":{}}

示例响应

Copy
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}

示例请求

Copy
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低级 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"} } }

示例响应

Copy
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 }

示例请求

Copy
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低级 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"}} }

示例响应

Copy
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 }