Platform Cache
Platform Cache is a Salesforce feature that stores frequently used data in memory on the Lightning Platform, so your Apex code can read it back fast instead of recomputing it or running the same SOQL query again.
Definition
Platform Cache is a Salesforce feature that stores frequently used data in memory on the Lightning Platform, so your Apex code can read it back fast instead of recomputing it or running the same SOQL query again. It comes in two flavors. Org cache holds data that every user and process in the org can read, and session cache holds data scoped to a single user's session.
You allocate Platform Cache capacity into named partitions, then read and write values through the Cache namespace classes in Apex. Each cached value has a time-to-live, after which it expires. Because the platform can also evict entries early when space runs low, cache is a speed boost, not a source of truth.
How Platform Cache stores and serves your data
Org cache versus session cache
Platform Cache splits into two stores that behave differently. Org cache is shared. Any user, trigger, or batch job in the org can write to it and read from it, which makes it the right home for data that looks the same for everyone. Think reference data, configuration pulled from custom metadata, or the result of an expensive aggregate query that many users hit. Session cache is private to one user's session. Only that session can read or write its entries, and the data is gone when the session ends. It suits per-user state like a multi-step wizard's progress or a costly calculation tied to the running user. The time-to-live limits differ too. Org cache values can live up to 48 hours, with a default of 24 hours when you do not specify one. Session cache values can live up to 8 hours, which is also the default, and never outlast the session itself. Choosing the wrong store is a common mistake. Putting shared lookup data in session cache means every user pays to rebuild it, while putting user-specific data in org cache risks one person seeing another person's values.
Partitions carve up the capacity
You do not write to "the cache" directly. Capacity is divided into partitions, and each partition gets its own slice of org-cache and session-cache space measured in megabytes. Partitions keep one application's data from crowding out another's. A heavy reporting feature and a lightweight settings cache can each get their own partition, so a spike in one does not evict the other. Every org has a default partition, and you can mark one partition as the default so code that does not name a partition still works. In Apex you target a partition by name using a prefix like local.MyPartition before the key, or by getting a partition object with Cache.Org.getPartition. The free capacity available depends on your edition. Enterprise, Unlimited, and Performance editions include a base allocation, Developer Edition gets a small amount for building and testing, and you can buy more or request a trial. If a partition has zero capacity allocated, puts to it silently do nothing, which surprises developers who forgot to allocate space.
The Cache namespace and how you call it
All access runs through the Cache namespace in Apex. For org cache you use Cache.Org and Cache.OrgPartition; for session cache you use Cache.Session and Cache.SessionPartition. The pattern is the same across both: put a value under a string key, get it back later, contains to check presence, and remove to evict it. A put can take an optional TTL in seconds and a visibility setting. A worked example helps. Say a Visualforce page or LWC controller needs a country-to-currency map that rarely changes. On the first request your Apex checks Cache.Org.get on a key like local.RefData.currencyMap. On a miss it runs the SOQL, stores the result with a put and a TTL of a few hours, and returns it. Every later request inside that window skips the query entirely and reads from memory. Keys must be alphanumeric, are capped at 50 characters, and a single cached object cannot exceed 100 KB. Values you store must be serializable, so you cannot cache things like an open database cursor or certain system types.
CacheBuilder removes the cache-miss boilerplate
Writing the check-miss-compute-store dance by hand is repetitive and easy to get wrong. The CacheBuilder interface solves this. You implement a single doLoad method that knows how to compute the value for a given key, and the platform calls it only when the value is absent or expired. Your calling code just asks for the value and never writes the miss-handling logic itself. This matters for correctness as much as convenience. With CacheBuilder, a cache miss can never return null by accident, because the platform always runs your loader to populate it. That avoids a classic bug where code reads from cache, gets nothing back because the entry was evicted, and then treats the empty result as real data. CacheBuilder also centralizes the TTL and the compute logic in one class, so refreshing the strategy later touches one place. For most production caching of org data, Salesforce points developers to CacheBuilder rather than raw put and get calls, precisely because it makes eviction safe to handle.
Eviction, expiry, and why cache is never truth
Two forces remove data from Platform Cache. The first is expiry: once a value passes its TTL, it is gone. The second is eviction under pressure. When a partition fills up, the platform drops the least recently used entries to make room, even if their TTL has not elapsed. This means any get can come back empty at any time, regardless of how long ago you stored the value. Your code must always handle the miss. The practical rule is that cache improves speed but never guarantees presence. Never store a value in cache and assume it will still be there on the next request, and never use cache as the only copy of data you cannot recompute. If the cached value drives a decision, you also have to think about staleness. A value cached for 24 hours can be 24 hours out of date, so cache data that changes slowly and tolerate the lag, or shorten the TTL when freshness matters. Sensitive data deserves extra care because org cache is readable by every process in the org.
When Platform Cache earns its keep
Platform Cache pays off when the same expensive work repeats across requests. Good candidates are read-heavy and change rarely: pricing tables, currency or tax lookups, navigation or menu structures, feature configuration, and aggregate counts that would otherwise force a heavy SOQL query on every page load. Caching these can cut response times and reduce pressure on SOQL governor limits, since a cache hit is not a query. It is the wrong tool in a few cases. Data that changes constantly will be stale before it is useful, and caching it wastes space. Data that is cheap to fetch gains little, because the cache lookup itself has a cost. Caching as a workaround for a poorly written query is a smell; fix the query first. And because partition capacity is finite, caching large or rarely reused objects can evict more valuable entries. The strongest pattern is small, hot, slow-changing data behind a CacheBuilder, with a TTL chosen to match how fresh that data really needs to be.
Set up a Platform Cache partition
Before any Apex can store values, an admin allocates Platform Cache capacity into a partition. You do this once in Setup, then reference the partition by name from code.
- Open Platform Cache in Setup
In Setup, enter Platform Cache in the Quick Find box and open it. The page shows your org's total cache capacity, how much is allocated, and any existing partitions.
- Create a new partition
Click New Platform Cache Partition. Give it a name that matches how you will reference it in Apex, such as RefData, and optionally a label and description.
- Allocate org and session capacity
Enter how many megabytes of Org Cache and Session Cache this partition should hold. The combined allocation across all partitions cannot exceed your org's total capacity.
- Set the default partition if needed
Mark one partition as the default so Apex calls that do not name a partition resolve to it. Save the partition to make it available to your code.
Memory reserved for data shared across all users and processes. A partition with 0 MB here silently ignores org-cache puts.
Memory reserved for per-user session data. Session values expire when the session ends, up to an 8-hour maximum TTL.
When checked, this partition handles Cache.Org and Cache.Session calls that omit a partition name. Only one partition can be the default.
- A partition with zero allocated capacity accepts put calls without error but stores nothing, so reads always miss.
- Total allocation across every partition is capped at your org's purchased plus free capacity; you cannot over-allocate.
- Developer Edition includes only a small free allocation, so test cache-miss paths there rather than assuming hits.
Prefer this walkthrough as its own page? How to Platform Cache in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Platform Cache.
Hands-on resources to go deeper on Platform Cache.
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.
Test your knowledge
Q1. What does Platform Cache do for Salesforce application performance?
Q2. What is the difference between Org Cache and Session Cache in Platform Cache?
Q3. When should an Apex developer reach for Platform Cache instead of repeating a SOQL query?
Discussion
Loading discussion…