The Properties service lets you store simple data in key-value pairs scoped to one script, one user of a script, or one document in which an add-on is used. It is typically used to store developer configuration or user preferences. Properties are never shared between scripts.
Comparison of property stores
The
PropertiesService
global object offers three methods, each of which returns a similar
Properties
object but with different access rights, as shown in the following table:
Script Properties | User Properties | Document Properties | |
---|---|---|---|
Method to access | getScriptProperties() |
getUserProperties() |
getDocumentProperties() |
Data shared among | All users of a script, add-on, or web app | The current user of a script, add-on, or web app | All users of an add-on in the open document |
Typically used for | App-wide configuration data, like the username and password for the developer's external database | User-specific settings, like metric or imperial units | Document-specific data, like the source URL for an embedded chart |
Data format
The Properties service stores all data as strings in key-value pairs. Data types that are not already strings are automatically converted to strings, including methods contained within saved objects.
Saving data
To save a single value, call the method Properties.setProperty(key,
value)
of the appropriate store, as shown in the following example:
To save data in bulk, pass a map of key-value pairs to
Properties.setProperties(properties)
.
Each key-value pair of the object in the parameter is stored as a separate
property:
Reading data
To retrieve a single value that you have previously saved, call
Properties.getProperty(key)
:
To retrieve all values in the current property store, call
Properties.getProperties()
:
Modifying data
The methods getProperty()
and getProperties()
return a copy of the stored
data, not a live view, so changing the returned object will not update the value
in the property store. To update the data in the store, simply save it again:
Deleting data
To delete a single value, call
Properties.deleteProperty(key)
:
To delete all properties in the current store, call
Properties.deleteAllProperties()
: