Data Retention and Cleanup

This page is the operator's procedure list for controlling what Face Matcher keeps and for how long. What each kind of data is, where it lives and why you would restrict it is explained in Data Retention; read that first. All API calls below go to the REST API on http://localhost:8098 (see REST API); none of them touches watchlists or watchlist members.

Set the storage mode

The storage mode decides whether anything from live streams is written to the database at all. Read it with GET /api/v1/Setup/DataStorage/Video; the default is:

{ "storageMode": "All" }

Set it with PUT /api/v1/Setup/DataStorage/Video and the same body. All stores detections of everyone, matched or not, with crops and full frames, and sends database notifications; it can fill a disk quickly. None stops storing and stops database notifications, leaving only the real-time notifications (matchResult, noMatchResult, faceProcessed and the like) for your integration, see RabbitMQ Notifications. Enrollment images and templates of watchlist members are stored in both modes.

Choose save strategies per source

With storageMode All, each camera and edge stream decides what it keeps. Set the properties in Station (Camera Settings Reference) or with PUT /api/v1/Cameras and PUT /api/v1/EdgeStreams:

Property	Values	Default	Effect
faceSaveStrategy	Balanced, All, MatchedOnly, None	Balanced	Balanced saves the first detection and then a new image whenever quality or match score improves; All saves every face; MatchedOnly applies the balanced rule to matched faces only; None stores nothing unless a linked object is saved.
pedestrianSaveStrategy	Balanced, All, None	Balanced	Same idea for pedestrian tracklets.
objectSaveStrategy	Balanced, All, MatchedOnly, None	Balanced	Same idea for objects.
saveFrameImageData	true, false	true	Store the full frame of each saved detection.

How much "better" a new image must be for Balanced and MatchedOnly to save it is tuned globally in .env section 2.13: BalancedFaceStrategy__QualityStep=1000, BalancedFaceStrategy__MatchScoreStep=10, MatchedOnlyFaceStrategy__MatchScoreStep=10, plus the pedestrian and object equivalents. Larger steps mean fewer images per tracklet. Apply changes with docker compose up -d.

Retention presets

Preset	Settings
Unlimited storage	faceSaveStrategy: All, saveFrameImageData: true, crop imageQuality: 100
Privacy / GDPR	faceSaveStrategy: MatchedOnly, saveFrameImageData: false, plus a short cleanup age below
Compact	faceSaveStrategy: Balanced, saveFrameImageData: false, crop imageQuality: 70
No data	storageMode: None

Disable image storage entirely

To keep detections, matches and templates but never store an image (no crops, no full frames, no notification or history pictures, no enrollment images), set the toggle in .env section 2.12 and restart:

NoSqlDataStorageDisabled=true

Detection, matching and liveness keep working; Station simply has nothing to show for events. Be aware that without stored enrollment images, face templates cannot be migrated to a newer template model later, see Template Migration; affected members would have to be re-enrolled.

Automated database cleanup

The cleanup job runs once a day and deletes old detection data; watchlist data is never touched. Read the configuration with GET /api/v1/Setup/DbCleanup (shown with defaults) and change it with PUT /api/v1/Setup/DbCleanup:

{
  "enabled": true,
  "cleanupAmount": null,
  "maxFramesCount": null,
  "maxImageDataAge": null,
  "cleanupStart": null,
  "deleteSql": false,
  "deleteMatchResults": false
}

Field	Meaning
enabled	Turns the job on or off.
maxImageDataAge	Days to keep frames; 7 deletes everything older than seven days.
maxFramesCount	Maximum number of frames to keep; the oldest go first.
cleanupStart	Time of day in UTC when the job runs, for example 01:00:00.
deleteSql	false deletes only image data (full frames, crops) and keeps the SQL records; true deletes the frames' SQL and image data.
deleteMatchResults	Also delete match results whose faces no longer exist.
cleanupAmount	Deprecated; leave null.

A typical GDPR-style setting keeps two weeks of data and removes records as well as images:

{
  "enabled": true,
  "maxImageDataAge": 14,
  "cleanupStart": "01:00:00",
  "deleteSql": true,
  "deleteMatchResults": true
}

Cleanup deletes rows and objects but does not shrink the PostgreSQL files or the SeaweedFS volume by itself; watch disk usage as described in Monitoring and Logs and take a backup before changing a long-running retention policy (Backup and Restore).