Data Storage Management

Data Storage Management

This skill activates when an org is approaching storage limits, receiving storage alert emails, or when a practitioner needs to understand how Salesforce allocates and measures data storage vs file storage. It covers monitoring, diagnosis, reclamation, and field-level optimization. It does NOT cover offloading files to external systems such as S3 or Heroku — use the data-archival-strategies skill for those patterns.

Before Starting

Gather this context before working on anything in this domain:

• Navigate to Setup > Storage Usage and note the current data storage usage (GB used / GB allocated) and file storage usage separately. Export or screenshot the per-object breakdown.
• Confirm the org edition. Enterprise orgs receive 10 GB base data storage + 20 MB per user license and 10 GB base file storage + 2 GB per user license. Unlimited orgs receive more generous per-user additions.
• Check whether a large delete or data load ran recently. Storage is recalculated asynchronously, so the Storage Usage page may simply not have caught up. The Recycle Bin is not a contributor: records in it do not count against storage, so do not budget for reclaiming anything by emptying it.
• Confirm whether Big Objects are in use. Big Objects have their own separate storage allocation and do NOT consume regular data storage quota.

Core Concepts

Data Storage vs File Storage

Salesforce measures two distinct pools of storage:

Data storage counts every standard and custom object record. The platform allocates roughly 2 KB per record on average, though records with many Long Text Area fields can consume significantly more. Every record in every object — including junction objects, history tracking records, feed items, and task/event records — contributes to the data storage total.

File storage counts the binary content of files: ContentDocument (Salesforce Files), legacy Attachment records, Documents in the Documents tab, and Chatter post attachments. Each ContentVersion (a version of a File) contributes its full byte size to file storage. Thumbnail previews and renditions generated by Salesforce also consume file storage.

For Enterprise edition:

• Data storage: 10 GB base + 20 MB per user license
• File storage: 10 GB base + 2 GB per user license

These allocations are org-wide shared pools. There is no per-user or per-object quota.

Monitoring Storage Usage

The canonical monitoring path is Setup > Storage Usage. This page shows:

• Total data storage used vs allocated, broken down by object type
• Total file storage used vs allocated, broken down by ContentDocument, Attachment, Document, etc.

For programmatic monitoring, use the Limits API (GET /services/data/vXX.0/limits/) which returns DataStorageMB and FileStorageMB with Max and Remaining values. This is the recommended approach for automated alerting pipelines.

Salesforce sends automated email alerts to system administrators at 75%, 90%, and 100% of storage capacity for both data and file storage pools independently.

ContentDocument (Files) vs Attachments

The legacy Attachment sObject is tied one-to-one to a parent record. If the same file needs to be associated with multiple records, it must be duplicated — each copy consuming full file storage. Attachments cannot be shared.

ContentDocument (Salesforce Files) with ContentDocumentLink is the modern replacement. A single ContentDocument can be linked to multiple records via ContentDocumentLink records without duplicating the binary content. This is a critical distinction for orgs that attach the same reference documents (contracts, product specs) to many records.

Prefer ContentDocument for all new file upload patterns. Migrate Attachments to ContentDocument when reclaiming file storage — but plan the migration carefully since it touches sharing, Apex triggers, and API integrations that reference the Attachment sObject.

Large Text Area Fields and Data Storage

Long Text Area and Rich Text Area fields count toward data storage based on their actual content length, not the field's maximum size. An empty Long Text Area field on a record does not consume the maximum 131,072 characters of storage. However, records with dense Rich Text Area content (embedded base64 images, heavy formatting markup) can push individual record sizes well above the 2 KB average.

Rich Text Area fields that store embedded images actually move those image bytes into file storage, not data storage — the field stores a reference. This is a non-obvious split that can cause confusion when diagnosing storage usage.

Recycle Bin and Storage Reclamation

Two claims circulate about this and both are wrong. Check them against Salesforce Help before acting on a storage incident.

• Standard delete puts records in the Recycle Bin for 15 days, during which they can be restored. Records in the Recycle Bin do not count against the org's storage usage ("Records in the Recycle Bin don't count against your Salesforce org's storage usage" — Manage the Recycle Bin), and there is no cap on how many deleted records the bin holds. So emptying the bin is not a storage-reclamation lever; it is a recoverability decision, and an irreversible one.
• Bulk API hard delete does not go to the Recycle Bin at all. That is the definition of the operation: records bypass the bin and are immediately and permanently gone. There is no 30-day (or any) window in which a hard delete can be undone. Anyone told otherwise will authorise a hard-delete job believing it is reversible.

Why storage still looks unchanged after a mass delete: storage is recalculated asynchronously. Salesforce Help states that after adding or removing a large number of records or files, "the change in your org's storage usage isn't reflected immediately." Wait and re-check Setup > Storage Usage rather than reaching for the Recycle Bin.

Programmatic reclamation: use Database.emptyRecycleBin(List<Id>) in Apex or the REST API DELETE /services/data/vXX.0/sobjects/{SObjectType}/{id}?allOrNone=false to permanently delete specific records. For bulk reclamation, use the Bulk API with hardDelete operation.

Common Patterns

Pattern: Storage Usage Triage After Alert

When to use: Org has received a 75%, 90%, or 100% storage alert email and the administrator needs to identify what is consuming storage and what can be safely reclaimed.

How it works:

1. Open Setup > Storage Usage. Note the top 5 objects by data storage consumption.
2. For each high-volume object, check whether records in it have a defined retention need. Common candidates for cleanup: Task/Event records older than 2 years, ContentVersion records from deleted parent records (orphaned files), EmailMessage records.
3. Rule out asynchronous recalculation before diagnosing further — if a large delete or load ran recently, the page may not have caught up. Do not reach for the Recycle Bin: bin records do not count against storage, so emptying it frees nothing and destroys the 15-day restore window.
4. Query orphaned ContentDocuments: SELECT Id FROM ContentDocument WHERE Id NOT IN (SELECT ContentDocumentId FROM ContentDocumentLink). These files have no linked records and can be safely deleted.
5. For large Attachment volumes, evaluate migration to ContentDocument to enable deduplication via ContentDocumentLink.

Why not skip the triage: Deleting records from the wrong object or time range can break business processes. Triage first, delete second.

Pattern: Preventing Duplicate File Storage via ContentDocumentLink

When to use: Multiple records need access to the same file (e.g., a standard contract template linked to every Opportunity).

How it works:

• Create the ContentDocument once (via ContentVersion insert).
• Create one ContentDocumentLink record for each parent record that needs access.
• Each ContentDocumentLink costs ~2 KB of data storage (it is a record), but the file binary is stored only once in file storage.

Why not use Attachments: Every Attachment is an independent binary copy tied to one parent. 1,000 Opportunities each with the same 500 KB contract template = 500 MB of file storage. The same pattern using ContentDocumentLink = 500 KB of file storage + ~2 KB × 1,000 = ~2 MB data storage. The saving is roughly 250x.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Gather current state — Open Setup > Storage Usage and record the current data storage used/allocated and file storage used/allocated. Note the top 5 objects by consumption in each pool. Confirm org edition and license count to understand the total allocation formula.
2. Rule out asynchronous recalculation — If a large delete or load ran recently, the Storage Usage page may simply not have caught up; Salesforce recalculates storage asynchronously. Re-check before diagnosing further. Do NOT empty the Recycle Bin as a reclamation step: bin records do not count against storage, so it frees nothing, and it destroys the 15-day restore window for everything in there.
3. Identify orphaned ContentDocuments — Run SELECT Id, Title, ContentSize FROM ContentDocument WHERE Id NOT IN (SELECT ContentDocumentId FROM ContentDocumentLink) in the Developer Console or Workbench. Delete orphans in batches using Bulk API hardDelete.
4. Assess high-volume objects — For the top data storage consumers, determine: (a) whether a retention policy allows deletion of old records, (b) whether the object is a candidate for Big Object archival, and (c) whether Large Text Area fields with embedded content are inflating sizes beyond the 2 KB average.
5. Evaluate Attachment-to-ContentDocument migration — If Attachments appear in the top file storage consumers, query for duplicate content (same ParentId pattern or same file name across many records). Plan migration using ContentVersion + ContentDocumentLink to eliminate binary duplication.
6. Set up monitoring — Implement an automated check using the Limits API. Alert when DataStorageMB.Remaining / DataStorageMB.Max drops below 25%. Salesforce's built-in alerts (75%, 90%, 100%) are a safety net, not a proactive monitoring strategy.
7. Validate and document — After reclamation actions, refresh Setup > Storage Usage to confirm the reduction. Document which objects were cleaned, how many records deleted, and the storage reclaimed. Update retention policies if none existed.

Review Checklist

Run through these before marking work in this area complete:

• Setup > Storage Usage reviewed and per-object breakdown captured
• Asynchronous recalculation ruled out after any recent large delete or load
• Orphaned ContentDocuments queried and deleted (or confirmed none exist)
• Attachment vs ContentDocument decision documented for any new file feature
• Limits API monitoring confirmed or set up (alert threshold ≤25% remaining)
• Big Object suitability assessed for any high-volume append-only objects
• No Rich Text Area fields storing embedded base64 images directly in field content

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Recycle Bin records do NOT count toward storage, and hard delete is not recoverable — Two widely-repeated beliefs, both wrong. Per Salesforce Help, records in the Recycle Bin don't count against the org's storage usage and the bin has no record-count cap; the 15-day figure is a restore window, not a storage-accounting window. And Bulk API hard delete bypasses the bin entirely — immediate, permanent, no undo, no 30-day grace. Storage that hasn't dropped after a mass delete is almost always asynchronous recalculation, which resolves on its own.
2. Big Objects do NOT consume regular data storage — Practitioners planning to migrate log or audit records to Big Objects to "free up" storage will succeed — Big Objects have their own separate, larger allocation and are entirely independent of the standard data storage pool.
3. ContentVersion renditions consume file storage — When a ContentDocument is uploaded, Salesforce auto-generates preview thumbnails and PDF renditions. These renditions are stored as additional ContentVersion records and count toward file storage. An org with millions of small uploaded files can see file storage inflated 2–3x by renditions alone.
4. Field History Tracking records count toward data storage — Every tracked field change creates a FieldHistory (or similar history sObject) record. Orgs with many tracked fields on high-volume objects can accumulate millions of history records. History records are stored for 18 months and then deleted by Salesforce, but current records count toward storage.
5. Chatter attachments count toward file storage, not data storage — Files attached directly to Chatter posts (FeedAttachment) are stored as ContentDocument records and count against file storage. They are not counted in data storage. Orgs with heavy Chatter usage should monitor file storage, not just data storage.

Output Artifacts

Related Skills

• data/data-archival-strategies — use when records need to be removed from the active org but retained for compliance; covers Big Objects, external archival, and MuleSoft/Heroku offload patterns
• data/batch-data-cleanup-patterns — use when planning large-scale record deletion or data quality cleanup that will reclaim storage
• architect/limits-and-scalability-planning — use when designing new data models and need to project storage growth over time before it becomes a problem