Create, update, and delete application data

In this guide, you will learn how to create, update, and delete your data using Amplify Libraries' Data client.

Before you begin, you will need:

An application connected to the API

Create an item

You can create an item by first generating the Data client with your backend Data schema. Then you can add an item:

1import { generateClient } from 'aws-amplify/data';
2import { type Schema } from '@/amplify/data/resource'
3
4const client = generateClient<Schema>();
5
6const { errors, data: newTodo } = await client.models.Todo.create({
7  content: "My new todo",
8  done: true,
9})

Note: You do not need to specify createdAt or updatedAt fields because Amplify automatically populates these fields for you.

Update an item

To update the item, use the update function:

1import { generateClient } from 'aws-amplify/data';
2import { type Schema } from '@/amplify/data/resource'
3
4const client = generateClient<Schema>();
5
6const todoDetails = {
7  id: 'some_id',
8  description: 'Updated description'
9};
10
11const { data: updatedTodo, errors } = await client.models.Todo.update(todo)

Notes:

You do not need to specify the updatedAt field. Amplify will automatically populate this field for you.
If you specify extra input fields not expected by the API, this query will fail. You can see this in the errors field returned by the query. With Amplify Data, errors are not thrown like exceptions. Instead, any errors are captured and returned as part of the query result in the errors field.

Delete an item

You can then delete the Todo by using the delete mutation. To specify which item to delete, you only need to provide the id of that item:

1import { generateClient } from 'aws-amplify/data';
2import { type Schema } from '@/amplify/data/resource'
3
4const client = generateClient<Schema>();
5
6const toBeDeletedTodo = {
7  id: "123123213"
8}
9
10const { data: deletedTodo, errors } = await client.models.Todo.delete(toBeDeletedTodo)

Note: When deleting items in many-to-many relationships, the join table records must be deleted before deleting the associated records. For example, for a many-to-many relationship between Posts and Tags, delete the PostTags join record before deleting a Post or Tag. Review Many-to-many relationships for more details.

Troubleshooting

Troubleshoot unauthorized errors

Each API request uses an authorization mode. If you get unauthorized errors, you may need to update your authorization mode. To override the default authorization mode defined in your amplify/data/resource.ts file, pass an authMode property to the request or the client. The following examples show how you can mutate data with a custom authorization mode:

1import { generateClient } from 'aws-amplify/data';
2import { type Schema } from '@/amplify/data/resource';
3
4const client = generateClient<Schema>();
5
6const { errors, data: newTodo } = await client.models.Todo.create(
7  {
8    content: 'My new todo',
9    done: true
10  },
11  {
12    authMode: 'apiKey'
13  }
14);

Cancel create, update, and delete requests

You can cancel any mutation API request by calling .cancel on the mutation request promise that's returned by .create(...), .update(...), or .delete(...).

1const promise = client.models.Todo.create({ content: "New Todo "})
2            //  ^ Note: we're not awaiting the request, we're returning the promise
3
4try {
5  await promise;
6} catch (error) {
7  console.log(error);
8  // If the error is because the request was cancelled you can confirm here.
9  if (client.isCancelError(error)) {
10    console.log(error.message); // "my message for cancellation"
11    // handle user cancellation logic
12  }
13}
14
15...
16
17// To cancel the above request
18client.cancel(promise, "my message for cancellation");

You need to ensure that the promise returned from .create(), .update(), and .delete() has not been modified. Typically, async functions wrap the promise being returned into another promise. For example, the following will not work:

1async function makeAPICall() {
2  return client.models.Todo.create({ content: 'New Todo' });
3}
4const promise = makeAPICall();
5
6// The following will NOT cancel the request.
7client.cancel(promise, 'my error message');

Conclusion

Congratulations! You have finished the Create, update, and delete application data guide. In this guide, you created, updated, and deleted your app data.

Next steps

Our recommended next steps include using the API to query data and subscribe to real-time events to look for mutations in your data. Some resources that will help with this work include: