La acción UpdateItem actualiza un elemento existente o agrega uno nuevo a la tabla, si no existe ya. Es preciso proporcionar la clave del elemento que se desea actualizar. Asimismo, debe proporcionar una expresión de actualización que indique los atributos que se van a modificar y los valores que se les asignarán.
Una expresión de actualización especifica cómo UpdateItem modificará los atributos de un elemento; por ejemplo, estableciendo un valor escalar o eliminando elementos de una lista o un mapa.
A continuación se muestra un resumen de la sintaxis de las expresiones de actualización.
update-expression ::= [ SETaction[,action] ... ] [ REMOVEaction[,action] ...] [ ADDaction[,action] ... ] [ DELETEaction[,action] ...]
Una expresión de actualización consta de una o varias cláusulas. Cada cláusula comienza con una palabra clave SET, REMOVE, ADD o DELETE. Puede incluir cualquiera de estas cláusulas en una expresión de actualización, en cualquier orden. Sin embargo, cada palabra clave de acción solo puede aparecer una vez.
Cada cláusula contiene una o más acciones, separadas por comas. Cada acción representa una modificación de datos.
Los ejemplos que aparecen en esta sección se basan en el elemento ProductCatalog que se muestra en Uso de expresiones de proyección en DynamoDB.
En los temas siguientes se describen algunos casos de uso diferentes de la acción SET.
Temas
SET: modificación o adición de atributos de elemento
Utilice la acción SET en una expresión de actualización para agregar uno o varios atributos a un elemento. Si cualquiera de estos atributos ya existe, se sobrescribirá con los nuevos valores. Si desea evitar sobrescribir un atributo existente, puede utilizar SET con la función if_not_exists. La función if_not_exists es específica de la acción SET y solamente se puede utilizar en una expresión de actualización.
Cuando se utiliza SET para actualizar una entrada de lista, el contenido de esa entrada se sustituye por los nuevos datos que ha especificado. Si el componente no existe, SET adjunta el nuevo componente al final de la lista.
Si agrega varias entradas en una misma operación SET, las entradas se ordenan según su número.
También puede utilizar SET para sumar o restar un valor de un atributo de tipo Number. Para llevar a cabo varias acciones SET, debe separarlas por comas.
En el resumen de sintaxis siguiente:
-
El componente
pathes la ruta de documento del elemento. -
Un componente
operandpuede ser una ruta de documento a un elemento o una función.
set-action ::=path= value value ::=operand|operand'+'operand|operand'-'operandoperand ::=path| function function ::=if_not_exists (path, value)
Si el elemento no contiene un atributo en la ruta especificada, if_not_exists se evalúa en value. De lo contrario, se evalúa como path.
La siguiente operación PutItem crea un elemento de muestra al que se refieren los ejemplos.
aws dynamodb put-item \ --table-name ProductCatalog \ --item file://item.json
Los argumentos de --item se almacenan en el archivo item.json. Para simplificar, se utilizan tan solo algunos de los atributos de elementos.
{
"Id": {"N": "789"},
"ProductCategory": {"S": "Home Improvement"},
"Price": {"N": "52"},
"InStock": {"BOOL": true},
"Brand": {"S": "Acme"}
}Temas
Modificación de atributos
ejemplo
Actualice los atributos ProductCategory y 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
Los argumentos de --expression-attribute-values se almacenan en el archivo values.json.
{
":c": { "S": "Hardware" },
":p": { "N": "60" }
}nota
En la operación UpdateItem, --return-values ALL_NEW hace que DynamoDB devuelva el elemento tal y como aparece después de la actualización.
Adición de listas y mapas
ejemplo
Agregue una lista y un mapa nuevos.
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
Los argumentos de --expression-attribute-values se almacenan en el archivo values.json.
{
":ri": {
"L": [
{ "S": "Hammer" }
]
},
":pr": {
"M": {
"FiveStar": {
"L": [
{ "S": "Best product ever!" }
]
}
}
}
}Adición de elementos a una lista
ejemplo
Agregue un nuevo atributo a la lista RelatedItems. Recuerde que las entradas de lista están basadas en cero; es decir, [0] representa la primera entrada de la lista, [1] representa la segunda, y así sucesivamente.
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
Los argumentos de --expression-attribute-values se almacenan en el archivo values.json.
{
":ri": { "S": "Nails" }
}nota
Cuando se utiliza SET para actualizar una entrada de lista, el contenido de esa entrada se sustituye por los nuevos datos que ha especificado. Si el componente no existe, SET adjunta el nuevo componente al final de la lista.
Si agrega varias entradas en una misma operación SET, las entradas se ordenan según su número.
Adición de atributos de mapa anidados
ejemplo
Agregue algunos atributos de mapa anidados.
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
Los argumentos de --expression-attribute-names se almacenan en el archivo names.json.
{
"#pr": "ProductReviews",
"#5star": "FiveStar",
"#3star": "ThreeStar"
}Los argumentos de --expression-attribute-values se almacenan en el archivo values.json.
{
":r5": { "S": "Very happy with my purchase" },
":r3": {
"L": [
{ "S": "Just OK - not that great" }
]
}
}Aumento y reducción de atributos numéricos
Puede sumar o restar un valor a un atributo numérico. Para ello, se utilizan los operadores + (más) y - (menos).
ejemplo
Reduzca el Price de un elemento.
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
Para aumentar el valor de Price, se utiliza el operador + en la expresión de actualización.
Adición de elementos a una lista
Puede agregar componentes al final de una lista. Para ello, se utiliza SET con la función list_append. (El nombre de la función distingue entre mayúsculas y minúsculas). La función list_append es específica de la acción SET y solamente se puede utilizar en una expresión de actualización. La sintaxis es la siguiente.
-
list_append (list1,list2)
La función toma dos listas como entrada y anexa todos los elementos de list2
.list1
ejemplo
En Adición de elementos a una lista, ha creado la lista RelatedItems y ha incluido en ella dos componentes: Hammer y Nails. Ahora, va a agregar dos componentes más al final de 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
Los argumentos de --expression-attribute-values se almacenan en el archivo values.json.
{
":vals": {
"L": [
{ "S": "Screwdriver" },
{"S": "Hacksaw" }
]
}
}Por último, vamos a agregar un componente más al principio de RelatedItems. Para ello, invierta el orden de los componentes de list_append. (Recuerde que list_append toma dos listas como información de entrada y agrega la segunda lista a la primera).
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
Ahora, el atributo RelatedItems resultante contiene cinco entradas, el siguiente orden: Chisel, Hammer, Nails, Screwdriver y Hacksaw.
Cómo evitar sobrescribir un atributo existente
ejemplo
Establezca el valor de Price de un elemento, pero solo si este no tiene ya un atributo Price. (Si Price ya existe, no sucede nada).
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: eliminación de atributos de un elemento
Utilice la acción REMOVE en una expresión de actualización para eliminar uno o varios atributos de un elemento en Amazon DynamoDB. Para llevar a cabo varias acciones REMOVE, debe separarlas por comas.
A continuación se muestra un resumen de la sintaxis de REMOVE en una expresión de actualización. El único operando es la ruta de documento del atributo que se desea eliminar.
remove-action ::=path
ejemplo
Elimine algunos atributos de un elemento. (Si el atributo no existe, no sucede nada).
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "REMOVE Brand, InStock, QuantityOnHand" \ --return-values ALL_NEW
Eliminación de elementos de una lista
Puede utilizar REMOVE para eliminar entradas individuales de una lista.
ejemplo
En Adición de elementos a una lista, ha modificado un atributo de lista (RelatedItems) para que contenga cinco componentes:
-
[0]—Chisel -
[1]—Hammer -
[2]—Nails -
[3]—Screwdriver -
[4]—Hacksaw
En el siguiente ejemplo de la AWS Command Line Interface (AWS CLI) se eliminan Hammer y Nails de la lista.
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "REMOVE RelatedItems[1], RelatedItems[2]" \ --return-values ALL_NEW
Después de eliminar Hammer y Nails, los componentes restantes se reordenan. Ahora, la lista contiene lo siguiente:
-
[0]—Chisel -
[1]—Screwdriver -
[2]—Hacksaw
ADD: actualización de números y conjuntos
nota
En general, recomendamos utilizar SET en lugar de ADD.
Utilice la acción ADD en una expresión de actualización para agregar un nuevo atributo y sus valores a un elemento.
Si el atributo ya existe, el comportamiento de ADD depende del tipo de datos del atributo:
-
Si el atributo es un número y el valor que se agrega también es un número, entonces el valor se suma matemáticamente al atributo existente. (Si el valor es un número negativo, entonces se resta del atributo existente).
-
Si el atributo es un conjunto y el valor que se agrega también es un conjunto, entonces el valor se agrega al conjunto existente.
nota
La acción ADD solo es compatible con los tipos de datos Number y Set.
Para llevar a cabo varias acciones ADD, debe separarlas por comas.
En el resumen de sintaxis siguiente:
-
El componente
pathes la ruta de documento de un atributo. El tipo de datos del atributo debe serNumbero Set. -
El componente
valuees un número que se desea agregar al atributo (si el tipo de datos esNumber) o un conjunto que se desea agregar al atributo (si el tipo de datos es Set).
add-action ::=pathvalue
En los temas siguientes se describen algunos casos de uso diferentes de la acción ADD.
Adición de un número
Supongamos que el atributo QuantityOnHand no existe. En el siguiente ejemplo de la AWS CLI, QuantityOnHand se establece en 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
Ahora que QuantityOnHand ya existe, puede volver a ejecutar el ejemplo para incrementar QuantityOnHand en 5 cada vez.
Adición de elementos a un conjunto
Supongamos que el atributo Color no existe. En el siguiente ejemplo de la AWS CLI, Color se establece en un conjunto de cadenas que contiene dos componentes.
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
Ahora que Color ya existe, podemos agregarle más componentes.
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: eliminación de elementos de un conjunto
importante
La acción DELETE solo es compatible con tipos de datos Set.
Utilice la acción DELETE en una expresión de actualización para eliminar una o varias entradas de un conjunto. Para llevar a cabo varias acciones DELETE, debe separarlas por comas.
En el resumen de sintaxis siguiente:
-
El componente
pathes la ruta de documento de un atributo. El tipo de datos del atributo debe ser Set. -
Subsetrepresenta uno o varios componentes que se van a eliminar depath. Parasubsetdebe especificar un tipo de datos Set.
delete-action ::=pathsubset
ejemplo
En Adición de elementos a un conjunto, crea el conjunto de cadenas Color. En este ejemplo se eliminan algunos de los componentes de ese conjunto.
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
Uso de varias expresiones de actualización
Puede utilizar varias expresiones de actualización en una instrucción.
Si desea modificar el valor de un atributo y eliminar por completo otro, podría utilizar una acción SET y otra REMOVE en una sola instrucción. Esta operación reduciría el valor de Price a 15 a la vez que eliminaría el atributo InStock del elemento.
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
Si desea agregar un elemento a una lista al mismo tiempo que cambia el valor de otro atributo, podría utilizar dos acciones SET en una sola instrucción. Esta operación agregaría "Nails" al atributo de la lista RelatedItems y también establecería el valor de Price a 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
