Skip to main content

Data Retention

The Data Retention page configures how long historical data is kept before automatic cleanup. Proper retention management balances storage capacity, performance, and reporting needs.

Overview​

Data retention controls four historical tables:

  1. Attribute History: Sensor readings, device states, zone changes
  2. Request History: Commands, macro executions, API calls
  3. Access Log: Physical access control events
  4. Automation History: Every trigger fire, schedule fire, and macro run, with the upstream cause preserved across nested calls

Current Data Overview​

Summary cards show current record counts:

  • Attribute History Records: Total count
  • Request History Records: Total count
  • Access Log Records: Total count
  • Automation History Records: Total count

Monitoring:

  • Watch for excessive growth (>1M records)
  • Large tables impact query performance
  • Regular cleanup maintains speed

Retention Settings​

Configure retention period for each data type:

Attribute History​

Description: Sensor readings, device states, temperature logs

Retention Period: Days to keep (1-3650)

Default: 7 days

Recommendations:

  • Production systems: 90-180 days
  • Analytics-heavy: 180-365 days
  • Compliance requirements: Per regulation
  • Simple systems: 30-60 days

Purge Now: Manually delete records older than configured days

Request History​

Description: Commands, macro executions, model changes, admin-only operations, and denied API requests. Each record includes the user, result (granted/denied), and denial reason. See Request History for details.

Retention Period: Days to keep

Default: 7 days

Recommendations:

  • Standard: 30-90 days
  • Troubleshooting active: 180 days
  • Security auditing: 180-365 days
  • Minimal logging: 7-14 days
  • High-traffic: 30 days

Purge Now: Immediate cleanup

Access Log​

Description: Access control events (PIN, RFID)

Retention Period: Days to keep

Recommendations:

  • Security requirements: 90-365 days
  • Compliance (may require 1-7 years)
  • Standard: 180 days
  • Minimal: 30 days

Purge Now: Manual purge

Automation History​

Description: Trigger fires, schedule fires, and macro runs. Each row captures the upstream cause (trigger/schedule/auth_user) so cause chains stay intact across nested macro calls. Surfaced under the Run History tab on the macro / trigger / schedule editor and as the trigger-fires overlay on Attribute History.

Retention Period: Two separate windows — successful/skipped runs and failed/aborted runs.

SettingDefaultNotes
success days14Applies to status of success, skipped, or debounced
failure days180Applies to status of failed or aborted — kept longer because they matter longer

A per-artifact cap of 10,000 rows applies as a noisy-neighbor safety net even within the retention window — one chatty trigger cannot drown the table.

Recommendations:

  • Most installs: defaults are fine
  • Heavy automation debugging: success 30, failure 365
  • Storage-constrained: success 7, failure 90

Automatic Cleanup​

Schedule: Runs daily at midnight (server time)

Process:

  1. Identifies records older than retention period
  2. Deletes in batches (prevents performance impact)
  3. Logs results
  4. Optimizes database tables

Enable: Automatic cleanup runs if db_maintenance_enabled = true

Manual Operations​

Save Settings​

Click Save Settings to:

  • Store retention periods
  • Apply to automatic cleanup schedule
  • No immediate data deletion

Reset​

Click Reset to reload the current saved settings, discarding any unsaved changes.

Run Maintenance Now​

Click Run Maintenance Now to:

  • Execute cleanup immediately
  • Delete records per current retention settings
  • Show results:
    • Records deleted from attribute_history
    • Records deleted from request_history
    • Records deleted from access_log
    • Records deleted from automation_history

Confirmation: Required (destructive operation)

Purge Individual Tables​

Click Purge Now next to any table to:

  • Delete only that table's old records
  • Use that table's retention setting
  • Leave other tables unchanged

Use Cases:

  • Attribute history growing too fast
  • Need space immediately
  • Testing retention settings

Important Warnings​

Irreversible: Deleted data cannot be recovered

Backup First:

  • Create backup before purging
  • Especially before testing new retention settings

Compliance: Verify retention meets:

  • Legal requirements
  • Industry regulations
  • Company policies

Recommendations:

  • Attribute History: ≥30 days
  • Request History: ≥7 days
  • Access Log: ≥90 days

Retention Strategy​

Small Systems (<100 zones)​

Conservative Retention:

Attribute History: 180 days
Request History: 90 days
Access Log: 180 days

Storage Impact: Minimal (few MB to few GB)

Large Systems (>500 zones)​

Aggressive Retention:

Attribute History: 30 days
Request History: 14 days
Access Log: 90 days (compliance)

Storage Impact: Significant (10+ GB possible)

Compliance-Driven​

Extended Retention:

Attribute History: 365 days (1 year)
Request History: 365 days
Access Log: 2555 days (7 years for some regulations)

Mitigation:

  • Increase server storage
  • Export old data to archive
  • Use database optimization

Performance Impact​

Record Count Guidelines​

Attribute History:

  • <100K records: No impact
  • 100K-1M: Minor impact
  • 1M-10M: Moderate impact

  • 10M: Significant impact

Request History:

  • <10K: No impact
  • 10K-100K: Minor impact

  • 100K: Moderate impact

Access Log:

  • <50K: No impact
  • 50K-500K: Minor impact

  • 500K: Moderate impact

Optimization​

When tables grow large:

  1. Reduce Retention: Shorten retention periods
  2. Run Maintenance: Execute cleanup
  3. Archive Data: Export old data before purging
  4. Disable Unnecessary History: Remove history flag from unneeded attributes