Abstract
In this report, the detailed specification of PropertiesService has been investigated. It is considered that knowing this specification will be useful for developing applications with Google Apps Script. As a result, it was found that the maximum key and value sizes are 524,287 bytes with a 1-byte key and 8,066 bytes, respectively. And also, it was found that the maximum size of PropertiesService is required to be considered with both the key and value sizes.
Introduction
This is a report for investigating the detailed specification of PropertiesService. The specification of PropertiesService has already been published in the official document. When I use this, I was looking for the detailed specification of this. However, it seems that the detailed specification has not been published. From this situation, it is considered that when the detailed specification is investigated and published, it will be useful for a lot of developers. With this motivation, the detailed specification of PropertiesService was investigated.
This result is for May 22, 2023. The specification might be changed with the future update on the Google side. Please be careful about this.
Confirmation of official document
In the current stage, the official document of Quotas for Google Services says as follows.
| Feature | Value |
|---|---|
| Properties value size | 9 KB / val |
| Properties total storage | 500 KB / property store |
From this table, it is found that the size of the value size of each property and the total storage of properties are 9 kB and 500 kB, respectively. When the official documents of “Class PropertiesService” and “guide to the Properties service”, unfortunately, no further information about the detailed specification couldn’t be found.
Experimental procedure
In this report, as the experimental procedure for investigating the specification of PropertiesService, the following tests were run.
- Maximum value size of a single property.
- Maximum key size of a single property.
- Maximum number of properties.
- Difference between
PropertiesService.getScriptProperties(),PropertiesService.getUserProperties(),PropertiesService.getDocumentProperties().
The results obtained by these 4 tests are compared with the values on the official document.
Results and discussion
1. Maximum value size of a single property
The sample script is as follows.
function sample1() {
const n = 524287;
const key = "a";
const value = Array(n).fill("a").join("");
console.log(value.length); // 524287
const p = PropertiesService.getScriptProperties();
p.setProperty(key, value);
const res = p.getProperty(key);
console.log(res.length); // 524287
}
In this sample, the key size is 1 byte. Because the empty key occurs an error like Exception: When setting or getting a property value, the property name must not be null or empty. When this script is run, the script works fine, and a single property with a key of 1 byte and a value of 524,287 bytes is created. When n is changed to 524,288 bytes, an error like Exception: You have exceeded the property storage quota. Please remove some properties and try again. occurs. From this result, it was found that the maximum value size of a single property is 524,287 bytes.
By the way, 1 byte of the key size and 524,287 bytes of the value size are summed, it’s 524,288 bytes. 524,288 bytes are 512 kB. It is considered that in the case of PropertiesService, the total size of both key and value is the maximum size of 524,288 bytes (512 kB).
As an additional test, when p.setProperty("b", "") is inserted just after the line of const res = p.getProperty(key); under const n = 524287, an error of Exception: You have exceeded the property storage quota. Please remove some properties and try again. occurred. From this result, it is considered that the maximum number of properties depends on the total size of keys and values.
2. Maximum key size of a single property
The sample script is as follows.
function sample2() {
const n = 8066;
const key = Array(n).fill("a").join("");
const value = "";
console.log(key.length); // 8066
const p = PropertiesService.getScriptProperties();
p.setProperty(key, value);
const res = p.getKeys()[0];
console.log(res.length); // 8066
}
In this sample, the value size is 0 bytes. It seems that a 0-byte key size cannot be used. When this script is run, the script works fine, and a single property with a key of 8,066 bytes and no value is created. When n is changed to 8,067 bytes, an error like Exception: Data storage error occurs. From this result, it was found that the maximum key size of a single property is 8,066 bytes.
3. Maximum number of properties
From the results of sections 1 and 2, the following results were obtained.
- At least, the key size is required to be more than 1 byte.
- Maximum key and value sizes are 524,287 bytes with 1-byte key and 8,066 bytes, respectively.
- Total size of both key and value is the maximum size of 524,288 bytes (512 kB). Namely, the maximum size of PropertiesService is required to be considered with both the key and value sizes.
From these results, for example, when the keys of the size of the key with an empty value is the numbers from 0 to x increasing by 1 are used, it was found that 105,899 properties could be created. At this time, the total size of both keys and values is 524,284. This is less than the maximum size of 524,288 bytes. From this result, it is considered that when the numbers and the string values are used as the keys under the total size is less than 524,288 bytes, more properties can be created.
As an additional test, when the key size and the value size are constant like 6 bytes and 4 bytes, respectively, it was found that 52,428 properties could be created. In this case, 52,428 x 10 = 524,280 bytes. And, when the key size and the value size are constant like 6 bytes and 14 bytes, respectively, it was found that 26,214 properties could be created. In this case, 26,214 x 20 = 524,280 bytes. The sizes of both results are less than the maximum size of 524,288 bytes.
From these results, it is considered that no maximum number of properties might be.
4. Difference between PropertiesService.getScriptProperties(), PropertiesService.getUserProperties(), PropertiesService.getDocumentProperties()
It was found that the above results are the same between PropertiesService.getScriptProperties(), PropertiesService.getUserProperties(), PropertiesService.getDocumentProperties().
5. Sample script: Obtaining the remaining capacity of PropertiesService
When the results of the above 1 to 4 sections are used, it is considered that a script for obtaining the remaining capacity of PropertiesService can be created. The sample script is as follows.
/**
* ### Description
* Retrieve the remaining capacity of current properties.
*
* @param {Object} prop PropertiesService.Properties
* @return {Object} An object including the usage, the limitation, and the remaining capacity.
*/
function getRemainingCapacityOfProperties_(prop) {
const limit = 524288; // [bytes] This value was investigated on May 21, 2023.
const obj = prop.getProperties();
const usage = Object.entries(obj).reduce(
(c, [k, v]) => (c += k.length + v.length),
0
);
return {
unit: "bytes",
usage,
limit,
remaining: limit - usage,
usage_percentage: Number(((usage / limit) * 100).toFixed(5)),
};
}
// Please run this function.
function sample() {
const prop = PropertiesService.getScriptProperties();
const res = getRemainingCapacityOfProperties_(prop);
console.log(res);
}
When sample function is run, the remaining capacity of the current PropertiesService is returned. The sample output value is as follows.
{
"unit": "bytes",
"usage": 356448,
"limit": 524288,
"remaining": 167840,
"usage_percentage": 67.98706
}
Summary
From this investigation, the following table with the detailed specification of PropertiesService could be created.
| Feature | Value |
|---|---|
| Minumum value size | 0 bytes |
| Maximum value size | 524,287 bytes at 1-byte key size (In this case, only one property can be created.) |
| Minumum key size | 1 byte |
| Maximum key size | 8,066 bytes |
| Properties total storage | 512 KB (524,288 bytes) / property store |
| Maximum number of properties | None |
| getScriptProperties(), getUserProperties(), getDocumentProperties() | Same specification |
- Total size of both key and value is the maximum size of 524,288 bytes (512 kB). Namely, the maximum size of PropertiesService is required to be considered with both the key and value sizes.
- Using these results, a script for obtaining the remaining capacity of PropertiesService could be proposed.