dataset.purgeItem()
Added in: @mastra/core@1.65.0
Permanently scrubs a dataset item's content from every historical version, deletion tombstone, and linked experiment result. Use deleteItem() instead when you only need to remove an item from the current dataset version.
Usage exampleDirect link to Usage example
import { Mastra } from '@mastra/core'
const mastra = new Mastra({/* storage config */})
const dataset = await mastra.datasets.get({ id: 'dataset-id' })
await dataset.purgeItem({ itemId: 'item-id' })
ParametersDirect link to Parameters
itemId:
BehaviorDirect link to Behavior
Purging replaces the item's content fields in existing history rows and deletion tombstones with redacted values and adds a purge marker to its metadata. The same fields, along with tags and comments, are scrubbed from experiment results linked to this dataset item. Experiment-result writes submitted after the purge are stored with redacted content.
Purge serializes or conflicts with concurrent dataset item writers without guaranteeing which operation completes first. If a mutating updateItem() call loses the race, it re-reads the purge marker and rejects with DATASET_ITEM_PURGED. deleteItem() remains idempotent, and any deletion tombstone created during the race stays redacted.
Normal item mutations use Slowly Changing Dimension Type 2 (SCD-2) versioning. Permanent purge intentionally overrides historical immutability for erasure while preserving item identity and the dataset version timeline. It doesn't create a new dataset version. Version-pinned reads can still return the item's row skeleton, but its purged content is no longer available. Experiment counters and review status are also preserved.
MongoDB storage requires a replica set or sharded deployment with transaction support. If transactions aren't available, the operation fails before changing the item or its experiment results.
externalId remains unchanged because Mastra uses it as an identity key. Don't store sensitive data in externalId.
Purging is idempotent and can't be undone.