Apex Blob And ContentVersion

Use this skill when Apex is the producer or consumer of binary file data — creating Files (ContentVersion), relating them to records (ContentDocumentLink), or moving Blobs between heap, DML, and callouts. The purpose is to keep the transaction under the heap ceiling, land the file under the right sharing, and avoid silent truncation when payloads are larger than they look.

Before Starting

Gather this context before touching ContentVersion, ContentDocumentLink, or raw Blob DML:

• Expected file size — under 3 MB, 3–12 MB, 12 MB+? Synchronous Apex has a 6 MB heap ceiling; async (Queueable, Batch, Future) has 12 MB. ContentVersion itself supports up to 2.1 GB, but you cannot land one through a single synchronous insert if the Blob is already in heap.
• Sharing model for the file — public to all internal users (AllUsers), tied to a record (inferred via ContentDocumentLink), or private to the uploader? The ShareType and Visibility flags on ContentDocumentLink are the control plane, not ContentVersion itself.
• Round-trip requirements — does the file need to come back down from Apex unchanged? If so, any intermediate Blob.toString() conversion will corrupt non-UTF-8 bytes.
• Transaction boundary — DML that inserts ContentVersion counts toward your DML row limit. Chained inserts of 50 large files exhaust heap well before the DML cap.

Core Concepts