# 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` オペレーションオペレーションは、1 つ以上の項目の値とその属性をプライマリキーごとに取得します (`Query` はハッシュと範囲のプライマリキーテーブルでのみ使用できます)。特定の `HashKeyValue` を指定する必要があります。プライマリキーの `RangeKeyValue` で比較オペレーションを使用してクエリの範囲を絞り込むことができます。範囲キーごとに正順または逆順で結果を取得するには、`ScanIndexForward` パラメータを使用します。

結果を返さないクエリは、読み込みのタイプに応じて最小読み込み容量ユニットを消費します。

**注記**  
クエリパラメータを満たす項目の合計数が 1 MB の制限を超えるとクエリが停止し、結果が後続のオペレーションでクエリを続行するための `LastEvaluatedKey` とともにユーザーに返されます。スキャン操作とは異なり、クエリ操作では、空の結果セット*および* `LastEvaluatedKey` が返されません。結果が 1 MB を超える場合、または `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` を返します。また、この制限に達する前に結果セットのサイズが 1 MB を超えた場合、DynamoDB はクエリを停止し、一致する値とともに、後続のオペレーションでクエリをクリックするために適用する `LastEvaluatedKey` を返します。型: 数値 | いいえ | 
| ConsistentRead  | `true` に設定されている場合、整合性のある読み込みが発行されます。それ以外の場合、結果整合性が使用されます。型: ブール値 | いいえ | 
| Count  | `true` に設定されている場合、DynamoDB は、一致する項目とその属性のリストではなく、クエリパラメータに一致する項目の合計数を返します。`Limit` パラメータをカウントのみのクエリに適用できます。 `AttributesToGet` のリストを提供する場合、`Count` を `true` に設定しないでください。そうでないと、DynamoDB は検証エラーを返します。詳細については、「[結果での項目のカウント](Query.Other.md#Query.Count)」を参照してください。型: ブール値 | いいえ | 
| HashKeyValue  | 複合プライマリキーのハッシュコンポーネントの属性値。型: 文字列、数値、またはバイナリ | はい | 
| RangeKeyCondition  | クエリに使用する属性値および比較演算子のコンテナ。クエリリクエストには `RangeKeyCondition` は必要ありません。`HashKeyValue` だけを指定した場合、DynamoDB は、指定されたハッシュキー要素値を持つすべての項目を返します。型: マップ | いいえ | 
| RangeKeyCondition:​ AttributeValueList | クエリパラメータについて評価する属性値。`BETWEEN` 比較を指定した場合を除き、`AttributeValueList` には属性値が 1 つ含まれます。`BETWEEN` 比較では、`AttributeValueList` には、2 つの属性値が含まれます。型: `ComparisonOperator` への `AttributeValue` のマップ。 | いいえ | 
| 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` は、文字列、数値、またはバイナリのうち、1 つの `AttributeValue` のみを含むことができます (セットではありません)。リクエストで指定されているもの以外の型の `AttributeValue` が項目に含まれる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と等しくありません。 |   | 
|   | `LE`: より小さい、または等しい。 `LE` の場合、`AttributeValueList` は、文字列、数値、またはバイナリのうち、1 つの `AttributeValue` のみを含むことができます (セットではありません)。リクエストで指定されているもの以外の型の `AttributeValue` が項目に含まれる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。 |   | 
|   | `LT`: より小さい。 `LT` の場合、`AttributeValueList` は、文字列、数値、またはバイナリのうち、1 つの `AttributeValue` のみを含むことができます (セットではありません)。リクエストで指定されているもの以外の型の `AttributeValue` が項目に含まれる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。 |   | 
|   | `GE`: より大きい、または等しい。 `GE` の場合、`AttributeValueList` は、文字列、数値、またはバイナリのうち、1 つの `AttributeValue` のみを含むことができます (セットではありません)。リクエストで指定されているもの以外の型の `AttributeValue` が項目に含まれる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。 |   | 
|   | `GT`: より大きい。 `GT` の場合、`AttributeValueList` は、文字列、数値、またはバイナリのうち、1 つの `AttributeValue` のみを含むことができます (セットではありません)。リクエストで指定されているもの以外の型の `AttributeValue` が項目に含まれる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。 |   | 
|   | `BEGINS_WITH`: プレフィックスを確認します。 `BEGINS_WITH` の場合、`AttributeValueList` は、文字列またはバイナリの 1 つの `AttributeValue` のみを含むことができます (数値やセットではありません)。比較のターゲット属性は、(数値またはセットではなく) 文字列またはバイナリである必要があります。 |   | 
|   | `BETWEEN`: 最初の値より大きいまたは等しい、および 2 番目の値より小さいまたは等しい。 `BETWEEN` の場合、`AttributeValueList` は、文字列、数値、またはバイナリのいずれかの同じ型の 2 つの `AttributeValue` 要素を含む必要があります (セットではありません)。ターゲット属性は、ターゲット値が最初の要素より大きいか等しく、2番目の要素より小さいか等しい場合に一致します。リクエストで指定されているもの以外の型の `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>


****  

|  エラー  |  説明  | 
| --- | --- | 
| 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>
+  [Scan](API_Scan_v20111205.md)