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

# 內建模組
<a name="built-in-modules-js"></a>

模組是`APPSYNC_JS`執行時間的一部分，並提供公用程式以協助撰寫 JavaScript 解析程式和函數。如需範例和範例，請參閱 [aws-appsync-resolver-samples](https://github.com/aws-samples/aws-appsync-resolver-samples) GitHub 儲存庫。

## DynamoDB 模組函數
<a name="built-in-ddb-modules"></a>

DynamoDB 模組函數可在與 DynamoDB 資料來源互動時提供增強的體驗。您可以使用 函數向 DynamoDB 資料來源提出請求，而無需新增類型映射。

使用 匯入模組`@aws-appsync/utils/dynamodb`：

```
// Modules are imported using @aws-appsync/utils/dynamodb
import * as ddb from '@aws-appsync/utils/dynamodb';
```

### 函數
<a name="built-in-ddb-modules-functions"></a>

#### 函數清單
<a name="built-in-ddb-modules-functions-list"></a>

 **` get<T>(payload: GetInput): DynamoDBGetItemRequest`**  
如需 GetInput 的相關資訊[輸入](#built-in-ddb-modules-inputs)，請參閱 。
產生`DynamoDBGetItemRequest`物件以向 DynamoDB 提出 [GetItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-getitem) 請求。  

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

export function request(ctx) {
	return get({ key: { id: ctx.args.id } });
}
```

 **`put<T>(payload): DynamoDBPutItemRequest`**  
產生`DynamoDBPutItemRequest`物件以向 DynamoDB 提出 [PutItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-putitem) 請求。  

```
import * as ddb from '@aws-appsync/utils/dynamodb'

export function request(ctx) {
	return ddb.put({ key: { id: util.autoId() }, item: ctx.args });
}
```

**`remove<T>(payload): DynamoDBDeleteItemRequest`**  
產生`DynamoDBDeleteItemRequest`物件以向 DynamoDB 提出 [DeleteItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-deleteitem) 請求。  

```
import * as ddb from '@aws-appsync/utils/dynamodb';

export function request(ctx) {
	return ddb.remove({ key: { id: ctx.args.id } });
}
```

**`scan<T>(payload): DynamoDBScanRequest`**  
產生 `DynamoDBScanRequest`以向 DynamoDB 提出[掃描](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-scan)請求。  

```
import * as ddb from '@aws-appsync/utils/dynamodb';

export function request(ctx) {
	const { limit = 10, nextToken } = ctx.args;
	return ddb.scan({ limit, nextToken });
}
```

**`sync<T>(payload): DynamoDBSyncRequest`**  
產生`DynamoDBSyncRequest`物件以提出[同步](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-sync)請求。請求只會接收自上次查詢後更改的資料 （差異更新）。只能對版本控制的 DynamoDB 資料來源提出請求。  

```
import * as ddb from '@aws-appsync/utils/dynamodb';

export function request(ctx) {
	const { limit = 10, nextToken, lastSync } = ctx.args;
	return ddb.sync({ limit, nextToken, lastSync });
}
```

**`update<T>(payload): DynamoDBUpdateItemRequest`**  
產生`DynamoDBUpdateItemRequest`物件以向 DynamoDB 提出 [UpdateItem](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-updateitem) 請求。

### 作業
<a name="built-in-ddb-modules-operations"></a>

操作協助程式可讓您在更新期間對部分資料採取特定動作。若要開始使用，`operations`請從 匯入`@aws-appsync/utils/dynamodb`：

```
// Modules are imported using operations
import {operations} from '@aws-appsync/utils/dynamodb';
```

#### 操作清單
<a name="built-in-ddb-modules-operations-list"></a>

 **`add<T>(payload)`**  
在更新 DynamoDB 時新增屬性項目的協助程式函數。  
**範例**  
若要使用 ID 值將地址 （街道、城市和郵遞區號） 新增至現有的 DynamoDB 項目：  

```
import { update, operations } from '@aws-appsync/utils/dynamodb';

export function request(ctx) {
	const updateObj = {
		address: operations.add({
			street1: '123 Main St',
			city: 'New York',
			zip: '10001',
		}),
	};
	return update({ key: { id: 1 }, update: updateObj });
}
```

**`append <T>(payload)`**  
將承載附加至 DynamoDB 中現有清單的協助程式函數。  
**範例**  
若要在更新期間將新增IDs (`newFriendIds`) 附加至現有的朋友清單 (`friendsIds`)：  

```
import { update, operations } from '@aws-appsync/utils/dynamodb';

export function request(ctx) {
	const newFriendIds = [101, 104, 111];
	const updateObj = {
		friendsIds: operations.append(newFriendIds),
	};
	return update({ key: { id: 1 }, update: updateObj });
}
```

**`decrement (by?)`**  
在更新 DynamoDB 時減少項目中現有屬性值的協助程式函數。  
**範例**  
若要將朋友計數器 (`friendsCount`) 減少 10：  

```
import { update, operations } from '@aws-appsync/utils/dynamodb';

export function request(ctx) {
	const updateObj = {
		friendsCount: operations.decrement(10),
	};
	return update({ key: { id: 1 }, update: updateObj });
}
```

**`increment (by?)`**  
在更新 DynamoDB 時遞增項目中現有屬性值的協助程式函數。  
**範例**  
若要將好友計數器 (`friendsCount`) 增加 10：  

```
import { update, operations } from '@aws-appsync/utils/dynamodb';

export function request(ctx) {
	const updateObj = {
		friendsCount: operations.increment(10),
	};
	return update({ key: { id: 1 }, update: updateObj });
}
```

**`prepend <T>(payload)`**  
在 DynamoDB 中現有清單前面的協助程式函數。  
**範例**  
若要在更新期間將新增IDs (`newFriendIds`) 附加至現有的朋友清單 (`friendsIds`)：  

```
import { update, operations } from '@aws-appsync/utils/dynamodb';

export function request(ctx) {
	const newFriendIds = [101, 104, 111];
	const updateObj = {
		friendsIds: operations.prepend(newFriendIds),
	};
	return update({ key: { id: 1 }, update: updateObj });
}
```

**`replace <T>(payload)`**  
在 DynamoDB 中更新項目時取代現有屬性的協助程式函數。當您想要更新屬性中的整個物件或子物件，而不只是承載中的索引鍵時，此功能非常有用。  
**範例**  
若要取代 `info` 物件中的地址 （街道、城市和郵遞區號）：  

```
import { update, operations } from '@aws-appsync/utils/dynamodb';

export function request(ctx) {
	const updateObj = {
		info: {
			address: operations.replace({
				street1: '123 Main St',
				city: 'New York',
				zip: '10001',
			}),
		},
	};
	return update({ key: { id: 1 }, update: updateObj });
}
```

**`updateListItem <T>(payload, index)`**  
取代清單中項目的協助程式函數。  
**範例**  
在更新範圍 (`newFriendIds`) 中，此範例用於`updateListItem`更新清單中第二個項目 （索引：`1`，新 ID：`102`) 和第三個項目 （索引：`2`，新 ID：`112`) 的 ID 值 ()`friendsIds`。  

```
import { update, operations as ops } from '@aws-appsync/utils/dynamodb';

export function request(ctx) {
	const newFriendIds = [
		ops.updateListItem('102', 1), ops.updateListItem('112', 2)
	];
	const updateObj = { friendsIds: newFriendIds };
	return update({ key: { id: 1 }, update: updateObj });
}
```

### 輸入
<a name="built-in-ddb-modules-inputs"></a>

#### 輸入清單
<a name="built-in-ddb-modules-inputs-list"></a>

 **`Type GetInput<T>`**  

```
GetInput<T>: { 
    consistentRead?: boolean; 
    key: DynamoDBKey<T>; 
}
```
**類型宣告**  
+ `consistentRead?: boolean` (選用)

  選用布林值，用於指定是否要與 DynamoDB 執行強式一致讀取。
+ `key: DynamoDBKey<T>` (必要)

  在 DynamoDB 中指定項目索引鍵的必要參數。DynamoDB 項目可能有單一雜湊索引鍵或雜湊和排序索引鍵。

**`Type PutInput<T>`**  

```
PutInput<T>: { 
    _version?: number; 
    condition?: DynamoDBFilterObject<T> | null; 
    customPartitionKey?: string; 
    item: Partial<T>; 
    key: DynamoDBKey<T>; 
    populateIndexFields?: boolean; 
}
```
**類型宣告**  
+ `_version?: number` (選用)
+ `condition?: DynamoDBFilterObject<T> | null` (選用)

  當您將物件放入 DynamoDB 資料表時，您可以選擇指定條件式表達式，以根據在執行操作之前已在 DynamoDB 中的物件狀態來控制請求是否成功。
+ `customPartitionKey?: string` (選用)

  啟用時，此字串值會修改啟用版本控制時差異同步資料表所使用的 `ds_sk`和 `ds_pk` 記錄格式。啟用時，也會啟用`populateIndexFields`項目的處理。
+ `item: Partial<T>` (必要)

  要放入 DynamoDB 之項目的其餘屬性。
+ `key: DynamoDBKey<T>` (必要)

  必要參數，指定 DynamoDB 中要對其執行放置的項目索引鍵。DynamoDB 項目可能有單一雜湊索引鍵或雜湊和排序索引鍵。
+ `populateIndexFields?: boolean` (選用)

  布林值，當 與 啟用時`customPartitionKey`，會為差異同步資料表中的每個記錄建立新的項目，特別是在 `gsi_ds_pk`和 `gsi_ds_sk`欄中。如需詳細資訊，請參閱《 *AWS AppSync 開發人員指南*》中的[衝突偵測和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)。

**`Type QueryInput<T>`**  

```
QueryInput<T>: ScanInput<T> & { 
    query: DynamoDBKeyCondition<Required<T>>; 
}
```
**類型宣告**  
+ `query: DynamoDBKeyCondition<Required<T>>` (必要)

  指定描述要查詢之項目的金鑰條件。對於指定的索引，分割區索引鍵的條件應為等式，排序索引鍵應為比較或 `beginsWith`（當它是字串時）。分割區和排序索引鍵僅支援數字和字串類型。

  **範例**

  請採用以下`User`類型：

  ```
  type User = {
    id: string;
    name: string;
    age: number;
    isVerified: boolean;
    friendsIds: string[] 
  }
  ```

  查詢只能包含下列欄位：`id`、 `name`和 `age`：

  ```
  const query: QueryInput<User> = {
      name: { eq: 'John' },
      age: { gt: 20 },
  }
  ```

**`Type RemoveInput<T>`**  

```
RemoveInput<T>: { 
    _version?: number; 
    condition?: DynamoDBFilterObject<T>; 
    customPartitionKey?: string; 
    key: DynamoDBKey<T>; 
    populateIndexFields?: boolean; 
}
```
**類型宣告**  
+ `_version?: number` (選用)
+ `condition?: DynamoDBFilterObject<T>` (選用)

  當您在 DynamoDB 中移除物件時，您可以選擇指定條件式表達式，以根據在執行操作之前已在 DynamoDB 中的物件狀態來控制請求是否成功。

  **範例**

  下列範例是包含條件的`DeleteItem`表達式，只有在文件擁有者符合提出請求的使用者時，才會允許操作成功。

  ```
  type Task = {
    id: string;
    title: string;
    description: string;
    owner: string;
    isComplete: boolean;
  }
  const condition: DynamoDBFilterObject<Task> = {
    owner: { eq: 'XXXXXXXXXXXXXXXX' },
  }
  
  remove<Task>({
     key: {
       id: 'XXXXXXXXXXXXXXXX',
    },
    condition,
  });
  ```
+ `customPartitionKey?: string` (選用)

  啟用時， `customPartitionKey`值會修改啟用版本控制時差異同步資料表所使用的 `ds_sk`和 `ds_pk` 記錄格式。啟用時，也會啟用`populateIndexFields`項目的處理。
+ `key: DynamoDBKey<T>` (必要)

  必要參數，指定要移除之 DynamoDB 中項目的索引鍵。DynamoDB 項目可能有單一雜湊索引鍵或雜湊和排序索引鍵。

  **範例**

  如果`User`只有使用者 的雜湊金鑰`id`，則金鑰看起來會如下所示：

  ```
  type User = {
  	id: number
  	name: string
  	age: number
  	isVerified: boolean
  }
  const key: DynamoDBKey<User> = {
  	id: 1,
  }
  ```

  如果資料表使用者具有雜湊索引鍵 (`id`) 和排序索引鍵 (`name`)，則索引鍵看起來會如下所示：

  ```
  type User = {
  	id: number
  	name: string
  	age: number
  	isVerified: boolean
  	friendsIds: string[]
  }
  
  const key: DynamoDBKey<User> = {
  	id: 1,
  	name: 'XXXXXXXXXX',
  }
  ```
+ `populateIndexFields?: boolean` (選用)

  布林值，當 與 啟用時`customPartitionKey`，會為差異同步資料表中的每個記錄建立新的項目，特別是在 `gsi_ds_pk`和 `gsi_ds_sk`欄中。

**`Type ScanInput<T>`**  

```
ScanInput<T>: { 
    consistentRead?: boolean | null; 
    filter?: DynamoDBFilterObject<T> | null; 
    index?: string | null; 
    limit?: number | null; 
    nextToken?: string | null; 
    scanIndexForward?: boolean | null; 
    segment?: number; 
    select?: DynamoDBSelectAttributes; 
    totalSegments?: number; 
}
```
**類型宣告**  
+ `consistentRead?: boolean | null` (選用)

  在查詢 DynamoDB 時指出一致讀取的選用布林值。預設值為 `false`。
+ `filter?: DynamoDBFilterObject<T> | null` (選用)

  從資料表擷取結果後，要套用至結果的選用篩選條件。
+ `index?: string | null` (選用)

  要掃描的索引選用名稱。
+ `limit?: number | null` (選用)

  要傳回的選用結果數目上限。
+ `nextToken?: string | null` (選用)

  選用分頁字符，以繼續先前的查詢。這會是從先前查詢所取得的。
+ `scanIndexForward?: boolean | null` (選用)

  選用布林值，指出查詢是以遞增或遞減順序執行。依預設，此值是設為 `true`。
+ `segment?: number` (選用)
+ `select?: DynamoDBSelectAttributes` (選用)

  從 DynamoDB 傳回的屬性。根據預設， AWS AppSync DynamoDB 解析程式只會傳回投影到索引中的屬性。支援的值是：
  + `ALL_ATTRIBUTES`

    從指定的資料表或索引傳回所有項目屬性。如果您查詢本機次要索引，DynamoDB 會從索引中每個相符項目的父資料表擷取整個項目。如果索引設定為投射所有項目屬性，所有資料都可從本機次要索引取得，不需進行任何擷取。
  + `ALL_PROJECTED_ATTRIBUTES`

    傳回已投影至索引的所有屬性。如果索引設定為投射所有屬性，此傳回值相當於指定 `ALL_ATTRIBUTES`。
  + `SPECIFIC_ATTRIBUTES`

    僅傳回 中列出的屬性`ProjectionExpression`。此傳回值等同於指定 ，`ProjectionExpression`而不指定 的任何值`AttributesToGet`。
+ `totalSegments?: number` (選用)

**`Type DynamoDBSyncInput<T>`**  

```
DynamoDBSyncInput<T>: { 
    basePartitionKey?: string; 
    deltaIndexName?: string; 
    filter?: DynamoDBFilterObject<T> | null; 
    lastSync?: number; 
    limit?: number | null; 
    nextToken?: string | null; 
}
```
**類型宣告**  
+ `basePartitionKey?: string` (選用)

  執行同步操作時要使用之基底資料表的分割區索引鍵。此欄位允許在資料表使用自訂分割區索引鍵時執行 Sync 操作。
+ `deltaIndexName?: string` (選用)

  用於同步操作的索引。當資料表使用自訂分割區索引鍵時，需要此索引才能在整個差異存放區資料表上啟用同步操作。同步操作將在 GSI 上執行 （在 `gsi_ds_pk`和 上建立`gsi_ds_sk`)。
+ `filter?: DynamoDBFilterObject<T> | null` (選用)

  從資料表擷取結果後，要套用至結果的選用篩選條件。
+ `lastSync?: number` (選用)

  上次成功同步操作開始的時刻，以 epoch 毫秒為單位。如果指定此值，只會傳回 `lastSync` 之後變更的項目。只有在從初始同步操作擷取所有頁面之後，才應該填入此欄位。如果省略，則會傳回基礎資料表的結果。否則，將會傳回差異資料表的結果。
+ `limit?: number | null` (選用)

  要一次評估的選用項目數量上限。如果省略此值，預設限制將設為 `100` 個項目。此欄位的最大值為 `1000` 個項目。
+ `nextToken?: string | null` (選用)

**`Type DynamoDBUpdateInput<T>`**  

```
DynamoDBUpdateInput<T>: { 
    _version?: number; 
    condition?: DynamoDBFilterObject<T>; 
    customPartitionKey?: string; 
    key: DynamoDBKey<T>; 
    populateIndexFields?: boolean; 
    update: DynamoDBUpdateObject<T>; 
}
```
**類型宣告**  
+ `_version?: number` (選用)
+ `condition?: DynamoDBFilterObject<T>` (選用)

  當您更新 DynamoDB 中的物件時，您可以選擇指定條件式表達式，以根據在執行操作之前已在 DynamoDB 中的物件狀態來控制請求是否成功。
+ `customPartitionKey?: string` (選用)

  啟用時， `customPartitionKey`值會修改啟用版本控制時差異同步資料表所使用的 `ds_sk`和 `ds_pk` 記錄格式。啟用時，也會啟用`populateIndexFields`項目的處理。
+ `key: DynamoDBKey<T>` (必要)

  必要參數，指定正在更新的 DynamoDB 中項目的索引鍵。DynamoDB 項目可能有單一雜湊索引鍵或雜湊和排序索引鍵。
+ `populateIndexFields?: boolean` (選用)

  布林值，當 與 啟用時`customPartitionKey`，會為差異同步資料表中的每個記錄建立新的項目，特別是在 `gsi_ds_pk`和 `gsi_ds_sk`欄中。
+ `update: DynamoDBUpdateObject<T>`

  指定要更新的屬性及其新值的物件。更新物件可與 `add`、`remove`、、`replace``increment`、`decrement`、`append`、`prepend`、 搭配使用`updateListItem`。

## Amazon RDS 模組函數
<a name="built-in-rds-modules"></a>

Amazon RDS 模組函數可在與使用 Amazon RDS Data API 設定的資料庫互動時提供增強的體驗。使用 匯入模組`@aws-appsync/utils/rds`：

```
import * as rds from '@aws-appsync/utils/rds';
```

也可以個別匯入函數。例如，以下匯入使用 `sql`：

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

### 函數
<a name="built-in-rds-modules-functions"></a>

您可以使用 AWS AppSync RDS 模組的公用程式協助程式來與資料庫互動。

#### Select
<a name="built-in-rds-modules-functions-select"></a>

`select` 公用程式會建立 `SELECT`陳述式來查詢您的關聯式資料庫。

**基本使用**

以其基本形式，您可以指定要查詢的資料表：

```
import { select, createPgStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {

    // Generates statement: 
    // "SELECT * FROM "persons"
    return createPgStatement(select({table: 'persons'}));
}
```

請注意，您也可以在資料表識別符中指定結構描述：

```
import { select, createPgStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {

    // Generates statement:
    // SELECT * FROM "private"."persons"
    return createPgStatement(select({table: 'private.persons'}));
}
```

**指定資料欄**

您可以使用 `columns` 屬性指定資料欄。如果未將此值設定為 ，則預設為 `*`：

```
export function request(ctx) {

    // Generates statement:
    // SELECT "id", "name"
    // FROM "persons"
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name']
    }));
}
```

您也可以指定資料欄的資料表：

```
export function request(ctx) {

    // Generates statement: 
    // SELECT "id", "persons"."name"
    // FROM "persons"
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'persons.name']
    }));
}
```

**限制和位移**

您可以套用 `limit`和 `offset`至查詢：

```
export function request(ctx) {

    // Generates statement: 
    // SELECT "id", "name"
    // FROM "persons"
    // LIMIT :limit
    // OFFSET :offset
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name'],
        limit: 10,
        offset: 40
    }));
}
```

**排序依據**

您可以使用 `orderBy` 屬性排序結果。提供指定 欄和選用 `dir` 屬性的物件陣列：

```
export function request(ctx) {

    // Generates statement: 
    // SELECT "id", "name" FROM "persons"
    // ORDER BY "name", "id" DESC
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name'],
        orderBy: [{column: 'name'}, {column: 'id', dir: 'DESC'}]
    }));
}
```

**篩選條件**

您可以使用特殊條件物件來建置篩選條件：

```
export function request(ctx) {

    // Generates statement:
    // SELECT "id", "name"
    // FROM "persons"
    // WHERE "name" = :NAME
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name'],
        where: {name: {eq: 'Stephane'}}
    }));
}
```

您也可以合併篩選條件：

```
export function request(ctx) {

    // Generates statement:
    // SELECT "id", "name"
    // FROM "persons"
    // WHERE "name" = :NAME and "id" > :ID
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name'],
        where: {name: {eq: 'Stephane'}, id: {gt: 10}}
    }));
}
```

您也可以建立`OR`陳述式：

```
export function request(ctx) {

    // Generates statement:
    // SELECT "id", "name"
    // FROM "persons"
    // WHERE "name" = :NAME OR "id" > :ID
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name'],
        where: { or: [
            { name: { eq: 'Stephane'} },
            { id: { gt: 10 } }
        ]}
    }));
}
```

您也可以使用 否定條件`not`：

```
export function request(ctx) {

    // Generates statement:
    // SELECT "id", "name"
    // FROM "persons"
    // WHERE NOT ("name" = :NAME AND "id" > :ID)
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name'],
        where: { not: [
            { name: { eq: 'Stephane'} },
            { id: { gt: 10 } }
        ]}
    }));
}
```

您也可以使用下列運算子來比較值：


| 
| 
| 運算子 | Description | 可能的值類型 | 
| --- |--- |--- |
| eq | Equal | number, string, boolean | 
| ne | Not equal | number, string, boolean | 
| le | Less than or equal | number, string | 
| lt | Less than | number, string | 
| ge | Greater than or equal | number, string | 
| gt | Greater than | number, string | 
| contains | Like | string | 
| notContains | Not like | string | 
| beginsWith | Starts with prefix | string | 
| between | Between two values | number, string | 
| attributeExists | The attribute is not null | number, string, boolean | 
| size | checks the length of the element | string | 

#### Insert
<a name="built-in-rds-modules-functions-insert"></a>

`insert` 公用程式提供使用 `INSERT`操作在資料庫中插入單一資料列項目的直接方式。

**單一項目插入**

若要插入項目，請指定 資料表，然後傳入值的物件。物件索引鍵會映射到您的資料表資料欄。資料欄名稱會自動逸出，並使用變數映射將值傳送至資料庫：

```
import { insert, createMySQLStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const { input: values } = ctx.args;
    const insertStatement = insert({ table: 'persons', values });
    
    // Generates statement:
    // INSERT INTO `persons`(`name`)
    // VALUES(:NAME)
    return createMySQLStatement(insertStatement)
}
```

**MySQL 使用案例**

您可以結合 `insert`後接 `select`來擷取插入的資料列：

```
import { insert, select, createMySQLStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const { input: values } = ctx.args;
    const insertStatement = insert({  table: 'persons', values });
    const selectStatement = select({
        table: 'persons',
        columns: '*',
        where: { id: { eq: values.id } },
        limit: 1,
    });
    
    // Generates statement:
    // INSERT INTO `persons`(`name`)
    // VALUES(:NAME)
    // and
    // SELECT *
    // FROM `persons`
    // WHERE `id` = :ID
    return createMySQLStatement(insertStatement, selectStatement)
}
```

**Postgres 使用案例**

使用 Postgres，您可以使用 從您插入的資料列[https://www.postgresql.org/docs/current/dml-returning.html](https://www.postgresql.org/docs/current/dml-returning.html)取得資料。它接受 `*`或一組資料欄名稱：

```
import { insert, createPgStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const { input: values } = ctx.args;
    const insertStatement = insert({
        table: 'persons',
        values,
        returning: '*'
    });

    // Generates statement:
    // INSERT INTO "persons"("name")
    // VALUES(:NAME)
    // RETURNING *
    return createPgStatement(insertStatement)
}
```

#### 更新
<a name="built-in-rds-modules-functions-update"></a>

`update` 公用程式可讓您更新現有的資料列。您可以使用 條件物件，將變更套用至滿足條件的所有資料列中的指定資料欄。例如，假設我們有一個結構描述，允許我們進行此變動。我們希望以 `Person` `id`的值更新 `name` 的 ，`3`但前提是我們從 開始知道它們 (`known_since`)`2000`：

```
mutation Update {
    updatePerson(
        input: {id: 3, name: "Jon"},
        condition: {known_since: {ge: "2000"}}
    ) {
    id
    name
  }
}
```

我們的更新解析程式如下所示：

```
import { update, createPgStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const { input: { id, ...values }, condition } = ctx.args;
    const where = {
        ...condition,
        id: { eq: id },
    };
    const updateStatement = update({
        table: 'persons',
        values,
        where,
        returning: ['id', 'name'],
    });

    // Generates statement:
    // UPDATE "persons"
    // SET "name" = :NAME, "birthday" = :BDAY, "country" = :COUNTRY
    // WHERE "id" = :ID
    // RETURNING "id", "name"
    return createPgStatement(updateStatement)
}
```

我們可以將檢查新增至條件，以確保只會更新主索引鍵`id`等於 `3` 的資料列。同樣地，對於 Postgres `inserts`，您可以使用 `returning` 來傳回修改後的資料。

#### 移除
<a name="built-in-rds-modules-functions-remove"></a>

`remove` 公用程式可讓您刪除現有的資料列。您可以在滿足條件的所有資料列上使用條件物件。請注意， `delete` 是 JavaScript 中的預留關鍵字。 `remove` 應該改用：

```
import { remove, createPgStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const { input: { id }, condition } = ctx.args;
    const where = { ...condition, id: { eq: id } };
    const deleteStatement = remove({
        table: 'persons',
        where,
        returning: ['id', 'name'],
    });

    // Generates statement:
    // DELETE "persons"
    // WHERE "id" = :ID
    // RETURNING "id", "name"
    return createPgStatement(updateStatement)
}
```

### 轉換
<a name="built-in-rds-modules-casting"></a>

在某些情況下，您可能希望在陳述式中使用有關正確物件類型的更具體性。您可以使用提供的類型提示來指定參數的類型。 AWS AppSync 支援與資料 API [相同的類型提示](https://docs.aws.amazon.com//rdsdataservice/latest/APIReference/API_SqlParameter.html#rdsdtataservice-Type-SqlParameter-typeHint)。您可以使用 模組的 `typeHint`函數來 AWS AppSync `rds`轉換參數。

下列範例可讓您將陣列做為值傳送，該值會轉換為 JSON 物件。我們使用 `->`運算子來擷取 JSON 陣列`index``2`中 的 元素：

```
import { sql, createPgStatement, toJsonObject, typeHint } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const arr = ctx.args.list_of_ids
    const statement = sql`select ${typeHint.JSON(arr)}->2 as value`
    return createPgStatement(statement)
}

export function response(ctx) {
    return toJsonObject(ctx.result)[0][0].value
}
```

在處理和比較 `DATE`、 和 時`TIME`，投射也很有用`TIMESTAMP`：

```
import { select, createPgStatement, typeHint } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const when = ctx.args.when
    const statement = select({
        table: 'persons',
        where: { createdAt : { gt: typeHint.DATETIME(when) } }
    })
    return createPgStatement(statement)
}
```

以下另一個範例示範如何傳送目前的日期和時間：

```
import { sql, createPgStatement, typeHint } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const now = util.time.nowFormatted('YYYY-MM-dd HH:mm:ss')
    return createPgStatement(sql`select ${typeHint.TIMESTAMP(now)}`)
}
```

**可用的類型提示**
+ `typeHint.DATE` - 對應的參數會以 `DATE`類型的物件傳送至資料庫。接受的格式為 `YYYY-MM-DD`。
+ `typeHint.DECIMAL` - 對應的參數會以 `DECIMAL`類型的物件傳送至資料庫。
+ `typeHint.JSON` - 對應的參數會以 `JSON`類型的物件傳送至資料庫。
+ `typeHint.TIME` - 對應的字串參數值會以 `TIME`類型的物件傳送至資料庫。接受的格式為 `HH:MM:SS[.FFF]`。
+ `typeHint.TIMESTAMP` - 對應的字串參數值會以 `TIMESTAMP`類型的物件傳送至資料庫。接受的格式為 `YYYY-MM-DD HH:MM:SS[.FFF]`。
+ `typeHint.UUID` - 對應的字串參數值會以 `UUID`類型的物件傳送至資料庫。