The Property store has a limit of 9k on individual property items and, the cache store has 100k. You may also be using other stores for this kind of data with similar limitations. Let’s take a look at how to minimize that problem.


One way is to stringify the object, compress the result using zip, then converting the zip blob to base 64 so you can save it as a string. This will typically get you savings of about 60-70%, so that’s a good thing anyway. But eventually you’ll come across a case that the compressed object is still bigger than the limit.

Writing a master property and dependent chunks

Once you’ve created your compressed stringified object, and it still doesn’t fit, in place of the data being stored against your key, you can instead store an array of other keys pointing to other store entries which contain the the compressed data cut up into chunks. When you access the master, it will go off and find the contributing properties to reconstitute the original data.


The cUseful library has a function that manages all of this for you. Here’s the key, and it’s also on github


Here’s how to use it, first with the PropertiesService. The chunksize is the maximum amount of data that can be written to the store. For testing I’ve just set it to 500, although the Apps Script Properties Service maximum is 9k in real life.

Writing a property value

It compresses the object, and takes care of creating additional property entries if it finds it needs them. Even though you access entries using ‘yourKey’, it is not actually the key that’s written to the store, but instead derivatives of it are. Accessing its records directly won’t do you any good. Data written with Chunking needs to be read back with the Chunking so that it takes care of uncompressing and joining together any additional chunk entries it’s had to create.The size returned is the total size of all the compressed object chunks written.

Reading a property value

You’ll get back your reconstituted and parsed object like this.

Removing a property value

This gets rid of an entry, plus any dependent entries.

Keeping the store clean

If you already have a value against a key, it maybe that this is stored across several entries. When you replace it with a new value, the number of entries for the new value may be different than that required for the previous value. When you use setBigProperty, Chunking automatically removes all the previous entries for that key after inserting your new value. This avoids having a build up of redundant dependent entries.

Multi user access

When the record is compressed and fits on a single record, there is no different than with the standard uncompressed version. Since the property value can be potentially spread across multiple store entries, there is a chance that an update operation is in progress when that same property is accessed by someone else. In the case of an update, for example, the old entries are deleted and new ones created.

I’m not using the LockService (I could also have used Using named locks with Google Apps Scripts), since they both bring significant overhead into operations like these. To minimize the chance of multi-user issues when the property value needs to spread across multiple entries, these mitigations are in place

  • dependent entries each have a onetime unique key, which is stored in the master record, so there is no chance of mixing up entries from one update with another.
  • dependent entries are deleted after the master entry, so if the master entry was findable, then so should each of its dependents.
  • dependent entries are created before the master entry, so if the master entry exists, then so will its dependents.

Whether single or multiple entries are used should be invisible to you, and you can use your regular mitigations in your app to avoid clashes such as the Lock Service if you need to.

The digest

In order to avoid rewriting values that haven’t changed, Chunking maintains a digest of the contents of the current property value in the master entry. When you use setBigProperty, this digest is used to check if the value you are setting is the same as the value already written. If it is, then there’s no need for the removal of any previous dependent properties. You can know this has happened if setBigProperty returns 0 for the size of data it has written.

This behavior can be changed, if you always want to write a new value, even if it hasn’t changed, using the setRespectDigest method, as shown below. An example of why you might want to do this could be if you were using the CacheService, and wanted an update to refresh the expiration time.

What’s in the store

Normally of course, you wouldn’t need to care – just as you don’t care what the inside of a zip file looks like, but here’s how it works.

If the compressed version of a value is able to fit within the chunksize, then there’s only one record It looks something like this.

If it doesn’t fit, then the master entry contains information about where to get all the chunks and looks like this. The chunks object contains links to other property values, which when combined, will reconstitute the compressed value. It also contains the digest for the entire value which is used to avoid unnecessary setting of values when they haven’t actually changed.

and the last of the chunk entries looks like this.

Using a different store

By default, Chunking is expecting to use a properties store, but it doesn’t have any dependencies built in, and you can plug in your own functions to take care of the writing and reading to a different store.

Here’s how to set it up to use the CacheService instead of the PropertiesService

The methods starting with .func, allow you to redefine how to write, read and remove objects from a store. Since the CacheService use different methods than the property service, they need to be redefined as above. The default PropertiesService versions of functions that can be modified to handle different kinds of stores are shown below. You can reset any of these with the .func… pattern.


Here’s a test writing various random data, reading it back and making sure its the same. The compression gives 60-70% saving using these test parameters and the properties service and cache service appear to give similar performance. Here are the results

and the code.

The cUseful library contains this and many other things posted around this site.

Here’s the key, and it’s also on github


For more like this see Google Apps Scripts Snippets
Why not join our forum, follow the blog or follow me on twitter to ensure you get updates when they are available.