File
A File in Salesforce is a document, image, PDF, video, or other binary artifact stored on the platform and tracked through the ContentDocument and ContentVersion objects.
Definition
A File in Salesforce is a document, image, PDF, video, or other binary artifact stored on the platform and tracked through the ContentDocument and ContentVersion objects. Files are the modern way to store content, and they replaced the older Attachment model as the default starting around 2014. Every File carries metadata (title, description, type, size, owner), supports versioning, and can be shared with people, groups, records, and libraries.
A File is how Salesforce keeps documents next to the records they belong to. A signed contract on an Opportunity, a resolution PDF on a Case, a training video, a campaign creative, all live as Files. The platform renders previews for common formats, indexes supported files for full-text search, and controls who sees each File through link-level permissions rather than plain record sharing.
How the File data model and sharing actually work
ContentDocument and ContentVersion: two objects, one File
Every File you see in the UI is really two records working together. ContentDocument is the metadata container. It holds the title, the owner, and a pointer to the latest version through the LatestPublishedVersionId field. ContentVersion holds the actual bytes for each upload in its VersionData field, plus ContentSize, FileType, and an IsLatest flag. ContentDocument is available in API version 21.0 and later for Salesforce Files. The relationship is one to many. One ContentDocument can have many ContentVersion records, one for each time someone uploads a new version. The platform shows a single File with a version history, but the data model keeps every revision. This matters when you query files. If you want the current bytes, filter ContentVersion on IsLatest = true. If you want to insert a brand new File through the API, you create a ContentVersion first and Salesforce generates the parent ContentDocument for you automatically. Deleting the ContentDocument removes all its versions and any links to records.
Files versus the legacy Attachment model
Before Files, Salesforce stored binary content as Attachments. An Attachment is simpler. It hangs directly off one parent record through the ParentId field, and that is the end of it. No versioning, no preview, no sharing to multiple records, no full-text search of the content. Files were built to fix all of that. New uploads default to Files in Lightning Experience. The Notes and Attachments related list still exists on some objects for backward compatibility, but the modern Files related list is what most orgs use now. Existing Attachments do not convert themselves. They stay as Attachment records until you migrate them, and Salesforce ships tooling for that, including the Convert Attachments to Files Lightning Component and Apex-based jobs. If your org has years of historical Attachments, plan that migration deliberately so you gain versioning, sharing, and search on the old content too. Files also let one document attach to many records at once, which a single Attachment can never do.
Sharing through ContentDocumentLink and ShareType
Files do not inherit visibility from a record the way child records often do. Access is controlled by a junction object called ContentDocumentLink. Each link connects one ContentDocument to one place it is shared: a record (Account, Opportunity, Case), a User, a public Group, or a Content Library. A File with no link to you, and no library membership that covers it, is simply invisible to you. The link carries a ShareType field with three values. V means Viewer, so the person can open and download but not change the File. C means Collaborator, which adds edit and the ability to upload new versions. I means Inferred, where the person's access follows their permission on the related record instead of a fixed level. There is also a Visibility field that controls whether a File is visible to all users or limited to internal users, which matters once Experience Cloud or external sharing is in play. Because sharing is link based, you can grant one team edit rights and another team read only on the same File.
File Storage is a separate allocation from Data Storage
Salesforce splits storage into two buckets, and Files land in the file bucket, not the data bucket that holds your records. Data Storage is measured against record counts. File Storage holds the actual bytes of uploaded content, plus things like document attachments and field history files in some cases. The two have independent allocations, so filling one does not touch the other. Allocations come from your edition plus your user licenses. As a rough guide, several editions include a base file storage amount for the org and then add a per user license allowance on top. Large media is the thing to watch. A few dozen high resolution images or a handful of training videos can consume more file storage than thousands of text records consume of data storage. Check usage at Setup, then Storage Usage, where Salesforce shows file storage and data storage side by side with the biggest consumers. Audit it on a schedule, because file storage tends to creep upward quietly as users attach more content over time. Exact numbers vary by edition, so confirm against the current allocation table.
Previews, full-text search, and supported formats
Salesforce generates a rendered preview for common file types so users can read a document inside the File viewer without downloading it. PDF, Word, Excel, PowerPoint, and image formats preview cleanly. The preview is generated server side after upload, so a very large or unusual file may take a moment before its preview is ready, and some formats produce no preview at all. Search is the other big payoff over Attachments. Salesforce indexes the text content of supported file types, so a global search for an invoice number can surface the PDF that contains it, not just files whose title matches. The catch is that indexing depends on the file actually containing extractable text. A born-digital PDF with real text gets indexed. A scanned image saved as a PDF is just a picture of words, so it will not match a content search unless it has been run through OCR first. When users complain that search cannot find something inside a file, the file format is usually the reason. Format choices at upload time decide whether that content is findable later.
Libraries, Files Connect, and external content
Files can be grouped into Content Libraries, which are shared workspaces with their own membership and permission model. A Library is how a marketing team manages approved creative, how legal centralizes templates, and how an enablement team publishes training. Library access is set per library through library permissions, independent of record level sharing, so you can give a whole department read access to a body of content without touching any individual File link. Files Connect extends the model outward. It lets Salesforce surface content that physically lives in an external system such as SharePoint, Google Drive, OneDrive, or Box, presenting those external documents as if they were native Files. The bytes stay in the source repository, and Salesforce holds a reference rather than a copy, so external content does not consume your Salesforce file storage. This is the right pattern when a document of record already lives in another system and duplicating it would be wasteful or risky. Setup goes through an external data source and authentication, and once connected, users browse and attach external files from inside Salesforce.
How to surface and share Files on a record
Files show up on records through the Files related list. On most modern Lightning record pages it appears by default, but on custom or older layouts you may need to add it and tune how sharing behaves. Here is how to surface Files on a record and control who can do what.
- Open the Lightning record page or page layout
From Setup or the gear menu on the object, edit the Lightning record page in the App Builder, or open the classic page layout for the object whose records should show Files.
- Add the Files related list
In the App Builder, drop a Related List Single or Related Lists component and choose Files, or in a page layout add the Files related list under Related Lists. Save and activate the page.
- Upload and attach a File
On a record, use the Files related list or drag a file onto the page. The upload creates a ContentDocument and a first ContentVersion, and a ContentDocumentLink ties it to that record.
- Set the sharing level
Use the Share option on the File to add people, groups, or other records, and pick Viewer or Collaborator. For external surfacing instead of upload, configure Files Connect through an external data source.
The Lightning component that displays Files linked to the current record and lets users upload, preview, and download them in place.
Controls whether someone can only view and download a File or can also edit it and upload new versions.
Determines whether the File is available to all users or limited to internal users, which matters for Experience Cloud and external sharing.
Grants a group of users access to a whole body of files at once, independent of record level sharing.
- Files do not inherit record sharing automatically. Without a ContentDocumentLink or library access, a user cannot see the File even if they can see the record.
- The Notes and Attachments related list is the legacy one. Add the Files related list, not Notes and Attachments, for modern file behavior.
- Image-only or scanned PDFs are not indexed for content search unless OCR has added a real text layer.
- Files count against File Storage, not Data Storage, so large media can exhaust file storage long before data storage fills.
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on File.
Hands-on resources to go deeper on File.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Discussion
Loading discussion…