Usar expressões de atualização no DynamoDB - Amazon DynamoDB
SET: modificar ou adicionar atributos de um itemREMOVE: excluir atributos de um itemADD: atualizar números e conjuntosDELETE: remover elementos de um conjuntoUsar várias expressões de atualização

Usar expressões de atualização no DynamoDB

A ação UpdateItem atualiza um item existente ou adiciona um item novo à tabela, caso ele ainda não exista. Você deve fornecer a chave do item que deseja atualizar. Você também deve fornecer uma expressão de atualização indicando os atributos que deseja modificar e os valores que deseja atribuir a eles.

Uma expressão de atualização especifica como UpdateItem modificará os atributos de um item. Por exemplo, definindo um valor escalar ou removendo elementos de uma lista ou de um mapa.

Veja a seguir um resumo da sintaxe para expressões de atualização.

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

Uma expressão de atualização consiste em uma ou mais cláusulas. Cada cláusula começa com uma palavra-chave SET, REMOVE, ADD ou DELETE. Você pode incluir qualquer uma dessas cláusulas em uma expressão de atualização, em qualquer ordem. No entanto, cada palavra-chave de ação pode aparecer apenas uma vez.

Dentro de cada cláusula há uma ou mais ações, separadas por vírgulas. Cada ação representa uma modificação de dados.

Os exemplos desta seção se baseiam no item ProductCatalog mostrado em Usar expressões de projeção no DynamoDB.

Os tópicos abaixo abrangem alguns casos de uso diferentes da ação SET.

SET: modificar ou adicionar atributos de um item

Use a ação SET em uma expressão de atualização para adicionar um ou mais atributos a um item. Se qualquer um desses atributos já existir, eles serão substituídos pelos novos valores. Se você deseja evitar a substituição de um atributo, pode usar SET com if_not_exists function. A função if_not_exists é específica à ação SET e só pode ser usada em uma expressão de atualização.

Quando você usa SET para atualizar um elemento de lista, o conteúdo desse elemento é substituído pelos novos dados especificados. Se o elemento ainda não existir, SET acrescentará o novo elemento ao final da lista.

Se você adicionar vários elementos em uma única operação SET, estes serão classificados por número de elemento.

Você também pode usar SET para adicionar ou subtrair de um atributo do tipo Number. Para executar várias ações SET, separe-as com vírgulas.

No seguinte resumo de sintaxe:

  • O elemento path é o caminho do documento para o item.

  • Um elemento operando pode ser o caminho de um documento para um item ou uma função.

set-action ::=
    path = value

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

operand ::=
    path | function

function ::=
    if_not_exists (path)

Se o item não contiver um atributo no caminho especificado, if_not_exists será avaliado como value. Caso contrário, será avaliado como path.

A seguinte operação PutItem cria um item de exemplo ao qual os exemplos fazem referência.

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

Os argumentos de --item são armazenados no arquivo item.json. (Para simplificar, apenas alguns atributos de item são usados.)

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

Modificar atributos

exemplo

Atualize os atributos ProductCategory e 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

Os argumentos de --expression-attribute-values são armazenados no arquivo values.json.

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

Na operação UpdateItem, --return-values ALL_NEW faz com que o DynamoDB retorne o item como ele aparece após a atualização.

Adicionar listas e mapas

exemplo

Adicione uma nova lista e um novo mapa.

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

Os argumentos de --expression-attribute-values são armazenados no arquivo values.json.

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

Adicionar elementos a uma lista

exemplo

Adicione um novo atributo à lista RelatedItems. (Lembre-se de que elementos de lista são baseados em zero e, portanto, [0] representa o primeiro elemento da lista, [1] representa o segundo, e assim por diante.)

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

Os argumentos de --expression-attribute-values são armazenados no arquivo values.json.

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

Quando você usa SET para atualizar um elemento de lista, o conteúdo desse elemento é substituído pelos novos dados especificados. Se o elemento ainda não existir, SET acrescentará o novo elemento ao final da lista.

Se você adicionar vários elementos em uma única operação SET, estes serão classificados por número de elemento.

Adicionar atributos de mapa aninhados

exemplo

Adicione alguns atributos de mapa aninhados.

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

Os argumentos de --expression-attribute-names são armazenados no arquivo names.json.

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

Os argumentos de --expression-attribute-values são armazenados no arquivo values.json.

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

Incrementar e reduzir atributos numéricos

Você pode adicionar ou subtrair de um atributo numérico existente. Para fazer isso, use os operadores + (mais) e - (menos).

exemplo

Diminua o valor do Price de um item.

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 o valor do Price, você usa o operador + na expressão de atualização.

Acrescentar elementos a uma lista

É possível adicionar elementos ao final de uma lista. Para fazer isso, use SET com a função list_append. (O nome da função diferencia maiúsculas de minúsculas.) A função list_append é específica à ação SET e só pode ser usada em uma expressão de atualização. A sintaxe é a seguinte.

  • list_append (list1, list2)

A função utiliza duas listas como entrada e acrescenta todos os elementos de list2 a list1.

exemplo

Em Adicionar elementos a uma lista, você cria a lista RelatedItems e a preenche com dois elementos: Hammer e Nails. Na sequência, você acrescenta mais dois elementos ao 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

Os argumentos de --expression-attribute-values são armazenados no arquivo values.json.

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

Por fim, você acrescenta mais um elemento ao início de RelatedItems. Para fazer isso, alterne a ordem dos elementos de list_append. (Lembre-se de que list_append usa duas listas como entrada e acrescenta a segunda lista à primeira.)

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

Agora, o atributo RelatedItems resultante contém cinco elementos, na seguinte ordem: Chisel, Hammer, Nails, Screwdriver, Hacksaw.

Impedir substituições de um atributo existente

exemplo

Defina o Price de um item, mas somente se o item ainda não tiver um atributo Price. (Se o atributo Price já existir, não acontecerá 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: excluir atributos de um item

Use a ação REMOVE em uma expressão de atualização para remover um ou mais atributos de um item no Amazon DynamoDB. Para executar várias ações REMOVE, separe-as com vírgulas.

O seguinte é um resumo da sintaxe de REMOVE em uma expressão de atualização. O único operando é o caminho do documento do atributo que você deseja remover.

remove-action ::=
    path
exemplo

Remova alguns atributos de um item. (Se os atributos não existirem, nada acontecerá.)

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

Remover elementos de uma lista

É possível usar REMOVE para excluir elementos individuais de uma lista.

exemplo

Em Acrescentar elementos a uma lista, você modifica um atributo da lista (RelatedItems) de forma que ele contenha cinco elementos:

  • [0]—Chisel

  • [1]—Hammer

  • [2]—Nails

  • [3]—Screwdriver

  • [4]—Hacksaw

O exemplo da AWS Command Line Interface (AWS CLI) a seguir exclui Hammer e Nails da lista.

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

Depois que Hammer e Nails forem removidos, os elementos restantes serão deslocados. Agora, a lista contém o seguinte:

  • [0]—Chisel

  • [1]—Screwdriver

  • [2]—Hacksaw

ADD: atualizar números e conjuntos

nota

Em geral, recomendamos o uso de SET em vez de ADD.

Use a ação ADD em uma expressão de atualização para adicionar um novo atributo e seus valores a um item.

Se o atributo já existir, o comportamento de ADD dependerá do tipo de dados do atributo:

  • Se o atributo for um número, e o valor que você está adicionando também for um número, esse valor será matematicamente adicionado ao atributo existente. (Se o valor for um número negativo, ele será subtraído do atributo existente.)

  • Se o atributo for um conjunto, e o valor que você está adicionando também for um conjunto, esse valor será acrescentado ao conjunto existente.

nota

A ação ADD oferece suporte apenas a tipos de dados de número e conjunto.

Para executar várias ações ADD, separe-as com vírgulas.

No seguinte resumo de sintaxe:

  • O elemento path é o caminho do documento para um atributo. O atributo deve ser um Number ou um tipo de dados de conjunto.

  • O elemento value é um número que você deseja adicionar ao atributo (para tipos de dados Number) ou um conjunto a ser acrescentado ao atributo (para tipos de conjunto).

add-action ::=
    path value

Os tópicos abaixo abrangem alguns casos de uso diferentes da ação ADD.

Adicionar um número

Suponha que o atributo QuantityOnHand não exista. O exemplo da AWS CLI a seguir define QuantityOnHand como 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

Agora que QuantityOnHand existe, você pode executar novamente o exemplo para incrementar QuantityOnHand em 5 de cada vez.

Adicionar elementos a um conjunto

Suponha que o atributo Color não exista. O exemplo da AWS CLI a seguir define Color como um conjunto de strings com dois elementos.

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

Agora que Color existe, você pode adicionar mais elementos a ele.

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: remover elementos de um conjunto

Importante

A ação DELETE oferece suporte apenas a tipos de dados Set.

Use a ação DELETE em uma expressão de atualização para remover um ou mais elementos de um conjunto. Para executar várias ações DELETE, separe-as com vírgulas.

No seguinte resumo de sintaxe:

  • O elemento path é o caminho do documento para um atributo. Esse atributo deve ser um tipo de dados de conjunto.

  • O elemento subset é um ou mais elementos que você deseja excluir de path. Você deve especificar o elemento subset como um tipo set.

delete-action ::=
    path subset
exemplo

Em Adicionar elementos a um conjunto, você cria o conjunto de tipo string Color. Este exemplo remove alguns dos elementos desse 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

Usar várias expressões de atualização

É possível usar várias expressões de atualização em uma única declaração.

Se quiser modificar o valor de um atributo e remover outro completamente, você poderá usar uma ação SET e uma REMOVE em uma única declaração. Essa operação reduziria o valor de Price para 15 e, ao mesmo tempo, removeria o atributo InStock do item.

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

Se quiser adicionar a uma lista e, ao mesmo tempo, alterar o valor de outro atributo, você poderá usar duas ações SET em uma única declaração. Essa operação adicionaria “Unhas” ao atributo da lista RelatedItems e também definiria o valor de Price como 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