Pick the right storage: Cache vs Properties

Apps Script gives every project a few small storage services, and they look interchangeable until you pick the wrong one. Each has a different lifetime, size ceiling, and speed, and choosing badly leads to data that vanishes when you needed it, or quota errors when a service fills up.

The decision comes down to two questions: how long does the data need to live, and how big is it. This guide maps each service to the jobs it actually suits, so you can match the storage to the task instead of guessing.

Comparison

The four places a script can keep data trade off speed against permanence and capacity. Cache is fastest but temporary; Sheets and Drive are durable but slow.

Service	Lifetime	Size limit	Speed
CacheService	up to 6 hours	100KB/key	fast
PropertiesService	until deleted	9KB/key, 500KB total	medium
Spreadsheet cells	until deleted	huge	slow
Drive blobs	until deleted	huge	slow

A few details worth knowing behind the table:

• Cache may evict a key before its expiry if the cache is under pressure — treat anything in it as a speed-up, never as a source of truth.
• Properties come in three scopes — script, document, and user — each with its own 500KB budget.
• Cache and Properties both store strings only. Objects must be run through JSON.stringify on the way in and JSON.parse on the way out.

Use each for

The right service is the cheapest one whose lifetime and size fit the data. Start from the question “would it matter if this disappeared?”

• Cache: data you can afford to lose and recompute — API response memoisation, rate-limit tokens, ephemeral state shared between runs.
• Properties: small, durable configuration — API keys, settings, counters, last-run timestamps, continuation cursors.
• Sheets: structured data you also want to read or edit by hand, and any append-only record such as a log or audit trail.
• Drive blobs: anything large — JSON snapshots, exports, generated files — that would overflow the Properties or Cache limits.

A common pattern uses two together: keep the API key in Properties, and cache the response it fetches. The durable thing lives in Properties; the disposable thing lives in Cache.

function getExchangeRate() {
  const cache = CacheService.getScriptCache();
  // 1. Try the cache first — avoids the network call entirely on a hit.
  const cached = cache.get('usd_eur');
  if (cached) return Number(cached);

  // 2. Cache miss — read the durable API key from Properties and fetch.
  const key = PropertiesService.getScriptProperties().getProperty('FX_API_KEY');
  const rate = fetchRate(key);

  // 3. Store the result for an hour (3600s) so later runs skip the fetch.
  cache.put('usd_eur', String(rate), 3600);
  return rate;
}

Anti-patterns

Most storage bugs come from using a service for something it was not built for. The lifetime and size limits are not suggestions — the service will drop data or throw a quota error when you cross them.

• Don’t put secrets in cache. Cache contents are not encrypted and can be evicted at any time — keys and tokens belong in Properties.
• Don’t put live data in properties. The 500KB total budget fills up fast; Properties is for small config, not a database.
• Don’t write logs to properties. Append-only data grows without limit — it belongs in a Sheet, where it can also be read and filtered by hand.
• Don’t rely on cache as a source of truth. A key can expire or be evicted early; always have a fallback that recomputes the value.
• Don’t store raw objects. Both Cache and Properties hold strings only — forgetting to stringify silently saves the text [object Object].