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

# Amazon QLDB 中的 FROM（插入、删除或设置）命令
<a name="ql-reference.from"></a>

**重要**  
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。

在 Amazon QLDB 中，以`FROM`开头的语句是 PartiQL 扩展，允许您在文档中插入和删除特定元素。您也可以使用此语句更新文档中的现有元素，类似于[UPDATE](ql-reference.update.md)命令。

**注意**  
要了解如何控制对特定表运行此 PartiQL 命令的访问权限，请参阅[请参阅《Amazon QLDB 开发人员》中的标准权限模式入门](getting-started-standard-mode.md)。

**Topics**
+ [语法](#ql-reference.from.syntax)
+ [参数](#ql-reference.from.parameters)
+ [嵌套集合](#ql-reference.from.nested-collections)
+ [返回值](#ql-reference.from.return)
+ [示例](#ql-reference.from.examples)
+ [使用驱动程序以编程方式运行](#ql-reference.from.driver)

## 语法
<a name="ql-reference.from.syntax"></a>

**FROM-INSERT**

在现有文档内插入新元素。要在表格中插入新顶级文档，必须使用[INSERT](ql-reference.insert.md)。

```
FROM table_name [ AS table_alias ] [ BY id_alias ]
[ WHERE condition ]
INSERT INTO element VALUE data [ AT key_name ]
```

**FROM-REMOVE**

移除文档中的现有元素，或者移除整个顶级文档。后者在语义上与传统 [DELETE](ql-reference.delete.md) 语法相同。

```
FROM table_name [ AS table_alias ] [ BY id_alias ]
[ WHERE condition ]
REMOVE element
```

**FROM-SET**

更新文档中的一项或多项元素。如元素不存在，则将其插入。这在语义上与传统 [UPDATE](ql-reference.update.md) 语法相同。

```
FROM table_name [ AS table_alias ] [ BY id_alias ]
[ WHERE condition ]
SET element = data [, element = data, ... ]
```

## 参数
<a name="ql-reference.from.parameters"></a>

***table\$1name***  
包含要修改数据的用户表的名称。仅默认[用户视图](working.userdata.md)支持 DML 语句。每条语句只能在单个表中运行。  
在此子句中，还可包含嵌套在指定表中的一个或多个集合。有关更多详细信息，请参阅 [嵌套集合](#ql-reference.from.nested-collections)。

**正如 *table\$1alias***  
（可选）用户定义的别名，其范围涵盖要修改的表。`SET`、`REMOVE`、`INSERT INTO` 或 `WHERE`语句中所用的表格别名必须在`FROM`语句中声明。`AS` 关键字是可选的。

**由 *id\$1alias***  
（可选）用户定义的别名，它绑定至结果集中每个文档的 `id`元数据字段。必须使用 `BY` 关键字在 `FROM` 子句中声明别名。当您想在查询默认用户视图的同时筛选[文档 ID](working.metadata.md)，这很有用。有关更多信息，请参阅 [通过 BY 子句查询文档 ID](working.metadata.by-clause.md)。

**哪里 *condition***  
（必需）要修改的文档的选择条件。  
如果省略 `WHERE` 子句，则表中的所有文档都被修改。

***element***  
待创建或修改的文档元素。

***data***  
元素新值。

**在 *key\$1name***  
在要修改的文档中添加的密钥名称。您必须指定相应的 `VALUE` 以及秘钥名称。这是在文档中的特定位置插入新 `AT` 值的必要条件。

## 嵌套集合
<a name="ql-reference.from.nested-collections"></a>

虽然只能对单个表运行 DML 语句，但可以将此表中文档中的嵌套集合指定为其他来源。您为嵌套集合声明的每个别名都可以在 `WHERE`子句和`SET`、`INSERT INTO`或`REMOVE`子句中使用。

例如，以下语句的`FROM` 来源包括 `VehicleRegistration` 表和嵌套 `Owners.SecondaryOwners` 结构。

```
FROM VehicleRegistration r, @r.Owners.SecondaryOwners o
WHERE r.VIN = '1N4AL11D75C109151' AND o.PersonId = 'abc123'
SET o.PersonId = 'def456'
```

此示例更新了特定`SecondaryOwners`列表元素，其中包含`'1N4AL11D75C109151'`中的`VIN`个`VehicleRegistration`文档中的`'abc123'` 的`PersonId`。此表达式允许您按其值而非其索引指定列表中的元素。

## 返回值
<a name="ql-reference.from.return"></a>

`documentId` — 您更新或删除的每个文档的唯一 ID。

## 示例
<a name="ql-reference.from.examples"></a>

修改文档中的一项元素。如果此元素不存在，则将其插入。

```
FROM Vehicle AS v
WHERE v.VIN = '1N4AL11D75C109151' AND v.Color = 'Silver'
SET v.Color = 'Shiny Gray'
```

修改或插入元素并筛选系统分配的文档`id`元数据字段。

```
FROM Vehicle AS v BY v_id
WHERE v_id = 'documentId'
SET v.Color = 'Shiny Gray'
```

修改文档中`Owners.SecondaryOwners`列表中*第一个*元素的`PersonId`字段。

```
FROM VehicleRegistration AS r
WHERE r.VIN = '1N4AL11D75C109151'
SET r.Owners.SecondaryOwners[0].PersonId = 'abc123'
```

移除文档中的现有元素。

```
FROM Person AS p
WHERE p.GovId = '111-22-3333'
REMOVE p.Address
```

从表格中删除整个文档。

```
FROM Person AS p
WHERE p.GovId = '111-22-3333'
REMOVE p
```

移除`VehicleRegistration`表格中文档中`Owners.SecondaryOwners`列表的*第一个*元素。

```
FROM VehicleRegistration AS r
WHERE r.VIN = '1N4AL11D75C109151'
REMOVE r.Owners.SecondaryOwners[0]
```

`{'Mileage':26500}`以顶级名称/值对的形式插入到表格中的文档中。`Vehicle`

```
FROM Vehicle AS v 
WHERE v.VIN = '1N4AL11D75C109151'
INSERT INTO v VALUE 26500 AT 'Mileage'
```

`{'PersonId':'abc123'}`以名称/值对的形式附加至`VehicleRegistration`表格中`Owners.SecondaryOwners`文档的字段中。请注意，语句`Owners.SecondaryOwners`必须已经存在且必须是列表数据类型才会生效。否则，`INSERT INTO`子句中必须使用关键字`AT`。

```
FROM VehicleRegistration AS r 
WHERE r.VIN = '1N4AL11D75C109151'
INSERT INTO r.Owners.SecondaryOwners VALUE { 'PersonId' : 'abc123' }
```

将`{'PersonId':'abc123'}`以文档现有`Owners.SecondaryOwners`列表中的*首个*元素插入。

```
FROM VehicleRegistration AS r 
WHERE r.VIN = '1N4AL11D75C109151'
INSERT INTO r.Owners.SecondaryOwners VALUE {'PersonId' : 'abc123'} AT 0
```

将多个名称/值对附加到文档中的现有`Owners.SecondaryOwners`列表中。

```
FROM VehicleRegistration AS r 
WHERE r.VIN = '1N4AL11D75C109151'
INSERT INTO r.Owners.SecondaryOwners << {'PersonId' : 'abc123'}, {'PersonId' : 'def456'} >>
```

## 使用驱动程序以编程方式运行
<a name="ql-reference.from.driver"></a>

要了解如何使用 QLDB 驱动程序以编程方式运行此语句，请参阅*驱动程序入门*中的以下教程：
+ Java: [快速入门教程](driver-quickstart-java.md) \$1 [说明书参考](driver-cookbook-java.md)
+ .NET: [快速入门教程](driver-quickstart-dotnet.md) \$1 [说明书参考](driver-cookbook-dotnet.md)
+ Go: [快速入门教程](driver-quickstart-golang.md) \$1 [说明书参考](driver-cookbook-golang.md)
+ Node.js: [快速入门教程](driver-quickstart-nodejs.md) \$1 [说明书参考](driver-cookbook-nodejs.md)
+ Python: [快速入门教程](driver-quickstart-python.md) \$1 [说明书参考](driver-cookbook-python.md)