# 查询
<a name="API_Query_v20111205"></a>

**重要**  
***本节介绍已经弃用的 API 版本 2011-12-05，不应用于新应用程序。***  
 **有关当前低级别 API 的文档，请参阅 [Amazon DynamoDB API 参考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**

## 描述
<a name="API_Query_Description"></a>

`Query` 操作通过主键获取一个或多个项目的值及其属性（`Query` 仅对 hash-and-range 主键表可用）。您必须提供一个特定 `HashKeyValue`，并且可以对主键的 `RangeKeyValue` 使用比较运算符缩小查询范围。使用 `ScanIndexForward` 参数按 range 键获取正向或反向顺序结果。

不返回结果的查询会根据读取类型消耗最小读取容量单位。

**注意**  
如果满足查询参数的项目总数超过 1MB 限制，则查询将停止，结果将返回给用户，并显示 `LastEvaluatedKey`，以在后续操作中继续查询。与扫描操作不同，查询操作永远不会返回空结果集*和* `LastEvaluatedKey`。仅当结果超过 1MB 或者使用 `Limit` 参数时提供 `LastEvaluatedKey`。  
可以使用 `ConsistentRead` 参数为一致性读取设置结果。

## 请求
<a name="API_Query_RequestParameters"></a>

### 语法
<a name="API_Query_RequestParameters.syntax"></a>

```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低级 API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.Query  
content-type: application/x-amz-json-1.0

{"TableName":"Table1",
	"Limit":2,
	"ConsistentRead":true,
	"HashKeyValue":{"S":"AttributeValue1":},
	"RangeKeyCondition": {"AttributeValueList":[{"N":"AttributeValue2"}],"ComparisonOperator":"GT"}
	"ScanIndexForward":true,
	"ExclusiveStartKey":{
		"HashKeyElement":{"S":"AttributeName1"},
		"RangeKeyElement":{"N":"AttributeName2"}
	},
    "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]},
}
```


****  

|  名称  |  描述  |  必填 | 
| --- | --- | --- | 
|  TableName  |  包含请求项目的表的名称。 类型：字符串  |  是  | 
| AttributesToGet  | 属性名称的数组。如果未指定属性名称，则返回所有属性。如果找不到某些属性，则不会出现在结果中。类型：数组 | 否 | 
| Limit  | 要返回的最大项目数（不一定是匹配项目数）。如果 DynamoDB 在查询表时处理的项目数达到限制，将停止查询并返回到此时的匹配值和 `LastEvaluatedKey`，在后续操作中应用以继续查询。此外，如果在 DynamoDB 达到此限制之前结果集大小超过 1MB，将停止查询并返回匹配值和 `LastEvaluatedKey`，在后续操作中应用以继续查询。类型：数字 | 否 | 
| ConsistentRead  | 如果设置为 `true`，则发出一致性读取，否则将使用最终一致性。类型：布尔值 | 否 | 
| Count  | 如果设置为 `true`，DynamoDB 将返回匹配查询参数的项目总数，而不是匹配项目及其属性的列表。可以对仅计数查询应用 `Limit` 参数。 提供 `AttributesToGet` 列表时不要将 `Count` 设置为 `true`；否则 DynamoDB 将返回验证错误。有关更多信息，请参阅 [对结果中的项目进行计数](Query.Other.md#Query.Count)。类型：布尔值 | 否 | 
| HashKeyValue  | 复合主键的 hash 部分的属性值。类型：字符串、数字或二进制 | 是 | 
| RangeKeyCondition  | 用于查询的属性值和比较运算符的容器。查询请求不需要 `RangeKeyCondition`。如果仅提供 `HashKeyValue`，DynamoDB 将返回具有指定 hash 键元素值的所有项目。类型：映射 | 否 | 
| RangeKeyCondition:​ AttributeValueList | 为查询参数计算的属性值。`AttributeValueList` 包含一个属性值，除非指定 `BETWEEN` 比较。对于 `BETWEEN` 比较，`AttributeValueList` 包含两个属性值。类型：`AttributeValue` 到 `ComparisonOperator` 的映射。 | 否 | 
| RangeKeyCondition:​ ComparisonOperator |  计算所提供属性的标准，例如等于、大于等于等。以下是查询操作的有效比较运算符。  大于、等于或小于的字符串值比较基于 ASCII 字符代码值。例如，`a` 大于 `A`，`aa` 大于 `B`。有关代码值列表，请参见 [http://en.wikipedia.org/wiki/ASCII\$1ASCII\$1printable\$1characters](http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters)。 对于二进制，DynamoDB 在比较二进制值时将二进制数据的每个字节视为无符号值，例如计算查询表达式时。  类型：字符串或二进制  | 否 | 
|   | `EQ`：等于。 对于 `EQ`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 |   | 
|   | `LE`：小于或等于。 对于 `LE`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 |   | 
|   | `LT`：小于。 对于 `LT`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 |   | 
|   | `GE`：大于或等于。 对于 `GE`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 |   | 
|   | `GT`：大于。 对于 `GT`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 |   | 
|   | `BEGINS_WITH`：检查前缀。 对于 `BEGINS_WITH`，`AttributeValueList` 只能包含一个字符串或二进制类型的 `AttributeValue`（不是数字或集合）。比较的目标属性必须是字符串或二进制（不是数字或集合）。 |   | 
|   | `BETWEEN`：大于或等于第一个值，小于或等于第二个值。 对于 `BETWEEN`，`AttributeValueList` 必须包含两个相同类型的 `AttributeValue` 元素，可以是字符串，数字或二进制（不是集合）。如果目标值大于等于第一个元素，小于等于第二个元素，则目标属性匹配。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 |   | 
| ScanIndexForward | 指定索引的升序或降序遍历。DynamoDB 返回的结果反映由 range 键确定的请求顺序：如果数据类型为数字，则按数字顺序返回结果；否则，遍历基于 ASCII 字符代码值。类型：布尔值默认值为 `true`（升序）。 | 否 | 
| ExclusiveStartKey | 继续早期查询的项目的主键。如果早期查询操作在完成查询之前因为结果集大小或 `Limit` 参数中断，该查询可能会提供此值作为 `LastEvaluatedKey`。`LastEvaluatedKey` 可以在新的查询请求中传回，从此处开始继续操作。类型：`HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement`（对于复合主键）。 | 否 | 

## 响应
<a name="API_Query_ResponseElements"></a>

### 语法
<a name="API_Query_ResponseElements.syntax"></a>

```
HTTP/1.1 200 
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0
content-length: 308

{"Count":2,"Items":[{
    "AttributeName1":{"S":"AttributeValue1"},
    "AttributeName2":{"N":"AttributeValue2"},
    "AttributeName3":{"S":"AttributeValue3"}
    },{
    "AttributeName1":{"S":"AttributeValue3"},
    "AttributeName2":{"N":"AttributeValue4"},
    "AttributeName3":{"S":"AttributeValue3"},
    "AttributeName5":{"B":"dmFsdWU="}
}],
    "LastEvaluatedKey":{"HashKeyElement":{"AttributeValue3":"S"},
                        "RangeKeyElement":{"AttributeValue4":"N"}
     },
     "ConsumedCapacityUnits":1
}
```


****  

|  名称  |  描述  | 
| --- | --- | 
| Items  | 符合查询参数的项目属性。类型：属性名称映射及其数据类型和值。 | 
| Count  |  响应中的项目数。有关更多信息，请参阅 [对结果中的项目进行计数](Query.Other.md#Query.Count)。 类型：数字  | 
| LastEvaluatedKey | 查询操作停止的项目主键，包括以前的结果集。使用此值可以在新请求中开始不包含此值的新操作。整个查询结果集完成后（即操作处理“最后一页”），`LastEvaluatedKey` 为 `null`。类型：`HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement`（对于复合主键）。 | 
| ConsumedCapacityUnits | 操作消耗的读取容量单位数。此值显示应用于预置吞吐量的数字。有关更多信息，请参阅[DynamoDB 预置容量模式](provisioned-capacity-mode.md)。 类型：数字 | 

## 特殊错误
<a name="API_Query_SpecialErrors"></a>


****  

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

## 示例
<a name="API_Query_Examples"></a>

 有关使用 AWS SDK 的示例，请参阅 [在 DynamoDB 中查询表](Query.md)。

### 示例请求
<a name="API_Query_Examples_Request"></a>

```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低级 API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.Query  
content-type: application/x-amz-json-1.0

{"TableName":"1-hash-rangetable",
	"Limit":2,
	"HashKeyValue":{"S":"John"},
	"ScanIndexForward":false,
	"ExclusiveStartKey":{
		"HashKeyElement":{"S":"John"},
		"RangeKeyElement":{"S":"The Matrix"}
	}
}
```

### 示例响应
<a name="API_Query_Examples_Response"></a>

```
HTTP/1.1 200 
x-amzn-RequestId: 3647e778-71eb-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0
content-length: 308

{"Count":2,"Items":[{
	"fans":{"SS":["Jody","Jake"]},
	"name":{"S":"John"},
	"rating":{"S":"***"},
	"title":{"S":"The End"}
	},{
	"fans":{"SS":["Jody","Jake"]},
	"name":{"S":"John"},
	"rating":{"S":"***"},
	"title":{"S":"The Beatles"}
	}],
	"LastEvaluatedKey":{"HashKeyElement":{"S":"John"},"RangeKeyElement":{"S":"The Beatles"}},
"ConsumedCapacityUnits":1
}
```

### 示例请求
<a name="API_Query_Examples_Request2"></a>

```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低级 API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.Query 
content-type: application/x-amz-json-1.0
 
{"TableName":"1-hash-rangetable",
	"Limit":2,
	"HashKeyValue":{"S":"Airplane"},
	"RangeKeyCondition":{"AttributeValueList":[{"N":"1980"}],"ComparisonOperator":"EQ"},
	"ScanIndexForward":false}
```

### 示例响应
<a name="API_Query_Examples_Response2"></a>

```
HTTP/1.1 200 
x-amzn-RequestId: 8b9ee1ad-774c-11e0-9172-d954e38f553a
content-type: application/x-amz-json-1.0
content-length: 119 
 
{"Count":1,"Items":[{
	"fans":{"SS":["Dave","Aaron"]},
	"name":{"S":"Airplane"},
	"rating":{"S":"***"},
	"year":{"N":"1980"}
	}],
"ConsumedCapacityUnits":1
}
```

## 相关操作
<a name="API_Query_Related_Actions"></a>
+  [扫描](API_Scan_v20111205.md)