SET — 修改或新增項目屬性 REMOVE — 刪除項目中的屬性 ADD — 更新數字與集合 DELETE — 移除集合中的元素使用多個更新表達式

在 DynamoDB 中使用更新表達式

UpdateItem 操作會更新現有項目，如尚不存在，則會將新項目新增到資料表中。您必須提供要更新項目的索引鍵。您也必須提供更新表達式，指出您想要修改的屬性以及您想要指派給它們的值。

更新表達式會指定 UpdateItem 如何修改項目的屬性，例如設定純量值或將元素從清單或映射中刪除。

以下是更新表達式的語法摘要。


update-expression ::=
    [ SET action [, action] ... ]
    [ REMOVE action [, action] ...]
    [ ADD action [, action] ... ]
    [ DELETE action [, action] ...]

更新表達式包含一或多個子句。每個子句的開頭是 SET、REMOVE、ADD 或 DELETE 關鍵字。您可以依任意順序在更新表達式中包含其中任何子句。不過，每個動作關鍵字都只能出現一次。

在每個子句內，會有以逗號分隔的一或多個動作。每個動作都會代表資料修改。

本節中的範例是以在 DynamoDB 中使用投影表達式中所顯示的 ProductCatalog 項目為基礎。

以下主題涵蓋了 SET 動作的一些不同使用案例。

SET — 修改或新增項目屬性

在更新表達式中使用 SET 動作，將一或多個屬性新增至項目。這些屬性如已存在，每一個都會為新值所覆寫。如果您想要避免覆寫現有屬性，則可以搭配使用 SET 與 if_not_exists 函數。if_not_exists 函數為 SET 動作專有，而且只能用於更新表達式。

當您使用 SET 更新清單元素時，會將該元素的內容取代為您所指定的新資料。如果元素尚未存在，則 SET 會在清單結尾附加新的元素。

如果您在單一 SET 操作中新增多個元素，則會依元素號碼依序排序元素。

您也可以使用 SET 來加減類型為 Number 的屬性。若要執行多個 SET 動作，請使用逗號分隔它們。

在下列語法摘要中：

path 元素是項目的文件路徑。
operand 元素可以是項目或函數的文件路徑。


set-action ::=
    path = value

value ::=
    operand
    | operand '+' operand
    | operand '-' operand

operand ::=
    path | function

function ::=
    if_not_exists (path, value)

如果項目不包含指定路徑的屬性，會if_not_exists評估為 value。否則，它會評估為 path。

下列 PutItem 操作會建立範例參考的範例項目。


aws dynamodb put-item \
    --table-name ProductCatalog \
    --item file://item.json

--item 的引數會存放在 item.json 檔案中。(為求簡化，只會使用一些項目屬性)。


{
    "Id": {"N": "789"},
    "ProductCategory": {"S": "Home Improvement"},
    "Price": {"N": "52"},
    "InStock": {"BOOL": true},
    "Brand": {"S": "Acme"}
}

主題

修改屬性
新增清單和映射
將元素新增至清單
新增巢狀映射屬性
增加和減少數值屬性
將元素附加至清單
防止覆寫現有屬性

修改屬性

範例

更新 ProductCategory 和 Price 屬性。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET ProductCategory = :c, Price = :p" \
    --expression-attribute-values file://values.json \
    --return-values ALL_NEW

--expression-attribute-values 的引數會存放在 values.json 檔案中。


{
    ":c": { "S": "Hardware" },
    ":p": { "N": "60" }
}

注意

在 UpdateItem 操作中，--return-values ALL_NEW 會讓 DynamoDB 傳回在更新後所顯示的項目。

新增清單和映射

範例

新增清單和映射。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET RelatedItems = :ri, ProductReviews = :pr" \
    --expression-attribute-values file://values.json \
    --return-values ALL_NEW

--expression-attribute-values 的引數會存放在 values.json 檔案中。


{
    ":ri": {
        "L": [
            { "S": "Hammer" }
        ]
    },
    ":pr": {
        "M": {
            "FiveStar": {
                "L": [
                    { "S": "Best product ever!" }
                ]
            }
        }
    }
}

將元素新增至清單

範例

將新的屬性新增至 RelatedItems 清單。(請記住，清單元素的開頭為零，因此 [0] 代表清單中的第一個元素、[1] 代表第二個元素，以此類推)。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET RelatedItems[1] = :ri" \
    --expression-attribute-values file://values.json \
    --return-values ALL_NEW

--expression-attribute-values 的引數會存放在 values.json 檔案中。


{
    ":ri": { "S": "Nails" }
}

注意

當您使用 SET 更新清單元素時，會將該元素的內容取代為您所指定的新資料。如果元素尚未存在，則 SET 會在清單結尾附加新的元素。

如果您在單一 SET 操作中新增多個元素，則會依元素號碼依序排序元素。

新增巢狀映射屬性

範例

新增一些巢狀映射屬性。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET #pr.#5star[1] = :r5, #pr.#3star = :r3" \
    --expression-attribute-names file://names.json \
    --expression-attribute-values file://values.json \
    --return-values ALL_NEW

--expression-attribute-names 的引數會存放在 names.json 檔案中。


{
    "#pr": "ProductReviews",
    "#5star": "FiveStar",
    "#3star": "ThreeStar"
}

--expression-attribute-values 的引數會存放在 values.json 檔案中。


{
    ":r5": { "S": "Very happy with my purchase" },
    ":r3": {
        "L": [
            { "S": "Just OK - not that great" }
        ]
    }
}

增加和減少數值屬性

您可以新增或扣除現有數值屬性。若要執行此作業，請使用 + (加號) 和 - (減號) 運算子。

範例

減少項目的 Price。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET Price = Price - :p" \
    --expression-attribute-values '{":p": {"N":"15"}}' \
    --return-values ALL_NEW

若要增加 Price，您要在更新表達式中使用 + 運算子。

將元素附加至清單

您可以將元素新增至清單結尾。若要執行此作業，請搭配使用 SET 與 list_append 函數 (函數名稱區分大小寫。) list_append 函數為 SET 動作專有，而且只能用於更新表達式。語法如下。

list_append (list1, list2)

此函數需要兩個列表作為輸入，並將所有元素從 list2 附加到 list1。

範例

在將元素新增至清單中，您會建立 RelatedItems 清單，並使用兩個元素填入它：Hammer 和 Nails。現在，您可在 RelatedItems 結尾多附加兩個元素。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET #ri = list_append(#ri, :vals)" \
    --expression-attribute-names '{"#ri": "RelatedItems"}' \
    --expression-attribute-values file://values.json  \
    --return-values ALL_NEW

--expression-attribute-values 的引數會存放在 values.json 檔案中。


{
    ":vals": {
        "L": [
            { "S": "Screwdriver" },
            {"S": "Hacksaw" }
        ]
    }
}

最後，您將另一個元素附加到 RelatedItems 的開頭。若要執行此作業，請切換 list_append 元素的順序。(請記住，list_append 採用兩份清單做為輸入，並將第二份清單附加至第一份清單。)


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET #ri = list_append(:vals, #ri)" \
    --expression-attribute-names '{"#ri": "RelatedItems"}' \
    --expression-attribute-values '{":vals": {"L": [ { "S": "Chisel" }]}}' \
    --return-values ALL_NEW

產生的 RelatedItems 屬性現在會包含五個元素，順序如下：Chisel、Hammer、Nails、Screwdriver、Hacksaw。

防止覆寫現有屬性

範例

設定項目的 Price，但只有在項目還沒有 Price 屬性時。(如果 Price 已存在，則不會發生任何事。)


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET Price = if_not_exists(Price, :p)" \
    --expression-attribute-values '{":p": {"N": "100"}}' \
    --return-values ALL_NEW

REMOVE — 刪除項目中的屬性

在更新表達式中使用 REMOVE 動作，從而在 Amazon DynamoDB 中移除項目的一或多個屬性。若要執行多個 REMOVE 動作，請使用逗號分隔它們。

下列是更新表達式中 REMOVE 的語法摘要。唯一的運算元是您想要移除的屬性文件路徑。


remove-action ::=
    path

範例

移除項目中的一些屬性 (如果屬性不存在，則不會發生任何事。)


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "REMOVE Brand, InStock, QuantityOnHand" \
    --return-values ALL_NEW

移除清單中的元素

您可以使用 REMOVE 刪除清單中的個別元素。

範例

在將元素附加至清單中，您修改清單屬性 (RelatedItems)，讓它包含五個元素：

[0]—Chisel
[1]—Hammer
[2]—Nails
[3]—Screwdriver
[4]—Hacksaw

下列 AWS Command Line Interface (AWS CLI) 範例Nails會從清單中刪除 Hammer和。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "REMOVE RelatedItems[1], RelatedItems[2]" \
    --return-values ALL_NEW

移除 Hammer 和 Nails 之後，會轉移其餘的元素。此清單現在包含下列項目：

[0]—Chisel
[1]—Screwdriver
[2]—Hacksaw

ADD — 更新數字與集合

注意

一般而言，建議使用 SET，而非 ADD。

在更新表達式中使用 ADD 動作，將新的屬性及其值新增至項目。

如果屬性已存在，則 ADD 的行為取決於屬性的資料類型：

如果屬性是數字，而您要新增的值也是數字，則此值會以數學方式新增到現有屬性。(如果值是負數，則會從現有屬性減去。)
如果屬性是集合，而您要新增的值也是集合，則此值會附加至現有集合。

注意

ADD 動作只支援數字和集合資料類型。

若要執行多個 ADD 動作，請使用逗號分隔它們。

在下列語法摘要中：

path 元素是屬性的文件路徑。屬性必須是 Number 或集合資料類型。
value 元素是您要新增至屬性的數字 (針對 Number 資料類型)，或要附加至屬性的集合 (針對集合類型)。


add-action ::=
    path value

以下主題涵蓋了 ADD 動作的一些不同使用案例。

主題

新增數字
將元素新增至集合

新增數字

假設 QuantityOnHand 屬性不存在。下列 AWS CLI 範例QuantityOnHand將設定為 5。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "ADD QuantityOnHand :q" \
    --expression-attribute-values '{":q": {"N": "5"}}' \
    --return-values ALL_NEW

現在已有 QuantityOnHand，您可以重新執行範例，QuantityOnHand 每次的增量為 5。

將元素新增至集合

假設 Color 屬性不存在。下列 AWS CLI 範例會將 Color 設定為具有兩個元素的字串集。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "ADD Color :c" \
    --expression-attribute-values '{":c": {"SS":["Orange", "Purple"]}}' \
    --return-values ALL_NEW

現在已有 Color，您可以在其中新增更多元素。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "ADD Color :c" \
    --expression-attribute-values '{":c": {"SS":["Yellow", "Green", "Blue"]}}' \
    --return-values ALL_NEW

DELETE — 移除集合中的元素

重要

DELETE 動作僅支援 Set 資料類型。

在更新表達式中使用 DELETE 動作，移除集合中的一或多個元素。若要執行多個 DELETE 動作，請使用逗號分隔它們。

在下列語法摘要中：

path 元素是屬性的文件路徑。屬性必須是集合資料類型。
subset 是您要從 path 刪除的一或多個元素。您必須指定 subset 做為集合類型。


delete-action ::=
    path subset

範例

在將元素新增至集合中，您會建立 Color 字串集。本範例會從該集合中移除一些元素。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "DELETE Color :p" \
    --expression-attribute-values '{":p": {"SS": ["Yellow", "Purple"]}}' \
    --return-values ALL_NEW

使用多個更新表達式

您可以在單一陳述式中使用多個更新表達式。

如果您想要修改屬性的值並完全移除其他屬性，您可以在單一陳述式中使用 SET 和 REMOVE 動作。此操作會將 Price 值減少為 15，同時也會從項目中移除 InStock 屬性。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET Price = Price - :p REMOVE InStock" \
    --expression-attribute-values '{":p": {"N":"15"}}' \
    --return-values ALL_NEW

如果您想要新增至清單，同時變更其他屬性的值，您可以在單一陳述式中使用兩個 SET 動作。此操作會將「釘子」新增到 RelatedItems 清單屬性中，並將 Price 值設定為 21。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET RelatedItems[1] = :newValue, Price = :newPrice" \
    --expression-attribute-values '{":newValue": {"S":"Nails"}, ":newPrice": {"N":"21"}}'  \
    --return-values ALL_NEW

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

投射表達式

條件和篩選條件表達式