本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 内置模块
<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`**  
[输入](#built-in-ddb-modules-inputs)有关信息，请参阅 GetInput。
生成一个`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 发出 [Scan](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` 对象以发出 [Sync](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>

通过使用操作帮助程序，您可以在更新期间对部分数据执行特定的操作。要开始使用，请从 `@aws-appsync/utils/dynamodb` 中导入 `operations`：

```
// 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` 更新列表 (`friendsIds`) 中的第二项（索引 `1`，新 ID `102`）和第三项（索引 `2`，新 ID `112`）的 ID 值。  

```
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 操作时使用的基表的分区键。在表使用自定义分区键时，该字段允许执行 Sync 操作。
+ `deltaIndexName?: string`（可选）

  用于 Sync 操作的索引。在表使用自定义分区键时，需要使用该索引才能对整个增量存储表启用 Sync 操作。Sync 操作是对 GSI（在 `gsi_ds_pk` 和 `gsi_ds_sk` 上创建）执行的。
+ `filter?: DynamoDBFilterObject<T> | null`（可选）

  从表中检索结果后为结果应用的可选筛选条件。
+ `lastSync?: number`（可选）

  上次成功执行的 Sync 操作的启动时间（以纪元毫秒为单位）。如果指定，则仅返回 `lastSync` 之后更改的项目。只有在从初始 Sync 操作中检索所有页面后，才会填充该字段。如果省略，将返回基表的结果。否则，将返回增量表的结果。
+ `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 数据 API 配置的数据库进行交互时，Amazon RDS 模块函数可提供增强的体验。使用 `@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 } }
        ]}
    }));
}
```

您也可以使用以下运算符来比较值：


| 
| 
| 运算符 | 说明 | 可能的值类型 | 
| --- |--- |--- |
| eq | Equal | 数字、字符串、布尔值 | 
| ne | Not equal | 数字、字符串、布尔值 | 
| le | Less than or equal | 数字，字符串 | 
| lt | Less than | 数字，字符串 | 
| ge | Greater than or equal | 数字，字符串 | 
| gt | Greater than | 数字，字符串 | 
| contains | like | 字符串 | 
| 不包含 | 不像 | 字符串 | 
| 开始于 | 以前缀开头 | 字符串 | 
| 介于 | 在两个值之间 | 数字，字符串 | 
| 属性存在 | 该属性不为空 | 数字、字符串、布尔值 | 
| size | 检查元素的长度 | 字符串 | 

#### 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` 的 `name` 更新为 `id` 值 `3`，但仅限我们自 `2000` 年开始就已知道它们 (`known_since`)：

```
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)。你可以使用 AWS AppSync `rds`模块中的`typeHint`函数来转换参数。

以下示例允许您将数组作为强制转换为 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` 类型的对象发送到数据库。