Class Cache

Cache

A reference to a particular cache.

This class allows you to insert, retrieve, and remove items from a cache. This can be particularly 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 up access on an average request.

 function 
  
 getRssFeed 
 () 
  
 { 
  
 var 
  
 cache 
  
 = 
  
 CacheService 
 . 
 getScriptCache 
 (); 
  
 var 
  
 cached 
  
 = 
  
 cache 
 . 
 get 
 ( 
 "rss-feed-contents" 
 ); 
  
 if 
  
 ( 
 cached 
  
 != 
  
 null 
 ) 
  
 { 
  
 return 
  
 cached 
 ; 
  
 } 
  
 var 
  
 result 
  
 = 
  
 UrlFetchApp 
 . 
 fetch 
 ( 
 "http://example.com/my-slow-rss-feed.xml" 
 ); 
  
 // 
  
 takes 
  
 20 
  
 seconds 
  
 var 
  
 contents 
  
 = 
  
 result 
 . 
 getContentText 
 (); 
  
 cache 
 . 
 put 
 ( 
 "rss-feed-contents" 
 , 
  
 contents 
 , 
  
 1500 
 ); 
  
 // 
  
 cache 
  
 for 
  
 25 
  
 minutes 
  
 return 
  
 contents 
 ; 
 }
You'll still need to wait the 20 seconds if the item is not in the cache, but subsequent calls will be very fast until the item expires out of the cache in 25 minutes.

Methods

Method Return type Brief description
get(key)
String Gets the cached value for the given key, or null if none is found.
getAll(keys)
Object Returns a JavaScript Object containing all key/value pairs found in the cache for an array of keys.
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).
putAll(values)
void Adds a set of key/value pairs to the cache.
putAll(values, expirationInSeconds)
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.
removeAll(keys)
void Removes a set of entries from the cache.

Detailed documentation

get(key)

Gets the cached value for the given key, or null if none is found.

 // 
  
 Gets 
  
 the 
  
 value 
  
 from 
  
 the 
  
 cache 
  
 for 
  
 the 
  
 key 
  
 'foo' 
 . 
 var 
  
 value 
  
 = 
  
 cache 
 . 
 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 of keys.

 // 
  
 Gets 
  
 a 
  
 set 
  
 of 
  
 values 
  
 from 
  
 the 
  
 cache 
 var 
  
 values 
  
 = 
  
 cache 
 . 
 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 stored per key is 100KB. The value will expire 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 stores the 900 items farthest from expiration. This limit might change.

 // 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 stored per key is 100KB. The specified expiration time is only a suggestion; 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 stores the 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. 
 cache 
 . 
 put 
 ( 
 'foo' 
 , 
  
 'bar' 
 , 
  
 20 
 );

Parameters

Name Type Description
key
String the key to store the value under
value
String the value to be cached
expirationInSeconds
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 the memcache server to set all values. The maximum length of a key is 250 characters. The maximum amount of data that can be stored per key is 100KB. The values will expire 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 stores the 900 items farthest from expiration. This limit might change.

 // 
  
 Puts 
  
 a 
  
 set 
  
 of 
  
 values 
  
 into 
  
 the 
  
 cache 
  
 with 
  
 the 
  
 keys 
  
 'foo' 
 , 
  
 'x' 
 , 
  
 and 
  
 'key' 
 . 
 var 
  
 values 
  
 = 
  
 { 
  
 'foo' 
 : 
  
 'bar' 
 , 
  
 'x' 
 : 
 'y' 
 , 
  
 'key' 
 : 
  
 'value' 
 }; 
 cache 
 . 
 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 the memcache server to set all values. The maximum length of a key is 250 characters. The maximum amount of data that can be stored per key is 100KB. The specified expiration time is only a suggestion; 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 stores the 900 items farthest from expiration. This limit might change.

 // 
  
 Puts 
  
 a 
  
 set 
  
 of 
  
 values 
  
 into 
  
 the 
  
 cache 
  
 with 
  
 the 
  
 keys 
  
 'foo' 
 , 
  
 'x' 
 , 
  
 and 
  
 'key' 
 . 
 var 
  
 values 
  
 = 
  
 { 
  
 'foo' 
 : 
  
 'bar' 
 , 
  
 'x' 
 : 
 'y' 
 , 
  
 'key' 
 : 
  
 'value' 
 }; 
 cache 
 . 
 putAll 
 ( 
 values 
 , 
  
 20 
 );

Parameters

Name Type Description
values
Object A JavaScript Object containing string keys and values
expirationInSeconds
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' 
 cache 
 . 
 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' 
 cache 
 . 
 removeAll 
 ([ 
 'foo' 
 , 
  
 'x' 
 ]);

Parameters

Name Type Description
keys
String[] the array of keys to remove