Salesforce Files vs Attachments: Differences and How to Convert

Salesforce Attachments and Salesforce Files both store documents against records, but they use different objects. An attachment is a single Attachment record that belongs to one parent record. A file is a ContentDocument with one or more ContentVersion records, and it can be shared with many records, users and groups through ContentDocumentLink. Files add version history, finer sharing and much larger size limits, and in Lightning Experience new attachments are added as Salesforce Files. To convert, you create a ContentVersion for each Attachment and link it to the same parent record.

The main differences:

• Storage objects. Attachments use one Attachment record, with the file in Body and the record it belongs to in ParentId. Files use ContentDocument for the file itself, ContentVersion for each version and its contents in VersionData, and ContentDocumentLink for every record, user, group or library the file is shared with.
• Sharing. An attachment belongs to one parent record and has an IsPrivate flag that limits it to the owner and administrators. A file can be linked to many records and people, each link with its own permission (ShareType of Viewer, Collaborator or Inferred from the record), up to 2,000 shares per file.
• Versioning. Attachments have no version history, so replacing one means a new attachment. Files keep every upload as a new ContentVersion under the same ContentDocument.
• Where they appear in Lightning. Files show on a record's Files related list and in Files home. In Lightning Experience, attachments added on a record are saved as Salesforce Files, so legacy Attachment records mostly come from Salesforce Classic, older integrations and imports.
• Size limits. Salesforce Help lists up to 10 GB for files uploaded in Files home, libraries or a record's Files related list, and 2 GB in Chatter posts and comments. Attachments added on a record in Salesforce Classic are limited to 25 MB.
• Search. Salesforce's object reference notes that Attachment records aren't searched during text searches.
• Migration. Attachments don't become files on their own. You create a new ContentVersion from each Attachment and link it to the parent record, then decide when to remove the originals.

If you already know you want to convert, go straight to how to migrate Salesforce Attachments to Files with Dataimporter.

1. How Salesforce Attachments work

Attachments are the original way to store documents on records. Each one is a single Attachment record with:

• ParentId: the one record it belongs to, such as an Account, Case, Opportunity, Task or a custom object record.
• Body: the file contents, sent and returned as base64 through the API.
• Name: the file name, up to 255 characters.
• IsPrivate: when true, only the owner and administrators can see it. Attachments on tasks and events can't be private.
• OwnerId: the user who owns it.

Because an attachment has exactly one parent, the same document attached to two records is two separate attachments. There is no history of earlier versions, and the API create call limits attachments to 25 MB (1.5 MB for solutions). The details are in Salesforce's Attachment object reference.

2. How Salesforce Files work

Salesforce Files split one document across three objects:

• ContentDocument: the file itself, which you see as one file in Salesforce.
• ContentVersion: one record per version, holding the contents in VersionData plus the Title and PathOnClient. Uploading a new version adds a ContentVersion to the same document.
• ContentDocumentLink: one record per place the file is shared, linking the document to a record, user, group or library.

Each link carries its own access level. ShareType is V (Viewer), C (Collaborator, who can edit) or I (Inferred, where access follows the user's access to the linked record). Visibility controls whether a file on a record is available to all users, internal users only or shared users. A single file can be shared up to 2,000 times, across records, people and groups.

When you create a file through the API, you can set FirstPublishLocationId on the ContentVersion to a record ID. Salesforce then links the new file to that record automatically, so you don't create the first ContentDocumentLink yourself. See the ContentVersion object reference.

3. Versioning

Version history is the clearest practical difference. With Files, uploading a new version of a contract keeps the earlier versions under the same document, and every record the file is shared with sees the latest one. With Attachments, an updated document is a new attachment, and you work out which is current from the file names and dates.

When you convert attachments to files, each attachment becomes the first version of a new file. Earlier copies uploaded as separate attachments stay separate files unless you combine them yourself.

4. Where they appear in Lightning Experience

In Lightning Experience, files show on a record's Files related list and in Files home, where users find and share files they own or can access. Salesforce Help notes that in Lightning Experience, attachments added on a record are added as Salesforce Files. Older Attachment records created in Salesforce Classic, by integrations or by imports stay as attachments until you convert them.

That matters for reporting and automation. Anything that queries Attachment won't see documents users have uploaded in Lightning, and anything that queries ContentDocumentLink won't see legacy attachments.

5. File size limits

From Salesforce Help's File Size and Sharing Limits page:

• Salesforce Files: 10 GB in Files home, libraries and on a record's Files related list. 2 GB when uploaded in Chatter posts and comments.
• Attachments in Lightning Experience: 10 GB, because they're added as Salesforce Files.
• Attachments in Salesforce Classic: 25 MB on a record's related list.
• Downloads over 2 GB: only through the REST API and the download servlet.

Some older Salesforce Help pages still list 2 GB as the maximum for Files, so check the limits page if a large upload fails. Limits through the API are lower and depend on the API you use, which is worth testing before you move large files.

6. When you still meet Attachments

Most orgs that have been around for a while have both. Attachments usually come from:

• Records created in Salesforce Classic.
• Integrations, Apex or email services written to create Attachment records.
• Earlier data imports that loaded documents as attachments.

Keeping both works, but users then look in two places, and reports and automation have to handle two models. That is the usual reason teams convert attachments to files, often as part of a wider clean-up or org migration.

7. What happens to attachments in a migration

There's no switch that converts existing attachments. Converting means creating new files from them and linking each file to the right record:

1. Read each attachment with its ParentId, Name and Body.
2. Create a ContentVersion with Body in VersionData, and Name in both Title and PathOnClient.
3. Link it to the parent by setting FirstPublishLocationId to the parent record's ID. In the same org that is the original ParentId. In a different org, record IDs change, so look up the parent by an external ID or another value that exists in both orgs.
4. Check the results by comparing counts of attachments and new files per parent, and spot-check a few records.
5. Remove the originals only after the check, once you've backed them up.

The same steps apply when you move records and their documents to a new org. Our Salesforce to Salesforce data migration guide covers load order and relationships for the rest of the data.

Dataimporter can do the conversion in the same org or between orgs with a Migration Template: add the parent object, add Attachment as a related object, change its target to ContentVersion and map the fields above. The full walkthrough is in how to migrate Salesforce Attachments to Files with Dataimporter, and Salesforce data migration with Dataimporter covers moving the records around them.

8. Summary

Attachments are single records tied to one parent, with no versions and smaller limits. Files separate the document, its versions and its shares into ContentDocument, ContentVersion and ContentDocumentLink, so one file can sit on many records with version history. Lightning Experience already saves new attachments as files, so converting older attachments leaves users with one place to look.

You can try Dataimporter for free and run a conversion on a sample of records first.

Frequently asked questions

What is the difference between Files and Attachments in Salesforce?

An attachment is one Attachment record linked to a single parent record. A file is a ContentDocument with ContentVersion records for each version, shared with records, users and groups through ContentDocumentLink. Files support version history, per-share permissions and larger uploads.

Which object stores Salesforce Files?

The contents are stored on ContentVersion in the VersionData field. ContentDocument represents the file across its versions, and ContentDocumentLink records where it's shared.

Are Salesforce Attachments being removed?

Attachment records still exist and can still be created through the API. In Lightning Experience, attachments added on a record are saved as Salesforce Files, so most new documents already end up as files.

What is the maximum file size for Salesforce Files and Attachments?

Salesforce Help lists 10 GB for files uploaded in Files home, libraries or a record's Files related list, 2 GB in Chatter posts and comments, and 25 MB for attachments added in Salesforce Classic. API uploads have lower limits.

How do I convert Attachments to Files?

Create a ContentVersion for each attachment with the attachment's contents in VersionData, its name in Title and PathOnClient, and the parent record's ID in FirstPublishLocationId. Salesforce links the new file to that record. See our step-by-step guide.