Scan - Amazon DynamoDB
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

Scan

重要

本节介绍已经弃用的 API 版本 2011-12-05,不应用于新应用程序。

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

描述

Scan 操作对表执行完整扫描,返回一个或多个项目及其属性。提供 ScanFilter 以获得更具体的结果。

注意

如果扫描项目的总数超过 1MB 限制,则扫描停止,并将结果返回给用户并显示 LastEvaluatedKey,以在后续操作中继续扫描。结果还包括超出限制的项目数量。扫描可能导致没有符合筛选条件的表数据。

结果集具有最终一致性。

请求

语法

// 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 参数应用于仅计数扫描。

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

类型:布尔值

ScanFilter

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

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

ScanFilter:AttributeValueList

用于计算筛选器扫描结果的值和条件。

类型:AttributeValueCondition 的映射。

ScanFilter:​ ComparisonOperator

计算所提供属性的标准,例如等于、大于等于等。以下是扫描操作的有效比较运算符。

注意

大于、等于或小于的字符串值比较基于 ASCII 字符代码值。例如,a 大于 Aaa 大于 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 可以在新的扫描请求中传回,以便从此时继续操作。

类型:HashKeyElementHashKeyElement,以及复合主键的 RangeKeyElement

响应

语法

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

操作消耗的读取容量单位数。此值显示应用于预置吞吐量的数字。有关更多信息,请参阅 管理 DynamoDB 预调配容量表的吞吐量设置

类型:数字

特殊错误

错误 描述
ResourceNotFoundException 找不到指定表。

示例

有关使用 Amazon SDK 的示例,请参阅 在 DynamoDB 中使用扫描

示例请求

// 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":{}}

示例响应

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}

示例请求

// 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"} } }

示例响应

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 }

示例请求

// 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"}} }

示例响应

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 }