Query - Amazon DynamoDB
설명요청응답특수 오류예제관련 작업

Query

중요

이 단원에서 언급되는 API 버전 2011-12-05는 사용 중단되었으며 새 애플리케이션에 사용해서는 안 됩니다.

현재 하위 수준 API에 대한 설명서는 Amazon DynamoDB API 참조 섹션을 참조하세요.

설명

Query는 기본 키를 기준으로 하나 이상의 항목 값과 그 속성을 가져오는 작업입니다(Query는 해시 및 범위 기본 키 테이블에서만 가능합니다). 특정 HashKeyValue를 입력해야 하며, 기본 키의 RangeKeyValue에 비교 연산자를 사용하여 쿼리의 범위를 좁힐 수 있습니다. ScanIndexForward 파라미터는 범위 키를 기준으로 순방향 또는 역방향 순서로 결과를 가져오는 데 사용됩니다.

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

참고

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

ConsistentRead 파라미터를 사용하면 결과를 consistent read로 설정할 수 있습니다.

요청

구문

// 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가 유효성 검사 오류를 반환합니다. 자세한 내용은 결과 내 항목 수 계산 단원을 참조하십시오.

타입: 부울

 아니요
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#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.

 아니요

응답

구문

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

응답의 항목 수. 자세한 내용은 결과 내 항목 수 계산 단원을 참조하십시오.

형식: 숫자
LastEvaluatedKey 쿼리 작업이 중단된 항목의 기본 키(이전 결과 집합 포함). 이 값은 새로운 요청에서는 이 값을 제외하고 새 작업을 시작할 때 사용됩니다.

전체 쿼리 결과 집합이 완료되면(“마지막 페이지”까지 처리) LastEvaluatedKey는 null 값을 갖습니다.

형식: 복합 기본 키의 HashKeyElement, 또는 HashKeyElement 및 RangeKeyElement.
ConsumedCapacityUnits

작업에 사용된 읽기 용량 단위의 수. 이 값은 할당 처리량에 적용되는 수를 나타냅니다. 자세한 정보는 프로비저닝된 용량 모드 섹션을 참조하세요.

형식: 숫자

특수 오류

Error 설명
ResourceNotFoundException 지정된 테이블을 찾을 수 없습니다.

예제

AWS 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.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"}
	}
}

샘플 응답


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
}

샘플 요청

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

샘플 응답

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
}