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

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

`Query` 請求物件可讓您指示 AWS AppSync DynamoDB 解析程式向 DynamoDB 提出`Query`請求，並可讓您指定下列項目：
+ 索引鍵表達式
+ 要使用哪些索引
+ 任何額外篩選條件
+ 要傳回多少項目
+ 是否使用一致性讀取
+ 查詢方向 (向前或向後)
+ 分頁字符

`Query` 請求物件具有下列結構：

```
type DynamoDBQueryRequest = {
  operation: 'Query';
  query: {
    expression: string;
    expressionNames?: { [key: string]: string };
    expressionValues?: { [key: string]: any };
  };
  index?: string;
  nextToken?: string;
  limit?: number;
  scanIndexForward?: boolean;
  consistentRead?: boolean;
  select?: 'ALL_ATTRIBUTES' | 'ALL_PROJECTED_ATTRIBUTES' | 'SPECIFIC_ATTRIBUTES';
  filter?: {
    expression: string;
    expressionNames?: { [key: string]: string };
    expressionValues?: { [key: string]: any };
  };
  projection?: {
    expression: string;
    expressionNames?: { [key: string]: string };
  };
};
```

欄位定義如下：

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

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

** `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` 的值預留位置，值必須是類型值。如需如何指定「輸入值」的詳細資訊，請參閱[類型系統 （請求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。此值為必填。此欄位為選用的，應只能填入用於 `expression` 中表達式屬性值預留位置的替代。

** `filter` **  
額外的篩選條件可用來在傳回 DynamoDB 的結果之前先篩選結果。如需篩選條件的詳細資訊，請參閱[篩選條件](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-filter)。此欄位為選用欄位。

** `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/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-projections)。此欄位為選用欄位。

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

如需 DynamoDB 類型轉換的詳細資訊，請參閱[類型系統 （回應映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)。

如需 JavaScript 解析程式的詳細資訊，請參閱 [JavaScript 解析程式概觀](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)。

結果的結構如下：

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

欄位定義如下：

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

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

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

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

下列範例是 GraphQL 查詢 的函數請求處理常式`getPosts(owner: ID!)`。

在此範例中，資料表上的全域次要索引受到查詢，以傳回指定 ID 擁有的所有文章。

```
import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { owner } = ctx.args;
  return {
    operation: 'Query',
    query: {
      expression: 'ownerId = :ownerId',
      expressionValues: util.dynamodb.toMapValues({ ':ownerId': owner }),
    },
    index: 'owner-index',
  };
}
```

如需 DynamoDB `Query` API 的詳細資訊，請參閱 [DynamoDB API 文件](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)。