Class Cache
Page Summary
The Cache class is used to insert, retrieve, and remove items from a cache, useful for speeding up access to expensive or slow resources.
Data can be added to the cache using
putorputAllmethods, with optional expiration times.Cached values can be retrieved using the
getorgetAllmethods.Entries can be removed from the cache using the
removeorremoveAllmethods.Individual keys can be up to 250 characters and store up to 100KB of data, with a cache item cap of 1,000 entries.
A reference to a particular cache.
This class allows you to insert, retrieve, and remove items from a cache. This can beparticularly useful when you want frequent access to an expensive or slow resource. For example,say you have an RSS feed at example.com that takes 20 seconds to fetch, but you want to speed upaccess on an average request.
functiongetRssFeed(){constcache=CacheService.getScriptCache();constcached=cache.get('rss-feed-contents');if(cached!=null){returncached;}constresult=UrlFetchApp.fetch('http://example.com/my-slow-rss-feed.xml');// takes 20 secondsconstcontents=result.getContentText();cache.put('rss-feed-contents',contents,1500);// cache for 25 minutesreturncontents;}
Methods
| Method | Return type | Brief description |
|---|---|---|
get(key) | String | Gets the cached value for the given key, ornull if none is found. |
get | Object | Returns a JavaScript Object containing all key/value pairs found in the cache for an array ofkeys. |
put(key, value) | void | Adds a key/value pair to the cache. |
put(key, value, expirationInSeconds) | void | Adds a key/value pair to the cache, with an expiration time (in seconds). |
put | void | Adds a set of key/value pairs to the cache. |
put | void | Adds a set of key/value pairs to the cache, with an expiration time (in seconds). |
remove(key) | void | Removes an entry from the cache using the given key. |
remove | void | Removes a set of entries from the cache. |
Detailed documentation
get(key)
Gets the cached value for the given key, ornull if none is found.
// Gets the value from the cache for the key 'foo'.constvalue=CacheService.getScriptCache().get('foo');
Parameters
| Name | Type | Description |
|---|---|---|
key | String | the key to look up in the cache |
Return
String — the cached value, or null if none was found
getAll(keys)
Returns a JavaScript Object containing all key/value pairs found in the cache for an array ofkeys.
// Gets a set of values from the cacheconstvalues=CacheService.getDocumentCache().getAll(['foo','x','missing']);// If there were values in the cache for 'foo' and 'x' but not 'missing', then// 'values' would be: {'foo': 'somevalue', 'x': 'othervalue'}
Parameters
| Name | Type | Description |
|---|---|---|
keys | String[] | the keys to lookup |
Return
Object — a JavaScript Object containing the key/value pairs for all keys found in the cache
See also
put(key, value)
Adds a key/value pair to the cache.
The maximum length of a key is 250 characters. The maximum amount of data that can be storedper key is 100KB. The value expires from the cache after 600 seconds (10 minutes).
The cap for cached items is 1,000. If more than 1,000 items are written, the cache storesthe 900 items farthest from expiration. This limit might change.
constcache=CacheService.getScriptCache();// Puts the value 'bar' into the cache using the key 'foo'cache.put('foo','bar');
Parameters
| Name | Type | Description |
|---|---|---|
key | String | the key to store the value under |
value | String | the value to be cached |
put(key, value, expirationInSeconds)
Adds a key/value pair to the cache, with an expiration time (in seconds).
The maximum length of a key is 250 characters. The maximum amount of data that can be storedper key is 100KB. The specified expiration time is only a suggestion; cached data may beremoved before this time if a lot of data is cached.
The cap for cached items is 1,000. If more than 1,000 items are written, the cache storesthe 900 items farthest from expiration. This limit might change.
// Puts the value 'bar' into the cache using the key 'foo', but only for the// next 20 seconds.CacheService.getScriptCache().put('foo','bar',20);
Parameters
| Name | Type | Description |
|---|---|---|
key | String | the key to store the value under |
value | String | the value to be cached |
expiration | Integer | the maximum time the value remains in the cache, in seconds. The minimum is 1 second and the maximum is 21600 seconds (6 hours). |
putAll(values)
Adds a set of key/value pairs to the cache.
Similar to repeated calls to "put", but more efficient as it only makes one call to thememcache server to set all values. The maximum length of a key is 250 characters. The maximumamount of data that can be stored per key is 100KB. The values will expire from the cache after600 seconds (10 minutes).
The cap for cached items is 1,000. If more than 1,000 items are written, the cache storesthe 900 items farthest from expiration. This limit might change.
// Puts a set of values into the cache with the keys 'foo', 'x', and 'key'.constvalues={foo:'bar',x:'y',key:'value',};CacheService.getUserCache().putAll(values);
Parameters
| Name | Type | Description |
|---|---|---|
values | Object | a JavaScript Object containing string keys and values |
See also
putAll(values, expirationInSeconds)
Adds a set of key/value pairs to the cache, with an expiration time (in seconds).
Similar to repeated calls to "put", but more efficient as it only makes one call to thememcache server to set all values. The maximum length of a key is 250 characters. The maximumamount of data that can be stored per key is 100KB. The specified expiration time is only asuggestion; cached data may be removed before this time if a lot of data is cached.
The cap for cached items is 1,000. If more than 1,000 items are written, the cache storesthe 900 items farthest from expiration. This limit might change.
// Puts a set of values into the cache with the keys 'foo', 'x', and 'key'.constvalues={foo:'bar',x:'y',key:'value',};CacheService.getUserCache().putAll(values,20);
Parameters
| Name | Type | Description |
|---|---|---|
values | Object | A JavaScript Object containing string keys and values |
expiration | Integer | The maximum time the value remains in the cache, in seconds The minimum allowed expiration is 1 second, and the maximum allowed expiration is 21600 seconds (6 hours). The default expiration is 600 seconds (10 minutes). |
See also
remove(key)
Removes an entry from the cache using the given key.
// Removes any cache entries for 'foo'CacheService.getUserCache().remove('foo');
Parameters
| Name | Type | Description |
|---|---|---|
key | String | the key to remove from the cache |
removeAll(keys)
Removes a set of entries from the cache.
// Removes entries from the cache with keys 'foo' and 'x'CacheService.getDocumentCache().removeAll(['foo','x']);
Parameters
| Name | Type | Description |
|---|---|---|
keys | String[] | the array of keys to remove |
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-11 UTC.