dataset.purgeItem()

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 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' })

Parameters

itemId:

string

ID of the item whose existing stored content is scrubbed.

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. Later updateItem() calls reject with the DATASET_ITEM_PURGED error.

Don't run purge concurrently with dataset item updates or deletions. A write that read the item before purge started can commit a stale revision after the purge completes.

The operation preserves dataset version history, item identity, experiment counters, and experiment review status. 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.

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.

Returns

result:

Promise<void>

Resolves when the item and linked experiment result content have been scrubbed.