Storage & Retention
Where events and metadata are stored, how long ClickHouse keeps events, and how to tier old data to object storage.
Review storage usage and retention in Settings → Storage & Retention (/settings/storage). The page separates the ClickHouse event store from PostgreSQL metadata.
| Tab | Shows |
|---|---|
| ClickHouse · Logs | Your OCSF events in ClickHouse: size on disk, compressed and uncompressed size, row count, partitions and the oldest and newest event, plus a disk pressure panel when the disk pressure service is active |
| PostgreSQL · Metadata | Metadata storage: detection rules, alerts, dashboards, saved searches, parser configurations and AI settings |
Viewing storage needs settings:view. Changing retention or tiering needs settings:retention.
Event retention (ClickHouse TTL)
Events are stored in the ClickHouse table nanosiem.ocsf_logs, partitioned by day. A table TTL deletes events older than the retention window: 365 days by default.
There is no retention editor in the UI. Change the window through the API:
curl -X PUT https://<host>/api/settings/storage/clickhouse/retention \
-H "X-API-Key: $NANO_API_KEY" -H "Content-Type: application/json" \
-d '{"retention_days": 180}'- The value must be at least 1 day.
- The change runs
ALTER TABLE … MODIFY TTLon the events table (on every shard of a cluster). ClickHouse removes expired data in the background as parts merge. - To delete expired data immediately, call
POST /api/settings/storage/clickhouse/retention/run. It materializes the TTL and optimizes the table, which can take several minutes on a large table. The request gives up after 5 minutes, but the operation keeps running in ClickHouse.
GET /api/settings/storage/clickhouse returns the size, row count, partition count and date range of the events table.
Both changes are recorded in the audit log.
Deleting a specific person's data is a separate process: see GDPR & Compliance (/settings/gdpr).
Storage tiering
Older ClickHouse parts can move from local disk to S3-compatible object storage, where they stay searchable. Tiering is configured through the API only; there is no UI for it.
| Method and path | Purpose |
|---|---|
GET /api/settings/tiering | Current configuration: endpoint, bucket, region, path style, whether credentials are set, move_factor, status and last apply time |
PUT /api/settings/tiering | Save the configuration |
POST /api/settings/tiering/credentials | Store the access key ID and secret (encrypted at rest) |
POST /api/settings/tiering/test | Test the connection to the bucket |
POST /api/settings/tiering/apply | Apply the storage policy to ClickHouse |
GET /api/settings/tiering/stats | Size and row count on each tier |
On Kubernetes, the Helm chart configures the cold tier instead (clickhouse.coldStorage.*); see Kubernetes. When tiering is active, the disk pressure service no longer drops partitions; data moves off the local disk instead.
Metadata pruning
The PostgreSQL retention policy (GET / PUT /api/settings/retention, {"enabled": true, "retention_days": N}) controls metadata only. POST /api/settings/retention/run prunes, older than the window:
- detection match records
- detection finding-emission records
- search history
It returns an error if the policy isn't enabled. It never deletes events; ClickHouse TTL does that.
API summary
| Method and path | Purpose |
|---|---|
GET /api/settings/storage/overview | Storage figures for ClickHouse and PostgreSQL, plus disk pressure status |
GET /api/settings/storage/clickhouse | Events table size, rows, partitions and date range |
PUT /api/settings/storage/clickhouse/retention | Set the event TTL in days |
POST /api/settings/storage/clickhouse/retention/run | Delete expired events now |
GET /api/settings/storage | PostgreSQL metadata statistics |
GET / PUT /api/settings/retention | Metadata retention policy |
POST /api/settings/retention/run | Prune PostgreSQL metadata now |
/api/settings/tiering/* | Storage tiering (above) |
Troubleshoot
Need help with these checks? Contact support with the request ID and time with timezone.
Old events are still searchable after lowering retention
ClickHouse applies a new TTL as parts merge. Run POST /api/settings/storage/clickhouse/retention/run to delete expired data immediately.
Running retention doesn't remove events
POST /api/settings/retention/run prunes PostgreSQL metadata. Use the ClickHouse retention routes for events.