Query
リクエストマッピングドキュメントを使用すると、AWS の AppSync DynamoDB リゾルバーから DynamoDB への Query
リクエストで、以下のように指定できます。
-
キー式
-
使用するインデックス
-
任意の追加フィルタ
-
返す項目の数
-
整合性のある読み込みを使用するかどうか
-
クエリの方向 (前方または後方)
-
ページ分割トークン
Query
マッピングドキュメントの構造は次のとおりです。
{
"version" : "2017-02-28",
"operation" : "Query",
"query" : {
"expression" : "some expression",
"expressionNames" : {
"#foo" : "foo"
},
"expressionValues" : {
":bar" : ... typed value
}
},
"index" : "fooIndex",
"nextToken" : "a pagination token",
"limit" : 10,
"scanIndexForward" : true,
"consistentRead" : false,
"select" : "ALL_ATTRIBUTES" | "ALL_PROJECTED_ATTRIBUTES" | "SPECIFIC_ATTRIBUTES",
"filter" : {
...
},
"projection" : {
...
}
}
各フィールドの定義は以下のようになります。
Query フィールド
-
version
-
テンプレート定義バージョン
2017-02-28
と2018-05-29
は現在サポートされています。この値は必須です。 -
operation
-
実行する DynamoDB の処理。
Query
DynamoDB の処理を実行するには、これをQuery
に設定する必要があります。この値は必須です。 -
query
-
query
セクションには、DynamoDB から取得する項目を指示するキー条件式を指定することができます。キー条件式の記述方法の詳細については、DynamoDB KeyConditions のドキュメントを参照してください。このセクションの指定は必須です。-
expression
-
クエリ式です。このフィールドの指定は必須です。
-
expressionNames
-
式の属性名のプレースホルダーを示します。キー - 値のペアの形式になります。キーは
expression
で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、expression
で使用される式の属性名のプレースホルダーのみを入力します。 -
expressionValues
-
式の属性値のプレースホルダーを示します。キー - 値のペアの形式になります。キーは
expression
で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この値は必須です。このフィールドはオプションであり、expression
で使用される式の属性値のプレースホルダーのみを入力します。
-
-
filter
-
DynamoDB からの結果が返される前に、その結果をフィルタリングするために使用する追加フィルタです。フィルタの詳細については、「フィルタ」を参照してください。このフィールドはオプションです。
-
index
-
クエリを実行するインデックスの名前です。DynamoDB クエリの処理により、ハッシュキーのプライマリキーインデックスに加えて、ローカルセカンダリインデックスとグローバルセカンダリインデックスをスキャンできます。指定されると、DynamoDB が指定されたインデックスにクエリを実行します。省略すると、プライマリキーインデックスに対してクエリが実行されます。
-
nextToken
-
前のクエリを継続するためのページ分割トークンです。これは前のクエリから取得されます。このフィールドはオプションです。
-
limit
-
評価する項目の最大数 (一致する項目の数であるとは限りません)。このフィールドはオプションです。
-
scanIndexForward
-
クエリを前方と後方のどちらに実行するかを示すブール値です。このフィールドはオプションであり、デフォルトは
true
です。 -
consistentRead
-
DynamoDB にクエリを実行する際に整合性のある読み込みを使用するかどうかを示すブール値です。このフィールドはオプションであり、デフォルトは
false
です。 -
select
-
デフォルトでは、AWS AppSync DynamoDB のリゾルバーはインデックスに射影されるすべての属性のみを返します。より多くの属性が必要な場合に、このフィールドを設定できます。このフィールドはオプションです。サポートされている値には以下があります。
-
ALL_ATTRIBUTES
-
指定されたテーブルまたはインデックスのすべての項目の属性を返します。ローカルセカンダリインデックスに対してクエリを実行する場合、DynamoDB は、親のテーブルからインデックスの項目に一致したすべての項目をフェッチします。インデックスがすべての項目の属性を射影するように設定されている場合、すべてのデータはローカルセカンダリインデックスから取得されるため、フェッチは必要ありません。
-
ALL_PROJECTED_ATTRIBUTES
-
インデックスにクエリを実行する場合のみ使用できます。インデックスに投射されたすべての属性を取得します。インデックスがすべての属性を投射するように設定されている場合、この返り値は
ALL_ATTRIBUTES
を指定した場合と同等になります。 SPECIFIC_ATTRIBUTES
-
projection
のexpression
にリストされている属性のみを返します。この戻り値は、Select
の値を指定せずにprojection
のexpression
を指定するのと同じです。
-
projection
-
DynamoDB オペレーションから返される属性を指定するために使用されるプロジェクション。プロジェクションの詳細については、「プロジェクション」を参照してください。このフィールドはオプションです。
DynamoDB からの結果が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト ($context.result
) で参照できます。
DynamoDB の型変換の詳細については、「型システム (リクエストマッピング)」を参照してください。
レスポンスマッピングテンプレートの詳細については、「リゾルバーのマッピングテンプレートの概要」を参照してください。
結果は以下の構造を持ちます。
{
items = [ ... ],
nextToken = "a pagination token",
scannedCount = 10
}
各フィールドの定義は以下のようになります。
-
items
-
DynamoDB クエリで返された項目を含むリストです。
-
nextToken
-
さらに結果がある場合、
nextToken
には別のリクエストで使用できるページ分割トークンが含まれています。AWS AppSync は、DynamoDB から返されたページ分割トークンを暗号化および難読化します。これにより、テーブルデータが誤って呼び出し元に漏えいされるのを防ぎます。また、これらのページ分割トークンは、異なるリゾルバー間では使用できないことにも注意してください。 -
scannedCount
-
フィルタ式 (ある場合) が適用される前に、クエリの条件式に一致した項目の数です。
例
次の例は、GraphQL クエリ getPosts(owner:
ID!)
のマッピングテンプレートです。
この例では、テーブルのグローバルセカンダリインデックスにクエリが実行され、指定した ID が所有するすべての投稿が返されます。
{
"version" : "2017-02-28",
"operation" : "Query",
"query" : {
"expression" : "ownerId = :ownerId",
"expressionValues" : {
":ownerId" : $util.dynamodb.toDynamoDBJson($context.arguments.owner)
}
},
"index" : "owner-index"
}
DynamoDB Query
API の詳細については、「DynamoDB API のドキュメント」を参照してください。