本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Query
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-query"></a>

`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" : {
        ...
    }
}
```

欄位定義如下：

## 查詢欄位
<a name="query-list"></a>

### 查詢欄位清單
<a name="query-list-col"></a>

** `version` **  
範本定義版本。目前支援 `2017-02-28` 和 `2018-05-29`。此值為必填。

** `operation` **  
要執行的 DynamoDB 操作。若要執行 `Query` DynamoDB 操作，這必須設為 `Query`。此值為必填。

** `query` **  
`query` 本節可讓您指定金鑰條件表達式，描述要從 DynamoDB 擷取哪些項目。如需如何編寫索引鍵條件表達式的詳細資訊，請參閱 [DynamoDB KeyConditions 文件](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.KeyConditions.html)。必須指定此區段。    
** `expression` **  
查詢表達式。必須指定此欄位。  
** `expressionNames` **  
表達式屬性 *name* 預留位置的替代，形式為鍵值組。金鑰對應至 中使用的名稱預留位置`expression`，且值必須是對應於 DynamoDB 中項目屬性名稱的字串。此欄位為選用的，應只能填入用於 `expression` 中表達式屬性名稱預留位置的替代。  
** `expressionValues` **  
表達式屬性 *value* 預留位置的替代，形式為鍵值組。鍵對應用於 `expression` 的值預留位置，值必須是類型值。如需如何指定「輸入值」的詳細資訊，請參閱[類型系統 （請求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。此值為必填。此欄位為選用的，應只能填入用於 `expression` 中表達式屬性值預留位置的替代。

** `filter` **  
額外的篩選條件可用來在傳回 DynamoDB 的結果之前先篩選結果。如需篩選條件的詳細資訊，請參閱[篩選條件](aws-appsync-resolver-mapping-template-reference-dynamodb-filter.md)。此欄位為選用欄位。

** `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`。此傳回值等同於指定 `projection`的 ，`expression`而不指定 的任何值`Select`。

**`projection`**  
用於指定要從 DynamoDB 操作傳回之屬性的投影。如需投影的詳細資訊，請參閱[投影](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)。此欄位為選用欄位。

DynamoDB 的結果會自動轉換為 GraphQL 和 JSON 基本類型，並可在映射內容中使用 (`$context.result`)。

如需 DynamoDB 類型轉換的詳細資訊，請參閱[類型系統 （回應映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)。

如需回應映射範本的詳細資訊，請參閱[解析程式映射範本概觀](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)。

結果的結構如下：

```
{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10
}
```

欄位定義如下：

** `items` **  
包含 DynamoDB 查詢傳回項目的清單。

** `nextToken` **  
如果可能有一個以上的結果，`nextToken` 會包含可用於另一個要求的分頁字符。請注意， AWS AppSync 會加密和混淆從 DynamoDB 傳回的分頁字符。這樣可確保資料表的資料不會不慎洩漏給發起人。另請注意，這些分頁字符在不同解析程式之間無法使用。

** `scannedCount` **  
套用篩選條件表達式 (若有的話) 以前符合查詢條件表達式的項目數。

## 範例
<a name="id9"></a>

下列範例是 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 文件](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)。