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

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

Scan

重要

This section refers to API version 2011-12-05, which is deprecated and should not be used for new applications.

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

Description

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

注意

如果扫描的项目总数超过 1MB 的限制,则会使用 LastEvaluatedKey 将扫描停止并返回给用户,以在后续操作中继续执行扫描。结果还包括超过限制的项目数。扫描不会导致任何表数据符合筛选条件。

结果集具有最终一致性。

Requests

Syntax

// 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 会返回验证错误。有关更多信息,请参阅对结果中的项目进行计数

类型: Boolean

ScanFilter

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

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

ScanFilter:AttributeValueList

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

类型: 到 AttributeValue 的映射。Condition

ScanFilter:​ ComparisonOperator

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

注意

大于、等于或小于的字符串值比较基于 ASCII 字符代码值。例如,a 大于 Aaa 大于 B。 有关代码值的列表,请参阅 http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters。

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

类型: 字符串或二进制

 

EQ:等于。

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

 
 

NE:不等于.

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

 
 

LE:小于或等于。

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

 
 

LT:小于。

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

 
 

GE:大于或等于。

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

 
 

GT:大于。

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

 
 

NOT_NULL:属性存在。

 
 

NULL:属性不存在。

 
 

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

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

 
 

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

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

 
 

BEGINS_WITH:检查前缀。

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

 
 

IN:检查精确匹配。

对于 INAttributeValueList 可以包含多个类型为 String、Number 或 Binary(非集合)的 AttributeValue。比较的目标属性必须具有相同的类型和精确值才能匹配。字符串绝不会与字符串集匹配。

 
 

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

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

 
ExclusiveStartKey

从其继续较早扫描的项目的主键。如果扫描操作在扫描整个表之前中断,则早期扫描可能会提供此值;这可能是因为结果集大小或 Limit 参数导致的。可以在新的扫描请求中传递回 LastEvaluatedKey 以从那时起继续操作。

类型: HashKeyElement,或对于复合主键为 HashKeyElementRangeKeyElement

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} }
名称 描述
Items

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

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

Count

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

类型: 数字

ScannedCount

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

类型: 数字

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

当整个扫描结果集完成时,LastEvaluatedKeynull(即操作处理“上一页”)。

ConsumedCapacityUnits

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

类型: 数字

特殊错误

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

Examples

有关使用 AWS 开发工具包的示例,请参阅在 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 }