Amazon DynamoDB
開発者ガイド (API バージョン 2012-08-10)

スキャン

重要

このセクションは、廃止された API バージョン 2011-12-05 についての記述で、新しいアプリケーションで使用することはできません。

現在の低レベル API のドキュメントについては、「Amazon DynamoDB API Reference」を参照してください。

説明

Scan オペレーションは、テーブルの完全スキャンを実行して、1 つ以上の項目とその属性を返します。ScanFilter を指定して、結果を絞り込みます。

注記

スキャンされた項目の合計数が 1 MB の制限を超えた場合、スキャンは停止し、後続のオペレーションでスキャンを継続できるように、LastEvaluatedKey とともに結果がユーザーに返されます。また、結果には、制限を上回る項目の数も記載されます。スキャンを実行しても、フィルタ基準に一致するテーブルデータがない場合もあります。

結果セットは結果整合性があります。

リクエスト

構文

// 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 は、この上限に到達する前にスキャンしたデータセットのサイズが 1 MB を超えた場合、スキャンを停止し、その上限までの一致する値と、スキャンを継続するために後続のオペレーションで利用できる LastEvaluatedKey を返します。

型: 数値

いいえ
Count

true に設定した場合、DynamoDB は、割り当てられたフィルタに対して一致する項目がない場合でも、Scan オペレーションの項目の合計数を返します。Limit パラメータはカウントのみのスキャンに適用できます。

AttributesToGet のリストを指定している場合は、Counttrue に設定しないでください。設定すると、DynamoDB は検証エラーを返します。詳細については、「結果での項目のカウント」を参照してください。

タイプ: ブール値

いいえ
ScanFilter

スキャン結果を評価し、目的の値のみを返します。複数の条件は、"AND" オペレーションで処理されます。このため、すべての条件に一致するものが結果に追加されます。

型: 属性名と値のマップ、比較演算子付き

いいえ
ScanFilter:AttributeValueList

フィルタするためにスキャン結果を評価するときの値と条件。

型: AttributeValueCondition のマップ

いいえ
ScanFilter:​ ComparisonOperator

等しい、より大きいなど、指定した属性を評価するための基準。スキャンオペレーションで有効な比較演算子を次に示します。

注記

より大きい、等しい、より小さいの文字列値比較は、ASCII 文字コード値に基づいて行われます。たとえば、aA より大きく、aaB より大きい文字列です。コードの値のリストについては、「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"]} も等しくありません。

 
 

NE : 等しくない。

NE の場合、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"]} と同等ではありません。

 
 

NOT_NULL : 属性がある。

 
 

NULL : 属性がない。

 
 

CONTAINS : サブシーケンスまたはセットの値のチェック。

CONTAINS の場合、AttributeValueList に指定できるのは、文字列型、数値型、またはバイナリ型の 1 つの AttributeValue だけです(セット型は指定できません)。比較対象の属性が文字列型の場合、部分文字列の一致がチェックされます。比較対象の属性がバイナリ型の場合、入力に一致する対象の属性のサブシーケンスが検索されます。比較対象の属性がセット("SS"、"NS"、または "BS")の場合、(部分文字列としてではなく)セットのメンバーがチェックされます。

 
 

NOT_CONTAINS : サブシーケンスがない、またはセットの値がないことのチェック。

NOT_CONTAINS の場合、AttributeValueList に指定できるのは、文字列型、数値型、またはバイナリ型の 1 つの AttributeValue だけです(セット型は指定できません)。比較対象の属性が文字列型の場合、部分文字列の一致がないことがチェックされます。比較対象の属性がバイナリ型の場合、入力に一致する対象の属性のサブシーケンスがないことがチェックされます。比較対象の属性がセット("SS"、"NS"、または "BS")の場合、(部分文字列としてではなく)セットのメンバーがないことがチェックされます。

 
 

BEGINS_WITH : プレフィックスのチェック。

BEGINS_WITH の場合、AttributeValueList に指定できるのは、文字列型またはバイナリ型の 1 つの AttributeValue だけです(数値型またはセット型は指定できません)。比較対象の属性は、(数値型またはセット型ではなく)文字列型またはバイナリ型である必要があります。

 
 

IN : 完全一致のチェック。

IN の場合、AttributeValueList に指定できるのは、文字列型、数値型、またはバイナリ型の複数の AttributeValue です(セット型は指定できません)。比較対象の属性は、同じ型と正確な値に一致する必要があります。文字列は文字列セットには一致しません。

 
 

BETWEEN : 最初の値以上、かつ 2 番目の値以下。

BETWEEN の場合、AttributeValueList には、同じ型(文字列、数値、またはバイナリ)の AttributeValue 要素を 2 つ指定する必要があります(セット型は指定できません)。対象の属性が一致するのは、対象の値が最初の要素以上かつ 2 番目の要素以下の場合です。リクエストで指定した型とは異なる型の AttributeValue が項目に含まれている場合、値は一致しません。たとえば、{"S":"6"}{"N":"6"} と同等ではありません。また、{"N":"6"}{"NS":["6", "2", "1"]} と同等ではありません。

 
ExclusiveStartKey

以前のスキャンを継続するときに開始する項目のプライマリキー。結果セットのサイズまたは Limit パラメータが原因で、以前のスキャンオペレーションがテーブル全体をスキャンする前に中断された場合、この値が返されている可能性があります。新しいスキャンリクエストで LastEvaluatedKey を渡して、その時点からオペレーションを継続できます。

型: HashKeyElement、または複合プライマリキーの場合 HashKeyElementRangeKeyElement

いいえ

レスポンス

構文

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 結果が小さいまたはない場合は、Scan オペレーションが不十分であることを示しています。詳細については、「結果での項目のカウント」を参照してください。

型: 数値

LastEvaluatedKey スキャンオペレーションが停止した項目のプライマリキー。後続のスキャンオペレーションでこの値を指定して、その時点からオペレーションを継続できます。

スキャン結果セット全体が完了すると(つまり、オペレーションによって "最後のページ" が処理されると)、LastEvaluatedKeynull になります。

ConsumedCapacityUnits

オペレーションによって消費された読み込みキャパシティーユニットの数。この値は、プロビジョニングされたスループットに対して適用された数を示します。詳細については、「プロビジョニングされたテーブルでのスループット設定の管理」を参照してください。

型: 数値

特殊なエラー

エラー 説明
ResourceNotFoundException 指定されたテーブルが見つかりませんでした。

AWS SDK を使用した例については、「スキャンの使用」を参照してください。

リクエスト例

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