Skip to main content

Mutations

Mutations in Squid are powerful tools that can be applied on an instance of a DocumentReference and used for modifying the data of a document. They can be applied locally and reflect immediately, providing a fast and responsive user experience.​

Unless being run in a transaction, all mutations return a Promise which resolves once the mutation is applied on the server.

Tip

The backend security rules enable you to control who can perform each mutation in a granular way. These rules receive a MutationContext as a parameter, which contains all the needed details about the mutation including the snapshot of the document before and after the change. You can read more about security rules to understand how to write them.

Applying mutations​

Mutations are applied optimistically locally and reflect immediately on the client. The changes are then sent to the server asynchronously to ensure a consistent, clean data state.

There are three types of mutations: insert, delete, and update. Each is performed on a document reference. Recall that the .doc() method returns a document reference.

Note

The following examples use the built-in database. To tailor the examples to a different database integration, you must include the integration ID with the collection reference and your document ID must be an object. For example:

squid
  .collection<User>('users', 'my_integration_id')
  .doc({ userId: 'new_user_id' });

For more information, see the documentation on Collection references and Document IDs.

Insert​

Insert is used for creating a new document. To insert a new document into a collection, you can call the insert method on a DocumentReference and pass in the new document data as an argument. Here is an example:

Client code
squid
  .collection<User>('users')
  .doc('new_user_id')
  .insert({
    name: 'John Doe',
    email: 'johndoe@example.com',
  })
  .then(() => console.log('User added successfully'))
  .catch((error) => console.error('Failed to add user', error));

Update​

To update a document, you can call the update method on a DocumentReference and pass in an object that contains the partial update data as an argument:

Client code
squid
  .collection<User>('users')
  .doc('existing_user_id')
  .update({ email: 'new_email@example.com' })
  .then(() => console.log('User updated successfully'))
  .catch((error) => console.error('Failed to update user', error));

You can also update a specific property of a document by calling the setInPath method on a DocumentReference and passing the path to the property and the new value as arguments:

Client code
userRef
  .setInPath('address.street', 'Main')
  .then(() => console.log('Updated successfully'))
  .catch((error) => console.error('Failed to update user', error));

To delete a specific property of a document, you can call the deleteInPath method on a DocumentReference and pass in the path to the property you want to delete:

Client code
userRef
  .deleteInPath('email')
  .then(() => console.log('User email deleted successfully'))
  .catch((error) => console.error('Failed to delete user email', error));

Delete​

To delete a document, you can call the delete method on a DocumentReference:

Client code
userRef
  .delete()
  .then(() => console.log('User deleted successfully'))
  .catch((error) => console.error('Failed to delete user', error));