# Query
<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`는 해시 및 범위 기본 키 테이블에서만 가능합니다). 특정 `HashKeyValue`를 입력해야 하며, 기본 키의 `RangeKeyValue`에 비교 연산자를 사용하여 쿼리의 범위를 좁힐 수 있습니다. `ScanIndexForward` 파라미터는 범위 키를 기준으로 순방향 또는 역방향 순서로 결과를 가져오는 데 사용됩니다.

결과를 반환하지 않는 쿼리는 읽기 형식에 따라 최소 읽기 용량 단위를 사용합니다.

**참고**  
쿼리 파라미터를 만족하는 전체 항목 수의 크기가 1MB 제한을 초과하면 쿼리가 중단되고 `LastEvaluatedKey`와 함께 사용자에게 결과가 반환된 후 이어지는 작업에서 쿼리가 계속 됩니다. 스캔 작업과 달리 쿼리 작업은 절대로 빈 결과 집합 *및* `LastEvaluatedKey`를 반환하지 않습니다. `LastEvaluatedKey`는 결과가 1MB를 초과하거나, 혹은 `Limit` 파라미터를 사용한 경우에만 반환됩니다.  
`ConsistentRead` 파라미터를 사용하면 결과를 consistent read로 설정할 수 있습니다.

## 요청
<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`로 설정하면 consistent read가 발생하고, 그 밖의 경우에는 eventually consistent가 사용됩니다.타입: 부울 | 아니요 | 
| Count  | `true`로 설정할 경우DynamoDB 가 일치하는 항목 및 해당 속성의 목록이 아닌 쿼리 파라미터와 일치하는 전체 항목 수를 반환합니다. `Limit` 파라미터는 항목 수 계산 쿼리에만 적용됩니다. `AttributesToGet` 목록을 제공하는 동안 `Count`를 `true`로 설정하지 마세요. 그렇지 않으면 DynamoDB가 유효성 검사 오류를 반환합니다. 자세한 내용은 [결과 내 항목 수 계산](Query.Other.md#Query.Count) 단원을 참조하십시오.타입: 부울 | 아니요 | 
| HashKeyValue  | 복합 기본 키에서 해시 구성 요소의 속성 값형식: 문자열, 숫자 또는 이진수 | 예 | 
| RangeKeyCondition  | 쿼리에 사용되는 속성 값과 비교 연산자가 저장되는 컨테이너. 쿼리를 요청할 때는 `RangeKeyCondition`이 필요하지 않습니다. `HashKeyValue`만 입력하면 DynamoDB가 지정한 해시 키 요소 값을 갖는 항목을 모두 반환합니다.유형: 맵 | 아니요 | 
| RangeKeyCondition:​ AttributeValueList | 쿼리 파라미터를 위해 평가할 속성 값. `BETWEEN` 비교를 지정하지 않으면 `AttributeValueList`에 속성 값이 하나 저장됩니다. 그리고, `BETWEEN` 비교를 지정하면 `AttributeValueList`에 속성 값이 2개 저장됩니다.형식: `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`의 경우, 문자열, 숫자 또는 이진수(집합 제외) 중에서 동일한 형식으로 2개의 `AttributeValueList` 요소가 `AttributeValue`에 저장되어야 합니다. 대상 값이 첫 번째 요소보다 크거나 같을 때, 그리고 두 번째 요소보다 작거나 같을 때 대상 속성이 일치합니다. 요청에서 지정한 형식과 다른 형식의 `AttributeValue` 값이 항목에 저장되면 값은 일치하지 않습니다. 예를 들어 `{"S":"6"}`은 `{"N":"6"}`과 비교할 수 없습니다. 또한 `{"N":"6"}`은 `{"NS":["6", "2", "1"]}`과 비교할 수 없습니다. |   | 
| ScanIndexForward | 인덱스의 오름차순 또는 내림차순을 지정합니다. DynamoDB는 범위 키에서 지정한 요청 순서를 반영하여 결과를 반환합니다. 데이터 형식이 숫자라면 결과는 숫자의 순서대로 반환됩니다. 그렇지 않으면 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>


****  

|  Error  |  설명  | 
| --- | --- | 
| 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)