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

# 適用於 DynamoDB 的 PartiQL 陳述式
<a name="ql-reference.statements"></a>

Amazon DynamoDB 支援下列 PartiQL 陳述式。

**注意**  
DynamoDB 不支援所有 PartiQL 陳述式。  
此參考提供使用 AWS CLI 或 APIs 手動執行之 PartiQL 陳述式的基本語法和使用範例。

*資料操作語言* (DML) 是一組用來管理 DynamoDB 資料表中資料的 PartiQL 陳述式。您可使用 DML 陳述式新增、修改或刪除資料表中的資料。

支援下列 DML 和查詢語言陳述式：
+ [適用於 DynamoDB 的 PartiQL Select 陳述式](ql-reference.select.md)
+ [適用於 DynamoDB 的 PartiQL Update 陳述式](ql-reference.update.md)
+ [適用於 DynamoDB 的 PartiQL Insert 陳述式](ql-reference.insert.md)
+ [適用於 DynamoDB 的 PartiQL Delete 陳述式](ql-reference.delete.md)

DynamoDB 專用 PartiQL 亦支援 [使用 DynamoDB 專用 PartiQL 執行交易](ql-reference.multiplestatements.transactions.md) 和 [使用 DynamoDB 專用 PartiQL 執行批次操作](ql-reference.multiplestatements.batching.md)。

# 適用於 DynamoDB 的 PartiQL Select 陳述式
<a name="ql-reference.select"></a>

在 Amazon DynamoDB 中，使用 `SELECT` 陳述式從資料表檢索資料。

如果 WHERE 子句中未提供與分割區索引鍵相等或 IN 條件，使用 `SELECT` 陳述式可能會導致完整的資料表掃描。掃描操作會檢查每個項目的要求值，並可能會在單一操作中耗用大型資料表或索引的佈建輸送量。

如果您想避免在 PartiQL 中進行完整的資料表掃描，則可以：
+ 確保 [WHERE 子句條件](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html#ql-reference.select.parameters)會據此進行相應設定，撰寫您的 `SELECT` 陳述式便不會導致完整的資料表掃描。
+ 請使用《DynamoDB 開發人員指南》中 [範例：允許在 DynamoDB 專用 PartiQL 中執行選取陳述式並拒絕完整的資料表掃描陳述式](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)
+ [Parameters](#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] , ...]
```

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

***表達式***  
(必要) 從 `*` 萬用字元形成的投影，或來自結果集中一或多個屬性名稱或文件路徑的投影清單。一個表達式可以包含對 [搭配 DynamoDB 使用 PartiQL 函數](ql-functions.md) 的呼叫或由 [適用於 DynamoDB 的 PartiQL 算術、比較和邏輯運算子](ql-operators.md) 修改的欄位。

***資料表***  
(必要) 要查詢的資料表名稱。

***索引***  
(選用) 要查詢的索引名稱。  
查詢索引時，必須在資料表名稱和索引名稱上加上雙引號。  

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

***condition***  
(選用) 查詢的選取條件。  
若要確保 `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
```

下列查詢會針對具有特定分割區索引鍵、`OrderID` 和值的 `Orders` 資料表，使用 OR 運算子傳回其中的所有項目。

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

下列查詢會針對具有特定分割區索引鍵、`OrderID` 和值的 `Orders` 資料表，使用 IN 運算子傳回其中的所有項目。傳回的結果會根據 `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` 之特定 `Total` 順序範圍內 `Orders` 資料表中的所有項目。

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

下列查詢顯示完整的資料表掃描，該掃描會傳回使用 BETWEEN 運算子和非索引鍵屬性 `Total` 之特定 `Total` 順序範圍內 `Orders` 資料表中的所有項目。

```
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 子句條件中的文件路徑傳回在 2019 年 12 月 24 日之後首次使用 FireStick 裝置的項目清單。

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

# 適用於 DynamoDB 的 PartiQL Update 陳述式
<a name="ql-reference.update"></a>

使用 `UPDATE` 陳述式來修改 Amazon DynamoDB 資料表中項目內一或多個屬性的值。

**注意**  
您一次只能更新一個項目，因為您無法發出可刪除多個項目的單個 DynamoDB PartiQL 陳述式。如需更新多個項目的相關資訊，請參閱 [使用 DynamoDB 專用 PartiQL 執行交易](ql-reference.multiplestatements.transactions.md) 或 [使用 DynamoDB 專用 PartiQL 執行批次操作](ql-reference.multiplestatements.batching.md)。

**Topics**
+ [語法](#ql-reference.update.syntax)
+ [Parameters](#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] *
```

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

***資料表***  
(必要) 包含要修改之資料的資料表。

***路徑***  
(必要) 要建立或修改的屬性名稱或文件路徑。

***資料***  
(必要) 屬性值或操作的結果。  
與 SET 搭配使用的支援操作：  
+ LIST\$1APPEND：將數值新增至清單類型。
+ SET\$1ADD：將數值新增至數字或字串集。
+ SET\$1DELETE：從數字或字串集中刪除數值。

***condition***  
(必要) 要修改之項目的選取條件。此條件必須解析為單一主索引鍵值。

***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>

更新現有項目中的屬性值。如果屬性不存在，則會建立此屬性。

下列查詢會透過新增數字類型的屬性 (`AwardsWon`) 和映射類型的屬性 (`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'
```

# 適用於 DynamoDB 的 PartiQL Delete 陳述式
<a name="ql-reference.delete"></a>

使用 `DELETE` 陳述式從您的 Amazon DynamoDB 資料表中刪除現有項目。

**注意**  
您一次只能刪除一個項目。您無法發出可刪除多個項目的單個 DynamoDB PartiQL 陳述式。如需刪除多個項目的相關資訊，請參閱 [使用 DynamoDB 專用 PartiQL 執行交易](ql-reference.multiplestatements.transactions.md) 或 [使用 DynamoDB 專用 PartiQL 執行批次操作](ql-reference.multiplestatements.batching.md)。

**Topics**
+ [語法](#ql-reference.delete.syntax)
+ [Parameters](#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 *
```

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

***資料表***  
(必要) 包含要刪除之項目的 DynamoDB 資料表。

***condition***  
(必要) 要刪除之項目的選取條件；此條件必須解析為單一主索引鍵值。

***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"
            }
        }
    ]
}
```

# 適用於 DynamoDB 的 PartiQL Insert 陳述式
<a name="ql-reference.insert"></a>

使用 `INSERT` 陳述式在 Amazon DynamoDB 中將項目新增至資料表。

**注意**  
您一次只能插入一個項目，因為您無法發出可插入多個項目的單個 DynamoDB PartiQL 陳述式。如需插入多個項目的相關資訊，請參閱 [使用 DynamoDB 專用 PartiQL 執行交易](ql-reference.multiplestatements.transactions.md) 或 [使用 DynamoDB 專用 PartiQL 執行批次操作](ql-reference.multiplestatements.batching.md)。

**Topics**
+ [語法](#ql-reference.insert.syntax)
+ [Parameters](#ql-reference.insert.parameters)
+ [傳回值](#ql-reference.insert.return)
+ [範例](#ql-reference.insert.examples)

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

插入單一項目。

```
INSERT INTO table VALUE item
```

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

***資料表***  
(必要) 您要插入資料的資料表。索資料表必須已存在。

***項目***  
(必要) 有效的 DynamoDB 項目表示為 [PartiQL 元組](https://partiql.org/docs.html)。您必須在 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'}
```