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:

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:

// 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:

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

Script properties can also be saved via the script editor user interface by going to File > Project properties and selecting the Project properties tab. User properties and document properties cannot be set or viewed in the user interface.

Reading data

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

// 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():

// 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:

// 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):

// 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():

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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.