Understanding Deletes in Append-Only Storage
OnchainDB performs soft deletes. When you delete a document, a new record with deleted: true is appended. The original data remains on the blockchain but is excluded from query results by default.
deleteDocument
Soft delete a document by appending a deletion record.
const deleted = await client.deleteDocument(
'users',
{ email: 'alice@example.com' },
{
payment_tx_hash: 'tx_hash',
user_address: 'celestia1...',
broker_address: 'celestia1broker...',
amount_utia: 30000
}
);
console.log('Deleted:', deleted); // true if found and soft-deleted
Parameters
| Parameter | Type | Description |
|---|
collection | string | Collection name |
where | object | Filter to find document |
paymentProof | PaymentProof | Payment information |
Return Value
Returns boolean - true if document was found and deleted, false if not found.
How Deletes Work
Original Record (Block 100):
{ id: "user_1", name: "Alice", email: "alice@example.com", deleted: false }
After deleteDocument (Block 101):
{ id: "user_1", deleted: true, deletedAt: "2024-01-02", updatedAt: "2024-01-02" }
Original record still exists on-chain, but queries exclude deleted records
Examples
Delete by ID
const deleted = await client.deleteDocument(
'posts',
{ id: 'post_123' },
paymentProof
);
if (deleted) {
console.log('Post deleted successfully');
} else {
console.log('Post not found');
}
Conditional Delete Pattern
// First verify ownership or permissions
const post = await client.findUnique('posts', { id: 'post_123' });
if (post && post.author === currentUser.id) {
await client.deleteDocument('posts', { id: 'post_123' }, paymentProof);
console.log('Post deleted');
} else {
console.log('Unauthorized or not found');
}
Verifying Deletion
After deletion, the document won’t appear in normal queries:
// Delete a user
await client.deleteDocument('users', { id: 'user_123' }, paymentProof);
// findUnique returns null for deleted documents
const user = await client.findUnique('users', { id: 'user_123' });
console.log(user); // null
// findMany excludes deleted documents
const users = await client.findMany('users', {});
// Deleted user is not in results
Data Retention
Since OnchainDB uses append-only storage:
| Aspect | Behavior |
|---|
| Original data | Remains on blockchain permanently |
| Query results | Exclude deleted records by default |
| Audit trail | Full history is preserved |
| Recovery | Possible by querying historical records |
Bulk Delete Pattern
For deleting multiple documents, iterate and delete:
const inactiveUsers = await client.findMany(
'users',
{ active: false }
);
for (const user of inactiveUsers) {
await client.deleteDocument('users', { id: user.id }, paymentProof);
}
Next Steps
