Home Guides Reference Samples Support Add-ons Apps Script API

Properties Service

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:

service/propertyService.gs
// Set a property in each of the three property stores.
var scriptProperties = PropertiesService.getScriptProperties();
var userProperties = PropertiesService.getUserProperties();
var documentProperties = PropertiesService.getDocumentProperties();

scriptProperties.setProperty('SERVER_URL', 'http://www.example.com/');
userProperties.setProperty('DISPLAY_UNITS', 'metric');
documentProperties.setProperty('SOURCE_DATA_ID', '1234567890abcdefghijklmnopqrstuvwxyz');

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:

service/propertyService.gs
// Set multiple script properties in one call.
var scriptProperties = PropertiesService.getScriptProperties();
scriptProperties.setProperties({
  'cow': 'moo',
  'sheep': 'baa',
  'chicken': 'cluck'
});

Reading data

To retrieve a single value that you have previously saved, call Properties.getProperty(key):

service/propertyService.gs
// Get the value for the user property 'DISPLAY_UNITS'.
var userProperties = PropertiesService.getUserProperties();
var units = userProperties.getProperty('DISPLAY_UNITS');

To retrieve all values in the current property store, call Properties.getProperties():

service/propertyService.gs
// Get multiple script properties in one call, then log them all.
var scriptProperties = PropertiesService.getScriptProperties();
var data = scriptProperties.getProperties();
for (var key in data) {
  Logger.log('Key: %s, Value: %s', key, data[key]);
}

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:

service/propertyService.gs
// Change the unit type in the user property 'DISPLAY_UNITS'.
var userProperties = PropertiesService.getUserProperties();
var units = userProperties.getProperty('DISPLAY_UNITS');
units = 'imperial'; // Only changes local value, not stored value.
userProperties.setProperty('DISPLAY_UNITS', units); // Updates stored value.

Deleting data

To delete a single value, call Properties.deleteProperty(key):

service/propertyService.gs
// Delete the user property 'DISPLAY_UNITS'.
var userProperties = PropertiesService.getUserProperties();
userProperties.deleteProperty('DISPLAY_UNITS');

To delete all properties in the current store, call Properties.deleteAllProperties():

service/propertyService.gs
// Delete all user properties in the current script.
var userProperties = PropertiesService.getUserProperties();
userProperties.deleteAllProperties();