Update

Use the Update command to modify a single item in DynamoDB. This is the Document Builder command for a UpdateItem operation.

Basic Usage

Update an item by primary key.

const todoListEntity = new DynamoEntity({
  table: parentTable,
  schema: z.object({
    todoListId: z.string(),
    userId: z.string(),
    title: z.string(),
    todos: z.array(z.string()),
  }),
  partitionKey: todo => key('USER', todo.userId),
  sortKey: todo => key('TODO_LIST', todo.todoListId),
});

const updateCommand = new Update({
  key: {
    userId: '123',
    todoListId: '456',
  },
  updates: {
    title: 'Todays To-dos',
    todos: append([
      'Do the dishes',
      'Walk the dog',
    ]),
  },
});

await todoListEntity.send(updateCommand);

In the example above, we update the title attribute to a new value and append two new items to the todos list attribute.

Update Operations

Document Builder provides a simple and expressive API for building the underlying DynamoDB UpdateExpression. Not only does it handle the construction of the underlying update expression itself, but also the accompanying ExpressionAttributeNames and ExpressionAttributeValues as well.

Update a single attribute

Updating a single attribute to a new value is as simple as providing the attribute name and the new value in the update object.

new Update({
  key: {
    PK: '123',
    SK: '456',
  },
  update: {
    myAttribute: 'new value',
  },
});

This would build the following UpdateItem operation:

{
  Key: {
    PK: '123',
    SK: '456',
  },
  UpdateExpression: 'SET #myAttribute = :myAttribute',
  ExpressionAttributeNames: {
    '#myAttribute': 'myAttribute',
  },
  ExpressionAttributeValues: {
    ':myAttribute': 'new value',
  }
}

Update multiple attributes

Update multiple attributes by providing multiple key-value pairs in the update object.

new Update({
  key: {
    PK: '123',
    SK: '456',
  },
  update: {
    attributeOne: 'new value one',
    attributeTwo: 42,
    attributeThree: false,
  },
});

Update nested attributes

To update nested attributes, use dot notation to specify the path to the nested attribute.

new Update({
  key: {
    PK: '123',
    SK: '456',
  },
  update: {
    'nested.attribute.one': 'new nested value',
    'nested.attribute.two': 100,
  },
});

Reference another attribute

If you want to set one attribute’s value to the value of another attribute, you can use the ref() function and pass it the attribute path.

new Update({
  key: {
    PK: '123',
    SK: '456',
  },
  update: {
    someAttribute: ref('anotherAttribute'),
  },
});

Reference another attribute with a default value

You can provide a default value to use in case the referenced attribute does not exist by passing a second argument to the ref() function.

new Update({
  key: {
    PK: '123',
    SK: '456',
  },
  update: {
    someAttribute: ref('anotherAttribute', 42),
  },
});

Reference another nested attribute

ref() also supports dot notation for referencing nested attributes.

new Update({
  key: {
    PK: '123',
    SK: '456',
  },
  update: {
    someAttribute: ref('nested.attribute.path'),
  },
});

Remove an attribute

If you want to remove an attribute from an item entirely, you can use the remove() function.

new Update({
  key: {
    PK: '123',
    SK: '456',
  },
  update: {
    obsoleteAttribute: remove(),
  },
});

Increment or decrement a numeric attribute

For numeric attributes, you can use the add() and subtract() functions to increment or decrement their values.

new Update({
  key: {
    PK: '123',
    SK: '456',
  },
  update: {
    counterAttribute: add(5),
    anotherCounter: subtract(3),
  },
});

Append or prepend to a List

If you have a List attribute, you can use the append() and prepend() functions to add items to the end or beginning of the list.

new Update({
  key: {
    PK: '123',
    SK: '456',
  },
  update: {
    myList: append(['new item at end']),
    anotherList: prepend(['new item at start']),
  },
});

Add a value to a Set

For Set attributes specifically, you can use the addToSet() function to add one or more values to the set.

new Update({
  key: {
    PK: '123',
    SK: '456',
  },
  update: {
    tags: addToSet(['newTag1', 'newTag2']),
  },
});

Remove a value from a Set

To remove one or more values from a Set attribute, you can use the removeFromSet() function.

new Update({
  key: {
    PK: '123',
    SK: '456',
  },
  update: {
    tags: removeFromSet(['tagToRemove1', 'tagToRemove2']),
  },
});

Returning the Updated Item

You can request that the update operation return the item’s attributes as they appear after the update operation. To do this, set the returnValues parameter in the command config.

const updateCommand = new Update({
  key: {
    userId: '123',
    todoListId: '456',
  },
  updates: {
    todos: append(['Walk the dog']),
  },
  returnValues: 'ALL_OLD',
});

const updateResult = await todoListEntity.send(updateCommand);
console.log(updateResult.updatedItem);

Conditional Updates

You can perform an update that only succeeds if certain conditions are met. To do this, use the ConditionalUpdate command and provide a condition in the command config.

const conditionalUpdate = new ConditionalUpdate({
  key: {
    userId: '123',
    todoListId: '456',
  },
  updates: {
    title: 'Updated To-dos',
  },
  condition: {
    title: 'Todays To-dos',
  },
});

await todoListEntity.send(conditionalUpdate);

In the above example, the update will only succeed if the existing title attribute is set to 'Todays To-dos'.

Tree-shakable Imports

import { Update } from 'dynamo-document-builder/commands/update';
import { ConditionalUpdate } from 'dynamo-document-builder/commands/conditional-update';

import { ref } from 'dynamo-document-builder/updates/ref';
import { remove } from 'dynamo-document-builder/updates/remove';
import { add } from 'dynamo-document-builder/updates/add';
import { subtract } from 'dynamo-document-builder/updates/subtract';
import { append } from 'dynamo-document-builder/updates/append';
import { prepend } from 'dynamo-document-builder/updates/prepend';
import { addToSet } from 'dynamo-document-builder/updates/add-to-set';
import { removeFromSet } from 'dynamo-document-builder/updates/remove-from-set';

API Reference

Commands

Update Operations