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

Amazon DynamoDB 支持以下 PartiQL 语句。

**注意**  
DynamoDB 不支持所有 PartiQL 语句。  
此参考提供可以使用 AWS CLI 或 API 手动运行的 PartiQL 语句的基本语法和用法示例。

*数据操作语言* (DML) 是一组用于管理 DynamoDB 表中的数据的 PartiQL 语句。可以使用 DML 语句在表中添加、修改或删除数据。

支持以下 DML 和查询语言语句：
+ [PartiQL for DynamoDB 的 Select 语句](ql-reference.select.md)
+ [PartiQL for DynamoDB Update 语句](ql-reference.update.md)
+ [PartiQL for DynamoDB Insert 语句](ql-reference.insert.md)
+ [PartiQL for DynamoDB Delete 语句](ql-reference.delete.md)

PartiQL for DynamoDB 还支持 [使用 PartiQL for DynamoDB 执行事务](ql-reference.multiplestatements.transactions.md) 和 [对 PartiQL for DynamoDB 运行批处理操作](ql-reference.multiplestatements.batching.md)。

# PartiQL for DynamoDB 的 Select 语句
<a name="ql-reference.select"></a>

使用 `SELECT` 语句从 Amazon DynamoDB 的表检索数据。

如果 WHERE 子句中未提供带有分区键的相等或 IN 条件，使用 `SELECT` 语句会导致全表扫描。扫描操作会检查每个项目的请求值，并且可以在单个操作中使用大型表或索引的预置吞吐量。

如果您想避免在 PartiQL 中进行全表扫描，您可以：
+ 创作您的 `SELECT` 语句不会导致全表扫描，方法是确保您的 [WHERE 子句条件](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html#ql-reference.select.parameters)相应地配置。
+ 使用《DynamoDB 开发人员指南》[示例：允许 Select 语句并拒绝 PartiQL for DynamoDB 的完整表扫描语句](ql-iam.md#access-policy-ql-iam-example6)中指定的 IAM 策略禁用全表扫描。

有关更多信息，请参阅《DynamoDB 开发人员指南》中的[查询和扫描数据的最佳实践](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-query-scan.html)。

**Topics**
+ [语法](#ql-reference.select.syntax)
+ [参数](#ql-reference.select.parameters)
+ [示例](#ql-reference.select.examples)

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

```
SELECT expression  [, ...] 
FROM table[.index]
[ WHERE condition ] [ [ORDER BY key [DESC|ASC] , ...]
```

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

***expression***  
（必需）从 `*` 通配符形成的投影，或者结果集的一个或多个属性名称或文档路径的投影列表。表达式可以包括对 [将 PartiQL 函数和 DynamoDB 结合使用](ql-functions.md) 或通过 [用于 DynamoDB 的 PartiQL 算术、比较和逻辑运算符](ql-operators.md) 修改的字段的调用。

***table***  
（必需）要查询的表名。

***index***  
（可选）要查询的索引的名称。  
查询索引时，必须在表名和索引名称中添加双引号。  

```
SELECT * 
FROM "TableName"."IndexName"
```

***条件***  
（可选）查询的选择条件。  
为了确保 `SELECT` 语句不会导致全表扫描，`WHERE` 子句条件必须指定分区键。使用相等或 IN 运算符。  
例如，如果 `Orders` 表有 `OrderID` 分区键和其他非键属性，包括 `Address`，则以下语句不会导致完整表扫描：  

```
SELECT * 
FROM "Orders" 
WHERE OrderID = 100

SELECT * 
FROM "Orders" 
WHERE OrderID = 100 and Address='some address'

SELECT * 
FROM "Orders" 
WHERE OrderID = 100 or OrderID = 200

SELECT * 
FROM "Orders" 
WHERE OrderID IN [100, 300, 234]
```
以下 `SELECT` 语句将导致完整表扫描：  

```
SELECT * 
FROM "Orders" 
WHERE OrderID > 1

SELECT * 
FROM "Orders" 
WHERE Address='some address'

SELECT * 
FROM "Orders" 
WHERE OrderID = 100 OR Address='some address'
```

***键***  
（可选）用于对返回结果进行排序的哈希键或排序键。默认顺序为升序 (`ASC`) 指定 `DESC` 如果您希望按降序重新调整结果。

**注意**  
如果省略 `WHERE` 子句，则检索表中的所有项目。

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

以下查询指定分区键 `OrderID`，并使用相等运算符，返回 `Orders` 表中的一个项目（如果存在）。

```
SELECT OrderID, Total
FROM "Orders"
WHERE OrderID = 1
```

以下查询使用 OR 运算符返回 `Orders` 表中具有特定分区键 `OrderID` 的所有项目。

```
SELECT OrderID, Total
FROM "Orders"
WHERE OrderID = 1 OR OrderID = 2
```

以下查询使用 IN 运算符返回 `Orders` 表中具有特定分区键 `OrderID` 的所有项目。返回的结果基于 `OrderID` 密钥属性值按降序排列。

```
SELECT OrderID, Total
FROM "Orders"
WHERE OrderID IN [1, 2, 3] ORDER BY OrderID DESC
```

以下查询显示一个全表扫描，返回 `Orders` 表中 `Total` 大于 500，`Total` 是非键属性的所有项目。

```
SELECT OrderID, Total 
FROM "Orders"
WHERE Total > 500
```

以下查询显示一个全表扫描，使用 IN 运算符和非键属性 `Total` 返回 `Orders` 表特定 `Total` 订单范围内的所有项目。

```
SELECT OrderID, Total 
FROM "Orders"
WHERE Total IN [500, 600]
```

以下查询显示一个全表扫描，使用 BETWEEN 运算符和非键属性 `Total` 返回 `Orders` 表特定 `Total` 订单范围内的所有项目。

```
SELECT OrderID, Total 
FROM "Orders" 
WHERE Total BETWEEN 500 AND 600
```

下面的查询在 WHERE 子句条件中指定分区键 `CustomerID` 和排序键 `MovieID`，在 SELECT 子句中使用完整文档路径，返回使用 firestick 设备观察的首个日期。

```
SELECT Devices.FireStick.DateWatched[0] 
FROM WatchList 
WHERE CustomerID= 'C1' AND MovieID= 'M1'
```

以下查询显示了一个完整表扫描，此扫描在 WHERE 子句条件中使用文档路径，返回 12/24/19 之后首次使用 firestick 设备的项目列表。

```
SELECT Devices 
FROM WatchList 
WHERE Devices.FireStick.DateWatched[0] >= '12/24/19'
```

# 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'
```

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

使用 `DELETE` 语句从 Amazon DynamoDB 表中删除现有项目。

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

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

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

```
DELETE FROM table 
 WHERE condition [RETURNING returnvalues]
 <returnvalues>  ::= ALL OLD *
```

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

***表*\$1**  
（必需）包含要删除的项目的 DynamoDB 表。

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

***returnvalues***  
（可选）如果要获得删除前的项目属性，请使用 `returnvalues`。有效值为：  
+ `ALL OLD *` - 返回旧项目的内容。

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

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

**注意**  
如果 DynamoDB 表中没有任何与发出 DELETE 的项目的主键相同的项目，则返回 SUCCESS 并删除 0 个项目。如果表具有具有相同主键的项目，但 DELETE 语句的 WHERE 子句中的条件计算结果为 false，则返回 `ConditionalCheckFailedException`。

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

以下查询删除 `"Music"` 表中的一个项目。

```
DELETE FROM "Music" WHERE "Artist" = 'Acme Band' AND "SongTitle" = 'PartiQL Rocks'
```

您可以添加参数 `RETURNING ALL OLD *` 以返回已删除的数据。

```
DELETE FROM "Music" WHERE "Artist" = 'Acme Band' AND "SongTitle" = 'PartiQL Rocks' RETURNING ALL OLD *
```

`Delete` 语句现在返回以下内容：

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

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

使用 `INSERT` 语句向 Amazon DynamoDB 的表添加项目。

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

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

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

插入单个项目。

```
INSERT INTO table VALUE item
```

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

***表*\$1**  
（必需）要在其中插入数据的表。表必须已经存在。

***item***  
（必需）表示为 [PartiQL tuple](https://partiql.org/docs.html) 的有效 DynamoDB 项目。您必须仅指定*一个*项目，项目中的每个属性名称都区分大小写，并且可以用*单*引号 (`'...'`) 在 PartiQL 中表示。  
字符串值也用*单*引号 (`'...'`) 在 PartiQL 中表示。

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

此语句不返回任何值。

**注意**  
如果 DynamoDB 表中已具有与要插入项目的主键相同的项目，则返回 `DuplicateItemException`。

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

```
INSERT INTO "Music" value {'Artist' : 'Acme Band','SongTitle' : 'PartiQL Rocks'}
```