# PartiQL for DynamoDB Update 语句
<a name="ql-reference.update"></a>

使用 `UPDATE` 语句来修改 Amazon DynamoDB 表中某个项目中一个或多个属性的值。

**注意**  
一次只能更新一个项目；不能发出单个 DynamoDB PartiQL 语句更新多个项目。有关更新多个项目的信息，请参阅 [使用 PartiQL for DynamoDB 执行事务](ql-reference.multiplestatements.transactions.md) 或 [对 PartiQL for DynamoDB 运行批处理操作](ql-reference.multiplestatements.batching.md)。

**Topics**
+ [语法](#ql-reference.update.syntax)
+ [参数](#ql-reference.update.parameters)
+ [返回值](#ql-reference.update.return)
+ [示例](#ql-reference.update.examples)

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

```
UPDATE  table  
[SET | REMOVE]  path  [=  data] […]
WHERE condition [RETURNING returnvalues]
<returnvalues>  ::= [ALL OLD | MODIFIED OLD | ALL NEW | MODIFIED NEW] *
```

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

***表*\$1**  
（必需）包含要修改的数据的表。

***path***  
（必需）要创建或修改的属性名称或文档路径。

***data***  
（必需）属性值或操作的结果。  
要与 SET 一起使用的支持操作：  
+ LIST\$1APPEND：向列表类型添加一个值。
+ SET\$1ADD：将值添加到数字或字符串集。
+ SET\$1DELETE：从数字或字符串集中删除值。

***条件***  
（必需）要修改的项目的选择条件。此条件必须解析为单个主键值。

***returnvalues***  
（可选）如果希望获取更新之前或之后显示的项目属性，使用 `returnvalues`。有效值为：  
+ `ALL OLD *` - 返回更新操作前项目的所有属性。
+ `MODIFIED OLD *` - 仅返回更新操作前已更新的属性。
+ `ALL NEW *` - 返回更新操作后显示的项目的所有属性。
+ `MODIFIED NEW *` - 仅返回 `UpdateItem` 操作后已更新的属性。

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

此语句不返回值，除非指定 `returnvalues` 参数。

**注意**  
如果对于 DynamoDB 表中的任何项目，UPDATE 语句的 WHERE 子句计算结果不为 true，则返回 `ConditionalCheckFailedException`。

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

更新现有项目的属性值。如果属性不存在，则创建该属性。

下面的查询添加一个 number 类型参数 (`AwardsWon`) 和一个 map 类型参数 (`AwardDetail`)，更新 `"Music"` 表的项目。

```
UPDATE "Music" 
SET AwardsWon=1 
SET AwardDetail={'Grammys':[2020, 2018]}  
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```

您可以添加 `RETURNING ALL OLD *` 以返回在 `Update` 操作之前显示的属性。

```
UPDATE "Music" 
SET AwardsWon=1 
SET AwardDetail={'Grammys':[2020, 2018]}  
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
RETURNING ALL OLD *
```

这将返回以下内容：

```
{
    "Items": [
        {
            "Artist": {
                "S": "Acme Band"
            },
            "SongTitle": {
                "S": "PartiQL Rocks"
            }
        }
    ]
}
```

您可以添加 `RETURNING ALL NEW *` 以返回在 `Update` 操作之后显示的属性。

```
UPDATE "Music" 
SET AwardsWon=1 
SET AwardDetail={'Grammys':[2020, 2018]}  
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
RETURNING ALL NEW *
```

这将返回以下内容：

```
{
    "Items": [
        {
            "AwardDetail": {
                "M": {
                    "Grammys": {
                        "L": [
                            {
                                "N": "2020"
                            },
                            {
                                "N": "2018"
                            }
                        ]
                    }
                }
            },
            "AwardsWon": {
                "N": "1"
            }
        }
    ]
}
```

以下查询通过附加到列表 `AwardDetail.Grammys`，更新 `"Music"` 表中的项目。

```
UPDATE "Music" 
SET AwardDetail.Grammys =list_append(AwardDetail.Grammys,[2016])  
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```

以下查询通过从列表 `AwardDetail.Grammys` 移除，更新 `"Music"` 表中的项目。

```
UPDATE "Music" 
REMOVE AwardDetail.Grammys[2]   
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```

以下查询通过将 `BillBoard` 添加到映射 `AwardDetail`，更新 `"Music"` 表中的项目。

```
UPDATE "Music" 
SET AwardDetail.BillBoard=[2020] 
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```

以下查询添加字符串集属性 `BandMembers`，更新 `"Music"` 表中的项目。

```
UPDATE "Music" 
SET BandMembers =<<'member1', 'member2'>> 
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```

以下查询将 `newbandmember` 添加到字符串集 `BandMembers`，更新 `"Music"` 表中的项目。

```
UPDATE "Music" 
SET BandMembers =set_add(BandMembers, <<'newbandmember'>>) 
WHERE Artist='Acme Band' AND SongTitle='PartiQL Rocks'
```