# DynamoDB 用の PartiQL ステートメント
<a name="ql-reference.statements"></a>

Amazon DynamoDB は、次の PartiQL ステートメントをサポートしています。

**注記**  
DynamoDB はすべての PartiQL ステートメントをサポートしているわけではありません。  
このリファレンスでは、AWS CLI シェルまたは API で手動で実行する PartiQL ステートメントについて、ベーシックな構文と使用例を示します。

*データ操作言語* (DML) は、DynamoDB テーブル内のデータを管理するために使用する、PartiQL ステートメントのセットです。DML ステートメントを使用して、テーブル内のデータを追加、変更、または削除します。

次の DML ステートメントとクエリ言語ステートメントがサポートされています。
+ [DynamoDB 用の PartiQL select ステートメント](ql-reference.select.md)
+ [DynamoDB 用の PartiQL 更新ステートメント](ql-reference.update.md)
+ [DynamoDB 用の PartiQL 挿入ステートメント](ql-reference.insert.md)
+ [DynamoDB 用の PartiQL 削除ステートメント](ql-reference.delete.md)

[DynamoDB 用の PartiQL を使用してトランザクションを実行する](ql-reference.multiplestatements.transactions.md) および [DynamoDB 用の PartiQL を使用してバッチ操作を実行する](ql-reference.multiplestatements.batching.md) は、DynamoDB 用の PartiQL でもサポートされています。

# DynamoDB 用の PartiQL select ステートメント
<a name="ql-reference.select"></a>

Amazon DynamoDB では、`SELECT` ステートメントを使用して、テーブルからデータを取得します。

`SELECT` ステートメントを使用すると、パーティションキーを持つ等価条件または IN 条件が WHERE 句で指定されていない場合、完全なテーブルスキャンになることがあります。スキャンオペレーションは、すべての項目でリクエストされた値を調べるので、大きなテーブルまたはインデックスに対してプロビジョニングされたスループットを 1 回のオペレーションで使い果たすことがあります。

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)
+ [パラメータ](#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***  
(必須) `*` ワイルドカードからの射影、または結果セットからの 1 つ以上の属性名かドキュメントパスの射影リスト。式には、[DynamoDB での PartiQL 関数の使用](ql-functions.md) への呼び出し、または [DynamoDB での PartiQL 算術演算子、比較演算子、論理演算子](ql-operators.md) によって変更されたフィールドで構成できます。

***テーブル*\$1**  
(必須) クエリするテーブル名。

*** インデックス***  
(オプション) クエリを実行するインデックスの名前です。  
インデックスにクエリを実行するときは、テーブル名とインデックス名に二重引用符を追加する必要があります。  

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

***condition***  
(オプション) クエリの選択条件。  
`SELECT` ステートメントによって、完全なテーブルスキャンが行われないようにするには、`WHERE` 句の条件がパーティションキーを指定する必要があります。等価演算子または IN 演算子を使用します。  
例えば、`OrderID` パーティションキーと、`Address` を含むその他の非キー属性がある `Orders` テーブルがある場合、次のステートメントは完全なテーブルスキャンを実行しません。  

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

***key***  
(任意) 返ってきた結果の並び替えに使用するハッシュキーまたはソートキー。デフォルトの順序は昇順 (`ASC`) です。返ってきた結果を降順に並べる場合は、`DESC` を指定します。

**注記**  
`WHERE` 句を省略すると、テーブル内のすべての項目が取得されます。

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

次のクエリは、`Orders` テーブルでパーティションキーと `OrderID` を指定し、等価演算子を使用することで、存在する場合に項目を 1 つ返します。

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

次のクエリは、OR 演算子を使用することで、特定のパーティションキーと `OrderID`、値を持つ `Orders` テーブルから、すべての項目を返します。

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

次のクエリは、IN 演算子を使用することで、特定のパーティションキーと `OrderID`、値を持つ `Orders` テーブルから、すべての項目を返します。返ってきた結果は、`OrderID` キー属性の値によって、降順に並べられます。

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

次のクエリは、`Total` が非キー属性である場合に、`Total` が 500 以上である `Orders` テーブルからすべての項目を返す、完全なテーブルスキャンを示します。

```
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 更新ステートメント
<a name="ql-reference.update"></a>

`UPDATE` ステートメントを使用して、Amazon DynamoDB テーブルの項目内にある、1 つ以上の属性の値を変更します。

**注記**  
一度に更新できる項目は 1 つだけです。1 つの DynamoDB PartiQL ステートメントを発行して、複数の項目を更新することはできません。複数項目の更新については、「[DynamoDB 用の PartiQL を使用してトランザクションを実行する](ql-reference.multiplestatements.transactions.md)」または「[DynamoDB 用の PartiQL を使用してバッチ操作を実行する](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**  
(必須) 修正されるデータを含んでいるテーブル。

***パス***  
(必須) 作成または変更される属性名、またはドキュメントパス。

***data***  
(必須) 属性値またはオペレーションの結果。  
SET で使用するためにサポートされている操作は、次の通りです。  
+ LIST\$1APPEND: List 型に値を追加します。
+ SET\$1ADD: 数値または文字列セットに値を追加します。
+ SET\$1DELETE: 数値または文字列セットから値を削除します。

***condition***  
(必須) 修正される項目の選択条件。この条件は、単一のプライマリキー値を解決する必要があります。

***returnvalues***  
(オプション) 属性が更新される前か、更新された後に、表示された項目の属性を取得したい場合に、`returnvalues` を使用します。有効な値は以下のとおりです。  
+ `ALL OLD *`: 更新操作の前に表示されていた項目について、すべての属性を返します。
+ `MODIFIED OLD *`: 更新操作の前に表示されていた属性について、更新された属性だけを返します。
+ `ALL NEW *`: 更新操作の後に表示される項目について、すべての属性を返します。
+ `MODIFIED NEW *`: `UpdateItem` 操作の後に表示される属性について、更新された属性だけを返します。

## 戻り値
<a name="ql-reference.update.return"></a>

`returnvalues` パラメータが指定されない限り、このステートメントは値を返しません。

**注記**  
UPDATE ステートメントの WHERE 句が、DynamoDB テーブルのどの項目も 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"
            }
        }
    ]
}
```

次のクエリは、`"Music"` テーブルの項目を、`AwardDetail.Grammys` リストに追加して更新します。

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

次のクエリは、`"Music"` テーブルの項目を、`AwardDetail.Grammys` リストから削除して更新します。

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

次のクエリは、`"Music"` テーブルで `AwardDetail` マップに `BillBoard` を追加して、項目を更新します。

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

次のクエリは、`"Music"` テーブルで、文字列セットの属性 `BandMembers` を追加して、項目を更新します。

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

次のクエリは、`"Music"` テーブルで文字列セットの属性 `BandMembers` に `newbandmember` を追加して、項目を更新します。

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

# DynamoDB 用の PartiQL 削除ステートメント
<a name="ql-reference.delete"></a>

`DELETE` ステートメントを使用して、Amazon DynamoDB テーブルにある項目を削除します。

**注記**  
一度に削除できる項目は 1 つだけです。1 つの DynamoDB PartiQL ステートメントを発行して、複数の項目を削除することはできません。複数のアイテムの削除については、「[DynamoDB 用の PartiQL を使用してトランザクションを実行する](ql-reference.multiplestatements.transactions.md)」または「[DynamoDB 用の PartiQL を使用してバッチ操作を実行する](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 テーブル。

***condition***  
(必須) 削除する項目の選択基準。この条件は、単一のプライマリキー値を解決する必要があります。

***returnvalues***  
(オプション) 削除される前に表示された、項目の属性を取得したい場合には、`returnvalues` を使用します。有効な値は以下のとおりです。  
+ `ALL OLD *`: 古い項目の内容が返されます。

## 戻り値
<a name="ql-reference.delete.return"></a>

`returnvalues` パラメータが指定されない限り、このステートメントは値を返しません。

**注記**  
DynamoDB テーブルに、DELETE が発行された項目と同じプライマリキーを持つ項目が無い場合、削除した項目を 0 としたうえで、SUCCESS を返します。テーブルに同じプライマリキーを持つ項目があるが、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 挿入ステートメント
<a name="ql-reference.insert"></a>

`INSERT` ステートメントを使用して、Amazon DynamoDB のテーブルに項目を追加します。

**注記**  
一度に挿入できる項目は 1 つだけです。1 つの DynamoDB PartiQL ステートメントを発行して、複数の項目を挿入することはできません。複数の項目の挿入については、「[DynamoDB 用の PartiQL を使用してトランザクションを実行する](ql-reference.multiplestatements.transactions.md)」または「[DynamoDB 用の PartiQL を使用してバッチ操作を実行する](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>

項目を 1 つ挿入します。

```
INSERT INTO table VALUE item
```

## パラメータ
<a name="ql-reference.insert.parameters"></a>

***テーブル*\$1**  
(必須) データを挿入するテーブル。このテーブルは既存であることが必要です。

***item***  
(必須) 有効な DynamoDB 項目は [PartiQL タプル](https://partiql.org/docs.html)。*1 つ*の項目のみ指定する必要があります。また、項目の各属性名は大文字と小文字が区別され、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'}
```