Deleting Data

Remove documents or specific fields from your database with single and batch delete operations.

Why Use Delete Operations

You need to remove records from your database, whether deleting entire documents, clearing multiple documents at once, or removing specific fields from a document. The Squid Client SDK provides delete operations for each of these cases.

Overview

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

Like other mutations, deletes are applied optimistically on the client and then synced with the server. For details on how optimistic updates work, see Adding data.

Core Concepts

Delete

To delete a document, call the delete method on a document reference:

Client code

const userRef = squid.collection<User>('users').doc('existing_user_id');

try {
  await userRef.delete();
  console.log('User deleted successfully');
} catch (error) {
  console.error(`Failed to delete user ${error}`);
}

Delete many

To delete multiple documents in a batch, use the deleteMany method on a collection reference. deleteMany takes an array of documents or document IDs as a parameter.

Client code

const staleDocs = await squid
  .collection<User>('users')
  .query()
  .eq('pending-delete', true)
  .snapshot();

try {
  await squid.collection<User>('users').deleteMany(staleDocs);
  console.log('Users successfully deleted');
} catch (error) {
  console.error(`Failed to delete users ${error}`);
}

When deleting many documents, you can use field projection to reduce the query payload size, since deleteMany only needs the document references, not the full document data:

Client code

const staleDocs = await squid
  .collection<User>('users')
  .query()
  .eq('pending-delete', true)
  .projectFields([])
  .snapshot();

await squid.collection<User>('users').deleteMany(staleDocs);

Delete in path

To delete a specific property of a document, call the deleteInPath method on a document reference and pass in the path to the property you want to delete. Use dot notation to specify nested properties in the path:

Client code

const userRef = squid.collection<User>('users').doc('existing_user_id');

try {
  await userRef.deleteInPath('contact.email');
  console.log('User email deleted successfully');
} catch (error) {
  console.error(`Failed to delete user email ${error}`);
}

Error Handling

Error	Cause	Solution
Security rule rejection	The delete was blocked by security rules	Verify the user has delete permission for the collection
Document not found	Attempting to delete a document that does not exist	Verify the document ID is correct; check that the document has not already been deleted
Invalid path	The path passed to deleteInPath does not exist on the document	Verify the path using dot notation matches the document structure

Best Practices

1. Use deleteMany() for batch operations instead of deleting documents one at a time in a loop.

2. Query before deleting to confirm which documents will be removed, especially for batch deletions:

   Client code

   const toDelete = await squid
     .collection<User>('users')
     .query()
     .eq('status', 'inactive')
     .snapshot();
   console.log(`Deleting ${toDelete.length} inactive users`);
   await squid.collection<User>('users').deleteMany(toDelete);

3. Use deleteInPath() to remove optional fields rather than setting them to null or empty values, to keep your documents clean.

4. Wrap related deletes in a transaction when you need to ensure all deletions succeed or fail together.