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 the recycle bin is a major contributor — deleted records count toward storage until the bin is emptied or records age past 15 days (30 days for bulk-deleted records).
• 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.
• Recycle Bin usage (data storage held by deleted-but-not-purged records)

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

Deleted records remain in the Recycle Bin for 15 days (standard delete) or 30 days (Bulk API hard delete), and they continue to count against data storage during that period. Emptying the Recycle Bin is often the fastest way to reclaim meaningful storage without any data risk — but it is irreversible.

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. Check the Recycle Bin section. If significant storage is held there, emptying it is the lowest-risk first step.
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. Check the Recycle Bin — If Recycle Bin data storage is significant (>5% of total), empty it first. This is zero-risk reclamation. Use Database.emptyRecycleBin() for targeted purges or the Setup UI for full purge.
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
• Recycle Bin storage checked and emptied if significant
• 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 counts toward storage — Deleted records are not immediately freed. They hold their data storage allocation for 15 days (standard deletes) or 30 days (Bulk API hard deletes). An org that mass-deletes records and then wonders why storage hasn't dropped needs to empty the Recycle Bin.
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