Skip to main content

vai purge

Remove embedding documents from MongoDB based on filter criteria. Supports filtering by source pattern, date, model, raw MongoDB filter, or stale source files.

Synopsis​

vai purge [options]

Description​

vai purge deletes documents from your embeddings collection based on one or more criteria. At least one filter is required — you can't accidentally purge everything. Before deleting, it shows a preview of matching documents and asks for confirmation (unless --force is used).

The --stale mode is particularly useful: it finds documents whose metadata.source file no longer exists on disk, letting you clean up embeddings for deleted files.

Options​

FlagDescriptionDefault
--db <database>Database nameFrom .vai.json or VAI_DB
--collection <name>Collection nameFrom .vai.json or VAI_COLLECTION
--source <glob>Filter by metadata.source pattern (glob-like)—
--before <date>Filter by _embeddedAt before date (ISO 8601)—
-m, --model <model>Filter by _model field—
--filter <json>Raw MongoDB filter (JSON string)—
--staleRemove docs whose source files no longer exist on disk—
--forceSkip confirmation prompt—
--dry-runShow what would be deleted without acting—
--jsonMachine-readable JSON output—
-q, --quietSuppress non-essential output—

Examples​

Remove embeddings from a specific source​

vai purge --source "docs/old-api/*"

Remove embeddings created before a date​

vai purge --before 2024-01-01

Remove embeddings from a legacy model​

vai purge --model voyage-3-large

Find and remove stale embeddings​

vai purge --stale --dry-run   # preview first
vai purge --stale --force     # then clean up

Combine multiple filters​

vai purge --model voyage-3.5-lite --before 2024-06-01 --force

Tips​

  • Always use --dry-run first to preview what will be deleted.
  • The --stale flag compares metadata.source paths against the filesystem. It resolves relative paths from the project root (or current directory).
  • Multiple filter options are combined with $and — all conditions must match.
  • Purge is permanent. There is no undo.