Skip to content

Basics

CacheService, PropertiesService, and LockService

PropertiesService keeps small text settings across runs, CacheService speeds up repeat reads for up to six hours, and LockService keeps two runs from colliding.

1 of 3

Each service solves a different coordination problem

Scripts that run on triggers or serve multiple people need three distinct tools: a place to keep durable settings, a fast scratchpad for repeat lookups, and a traffic light so two runs do not overwrite each other.

  • PropertiesService stores small string key-value pairs until code or an editor deletes them. Each value holds up to 9 KB and each store holds up to 500 KB.
  • CacheService stores temporary string entries up to 100 KB per key for 1 second to 21,600 seconds (6 hours). Entries can be evicted early, so code must always be ready to recompute or refetch on a cache miss.
  • LockService serializes critical sections across concurrent executions so only one run enters the protected block at a time.

2 of 3

Script, user, and document scopes

All three services offer script, user, and document partitions, and picking the wrong partition either leaks data across users or fails with null.

  • Script scope (getScriptProperties, getScriptCache, getScriptLock) is shared by every execution of that script project. Note that an attached Apps Script library has its own separate script store and lock, independent of the caller.
  • User scope (getUserProperties, getUserCache, getUserLock) isolates data or locks to the effective account of the current execution, such as per-user OAuth tokens or personal preferences.
  • Document scope (getDocumentProperties, getDocumentCache, getDocumentLock) attaches to the open container file. In a standalone script with no container document, those methods return null.

3 of 3

Combine a cache check with a short lock

Acquire a lock before a read-modify-write update to PropertiesService or a shared sheet, and always call releaseLock() in a finally block so a thrown error never leaves later runs waiting.

Remember that time spent inside tryLock(timeoutInMillis) or waitLock(timeoutInMillis) counts toward the 6-minute execution limit.

Read from CacheService first and guard counter updates with LockService
function recordProcessedBatch() {
  const cache = CacheService.getScriptCache();
  let configText = cache.get('BATCH_LIMIT');
  if (configText === null) {
    configText = PropertiesService.getScriptProperties().getProperty('BATCH_LIMIT') ?? '25';
    cache.put('BATCH_LIMIT', configText, 600);
  }

  const lock = LockService.getScriptLock();
  if (!lock.tryLock(10000)) {
    Logger.log('Another execution holds the script lock. Skipping this run.');
    return;
  }

  try {
    const properties = PropertiesService.getScriptProperties();
    const total = Number(properties.getProperty('TOTAL_BATCHES') ?? '0') + 1;
    properties.setProperty('TOTAL_BATCHES', String(total));
    Logger.log('Recorded batch ' + total + ' with limit ' + configText + '.');
  } finally {
    lock.releaseLock();
  }
}

Remember

The short version

  • PropertiesService keeps strings until deleted (9 KB per key, 500 KB per store); CacheService holds up to 100 KB per key for at most 6 hours and can evict early.
  • Document properties, caches, and locks return null in standalone projects.
  • Libraries use their own ScriptProperties store rather than the calling project store.
  • Always release a LockService lock inside a finally block, and keep lock wait times well under the 6-minute execution limit.

Keep going

Put it to work

All basics