Content Document
A Content Document in Salesforce (ContentDocument in the API) is the persistent parent record that represents a single file in the Salesforce Files framework.
Definition
A Content Document in Salesforce (ContentDocument in the API) is the persistent parent record that represents a single file in the Salesforce Files framework. The Content Document itself does not hold the binary content. It holds the metadata users see, such as Title, FileType, FileExtension, ContentSize, ContentModifiedDate, OwnerId, the LatestPublishedVersionId pointing at the current Content Version, and the SharingPrivacy flag. The binary lives on child Content Version records, and the file-to-record attachments live on child Content Document Link records.
Salesforce introduced Content Document as part of the modern Files framework that replaced the legacy Attachment object around 2014. The shift moved Salesforce from a per-record attachment model (where each file was tied to one parent) to a shared-file model (where one file can be linked to many parents at once and carries its own version history). Content Document is the user-facing identifier that survives across versions; the Content Versions underneath are the actual binary payloads.
How Content Document fits into the Salesforce Files framework
The three-object structure: Content Document, Content Version, Content Document Link
The Files framework has three main objects. Content Document is the persistent parent that survives across versions; it has one ID that does not change. Content Version is the per-version child; uploading a new version of the same file creates a new Content Version record but keeps the Content Document ID stable. Content Document Link is the junction that connects a Content Document to whatever record it has been attached to (Account, Case, Opportunity, and others). One file can have many Links to many parent records.
What metadata lives on the Content Document
The Content Document record holds Title (the display name), FileType (the high-level type like Image or PDF), FileExtension (the actual extension), ContentSize (current version size in bytes), ContentModifiedDate (when the latest version was uploaded), OwnerId, LatestPublishedVersionId (foreign key to the active Content Version), SharingOption (Allowed or Restricted from linking to additional records), and SharingPrivacy (Public or Private). The metadata reflects the latest version; previous versions keep their own metadata on their respective Content Version records.
How Content Document replaces Attachment
The legacy Attachment object tied one file to one parent record. Attaching the same document to ten Cases meant ten copies of the binary, ten storage charges, and no version history. Content Document replaces that model: one Content Document with ten Content Document Links to ten Cases, one storage charge, and shared version history. Attachments still exist for backward compatibility and for objects that have not migrated, but new development should use Content Document.
Version history and the LatestPublishedVersionId pointer
Uploading a new version of an existing file creates a new Content Version record under the same Content Document. The Content Document LatestPublishedVersionId pointer updates to the new version. Old versions remain queryable through Content Version and can be downloaded individually. The version number on Content Version increments as 1, 2, 3, and so on. This is how Salesforce supports rolling back to an older version or auditing what the file content was at a given date.
Sharing and visibility through Content Document Links
Visibility of a Content Document depends on its Content Document Links. If a user can see the parent record of a Link (e.g., the Case the file is attached to), they can see the file (subject to the Link Visibility field, which can be set to Viewer, Collaborator, or Owner). Removing all Links removes user access to the file (other than the owner). This is a different model than legacy Attachments, which inherited visibility from their single parent.
Content Document in Files vs Libraries
Salesforce Files framework supports two main organizational patterns. Files attached to records (the most common) link a Content Document to a parent record through a Content Document Link. Files in Libraries (Salesforce CRM Content Libraries, also called Content Libraries) organize Content Documents into folder-like containers separate from individual records. Both use the same Content Document object underneath; the difference is whether the file is attached to records or sitting in a library for browse-style discovery.
Files Connect and the external Content Document
Salesforce Files Connect lets external storage (SharePoint, Google Drive, Box) appear as Content Documents in Salesforce without copying the files into Salesforce storage. The Content Document record exists with metadata, but the binary stays in the external system. This is the modern pattern for orgs that already have document management in Microsoft or Google and want to avoid duplicating files into Salesforce.
How to work with Content Document in Salesforce
Most users interact with Content Document through the Files UI rather than the object directly. For developers and admins, the object is queryable through SOQL and writable through Apex with a few gotchas around version handling.
- Confirm Salesforce Files is enabled
All editions above Group Edition have Salesforce Files enabled by default. If you only see the legacy Notes and Attachments related list, ensure the Files Related List is added to the page layout in Setup, Object Manager, Page Layouts.
- Upload a file from a record
Open any record (Case, Account, Opportunity). In the Files related list, click Upload Files. Salesforce creates a Content Document, a Content Version with the binary, and a Content Document Link tying it to the current record.
- Attach an existing file to another record
From a different record, click Add Files in the Files related list. Salesforce shows a picker of existing Content Documents you have access to. Selecting a file creates a new Content Document Link without duplicating the binary.
- Query Content Document programmatically
SOQL like SELECT Id, Title, FileType, ContentSize, LatestPublishedVersionId FROM ContentDocument WHERE Id IN ... The LatestPublishedVersionId joins to the active Content Version. Most useful queries also join Content Document Link to find which records a file is attached to.
- Upload a new version through Apex
Insert a new Content Version with the same ContentDocumentId as an existing Content Document. Salesforce automatically updates the LatestPublishedVersionId pointer on the parent.
- Delete a Content Document
Deleting a Content Document cascades to delete all Content Versions and Content Document Links. Use delete carefully; this is destructive and reduces storage but removes the file from every record it was attached to.
- Content Document is the parent; Content Version is the per-version child. Updating metadata on the wrong object is a common bug.
- Removing all Content Document Links does not delete the Content Document. The file persists in storage until you delete the Content Document itself.
- Apex code that inserts Content Version without an existing Content Document creates a new Content Document automatically. To version an existing document, set the ContentDocumentId on the new Content Version explicitly.
- Attachment and Content Document are different objects with different APIs. Code targeting Attachment will not find files stored as Content Document and vice versa.
- Files larger than 2 GB cannot be uploaded as a Content Document. For very large files, use Salesforce Files Connect with external storage.
Trust & references
Cross-checked against the following references.
- ContentDocument Object ReferenceSalesforce Developers
- Salesforce Files OverviewSalesforce Help
Straight from the source - Salesforce's reference material on Content Document.
- ContentVersion Object ReferenceSalesforce Developers
- ContentDocumentLink Object ReferenceSalesforce Developers
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…