Google Apps Script

Class ScriptDbInstance

A JavaScript object database for permanently storing data. Use query(query) to retrieve items, save(item) to create or update them, and remove(item) to delete them. When modifying more than one item at a time use the batch methods. The methods that return QueryOperator are used for constructing query objects and do not initiate requets to the database.

Properties

PropertyTypeDescription
ASCENDINGSortDirectionAscending sort direction.
DESCENDINGSortDirectionDescending sort direction.
LEXICALSortStrategyLexical sort strategy.
NUMERICSortStrategyNumeric sort strategy.

Methods

MethodReturn typeBrief description
allOk(mutateResults)BooleanReturns true if all of the items in the result set were successful.
anyOf(values)QueryOperatorReturns a query operator that evaluates to true if the field's value matches any of the passed in values.
anyValue()QueryOperatorReturns a query operator that evaluates to true if the field has any value.
between(value1, value2)QueryOperatorReturns a query operator that evaluates to true if the field has a value in-between the two passed in values.
count(query)IntegerReturns the number of items that match the query.
greaterThan(value)QueryOperatorReturns a query operator that evaluates to true if the field's value is greater than the passed in value.
greaterThanOrEqualTo(value)QueryOperatorReturns a query operator that evaluates to true if the field's value is greater than or equal to the passed in value.
lessThan(value)QueryOperatorReturns a query operator that evaluates to true if the field's value is less than the passed in value.
lessThanOrEqualTo(value)QueryOperatorReturns a query operator that evaluates to true if the field's value is less than or equal to the passed in value.
load(id)ScriptDbMapLoads an item from the database by id.
load(ids)ScriptDbMap[]Loads items from the database by id.
not(value)QueryOperatorReturns a query operator that evaluates to true if the field's value does not match the passed in value.
query(query)ScriptDbResultQuery the database for matching items.
remove(item)voidRemoves an item from the database.
removeBatch(items, atomic)MutationResult[]Removes items from the database.
removeById(id)voidRemoves an item from the database by id.
removeByIdBatch(ids, atomic)MutationResult[]Removes items from the database by id.
save(item)ScriptDbMapSaves a new item to the database.
save(item)ScriptDbMapSaves an existing item to the database, updating it.
saveBatch(items, atomic)Object[]Saves items to the database.

Detailed documentation

allOk(mutateResults)

Returns true if all of the items in the result set were successful. This can be used to quickly check if your batch mutation operation had any problems.

 
var results = db.saveBatch(itemsToSave, false);
 if (db.allOk(results)) {
   // All of the items were saved, continue on.
 } else {
   // Some items failed to save, handle them first.
 }
 

Parameters

NameTypeDescription
mutateResultsObject[]the results from a batch mutation operation

Return

Boolean — true if all the items were successful, false if any item failed


anyOf(values)

Returns a query operator that evaluates to true if the field's value matches any of the passed in values.

 
var db = ScriptDb.getMyDb();
 // Find people with the name "fred", "barney", or "mark".
 var results = db.query({
   type: 'person',
   name: db.anyOf(['fred', 'barney', 'mark'])
 });
 while (results.hasNext()) {
   var item = results.next();
   // Do something with the item.
 }
 

Parameters

NameTypeDescription
valuesObject[]the values to compare with

Return

QueryOperator — a query operator to be used in a query object


anyValue()

Returns a query operator that evaluates to true if the field has any value. Items that don't have the field, or have a null value for that field, will not be matched.

 
var db = ScriptDb.getMyDb();
 // Find people with an eye color specified.
 var results = db.query({
   type: 'person',
   eyeColor: db.anyValue()
 });
 while (results.hasNext()) {
   var item = results.next();
   // Do something with the item.
 }
 

Return

QueryOperator — a query operator to be used in a query object


between(value1, value2)

Returns a query operator that evaluates to true if the field has a value in-between the two passed in values. This operator only applies to numerical values.

 
var db = ScriptDb.getMyDb();
 // Find people who are 13 or older but younger than 25.
 var results = db.query({
   type: 'person',
   age: db.between(13, 25)
 });
 while (results.hasNext()) {
   var item = results.next();
   // Do something with the item.
 }
 

Parameters

NameTypeDescription
value1Objectthe inclusive lower bound
value2Objectthe exclusive upper bound

Return

QueryOperator — a query operator to be used in a query object


count(query)

Returns the number of items that match the query. This accepts the same query objects as the query(query) method.

 
var db = ScriptDb.getMyDb();
 // Log the number of people with the name "fred" and age 25.
 var results = db.count({
   type: 'person',
   name: 'fred',
   age: 25
 });
 Logger.log(results);
 

Parameters

NameTypeDescription
queryObjecta query object

Return

Integer — the number of items that match the query


greaterThan(value)

Returns a query operator that evaluates to true if the field's value is greater than the passed in value. This operator only applies to numerical values.

 
var db = ScriptDb.getMyDb();
 // Find people with an age greater than 40.
 var results = db.query({
   type: 'person',
   age: db.greaterThan(40)
 });
 while (results.hasNext()) {
   var item = results.next();
   // Do something with the item.
 }
 

Parameters

NameTypeDescription
valueObjectthe value to compare with

Return

QueryOperator — a query operator to be used in a query object


greaterThanOrEqualTo(value)

Returns a query operator that evaluates to true if the field's value is greater than or equal to the passed in value. This operator only applies to numerical values.

 
var db = ScriptDb.getMyDb();
 // Find people with an age of 40 or over.
 var results = db.query({
   type: 'person',
   age: db.greaterThanOrEqualTo(40)
 });
 while (results.hasNext()) {
   var item = results.next();
   // Do something with the item.
 }
 

Parameters

NameTypeDescription
valueObjectthe value to compare with

Return

QueryOperator — a query operator to be used in a query object


lessThan(value)

Returns a query operator that evaluates to true if the field's value is less than the passed in value. This operator only applies to numerical values.

 
var db = ScriptDb.getMyDb();
 // Find people with an age less than 12.
 var results = db.query({
   type: 'person',
   age: db.lessThan(12)
 });
 while (results.hasNext()) {
   var item = results.next();
   // Do something with the item.
 }
 

Parameters

NameTypeDescription
valueObjectthe value to compare with

Return

QueryOperator — a query operator to be used in a query object


lessThanOrEqualTo(value)

Returns a query operator that evaluates to true if the field's value is less than or equal to the passed in value. This operator only applies to numerical values.

 
var db = ScriptDb.getMyDb();
 // Find people with an age of 12 or less.
 var results = db.query({
   type: 'person',
   age: db.lessThanOrEqualTo(12)
 });
 while (results.hasNext()) {
   var item = results.next();
   // Do something with the item.
 }
 

Parameters

NameTypeDescription
valueObjectthe value to compare with

Return

QueryOperator — a query operator to be used in a query object


load(id)

Loads an item from the database by id.

 
var db = ScriptDb.getMyDb();
 var item = db.load(someId);
 

Parameters

NameTypeDescription
idStringthe id of the item to load

Return

ScriptDbMap — the item, or null if it cannot be found


load(ids)

Loads items from the database by id. If an item can't be found for a given id then it will be omitted from the results.

 
var db = ScriptDb.getMyDb();
 var items = db.load(arrayOfIds);
 

Parameters

NameTypeDescription
idsString[]the ids of the items to load

Return

ScriptDbMap[] — the items with matching ids


not(value)

Returns a query operator that evaluates to true if the field's value does not match the passed in value.

 
var db = ScriptDb.getMyDb();
 // Find people with the name "fred" and a town that isn't "Springfield".
 var results = db.query({
   type: 'person',
   name: 'fred',
   town: db.not('Springfield')
 });
 while (results.hasNext()) {
   var item = results.next();
   // Do something with the item.
 }
 

Parameters

NameTypeDescription
valueObjectthe value to compare with

Return

QueryOperator — a query operator to be used in a query object


query(query)

Query the database for matching items. This method uses a technique called "Query by Example", taking a partial object to us when matching against items in the database. The query object can contain QueryOperators to create more advanced queries.

 
var db = ScriptDb.getMyDb();
 // Find people with the name "fred" and age 25.
 var results = db.query({
   type: 'person',
   name: 'fred',
   age: 25
 });
 while (results.hasNext()) {
   var item = results.next();
   // Do something with the item.
 }
 

Parameters

NameTypeDescription
queryObjecta query object

Return

ScriptDbResult — an object used to retrieve the results


remove(item)

Removes an item from the database.

 
var db = ScriptDb.getMyDb();
 var result = db.query({name: 'fred'});
 // Just remove the first result.
 var item = result.next();
 db.remove(item);
 

Parameters

NameTypeDescription
itemScriptDbMapthe item to remove

removeBatch(items, atomic)

Removes items from the database.

 
var results = db.removeBatch(itemsToRemove, false);
 if (db.allOk(results)) {
   return;
 }
 var failedItems = [];
 for (var i = 0; i < results.length; i++) {
   if (!results[i].successful()) {
     failedItems.push(itemsToRemove[i]);
   }
 }
   // Handle the failed items, perhaps showing an error message.
 

Parameters

NameTypeDescription
itemsScriptDbMap[]the items to remove
atomicBooleanwhether to write to the database atomically or not. Currently only the value false is allowed.

Return

MutationResult[] — an array of result objects indicating success or failure


removeById(id)

Removes an item from the database by id.

 
var db = ScriptDb.getMyDb();
   db.removeById(someId);
 

Parameters

NameTypeDescription
idStringthe id of the item to remove

removeByIdBatch(ids, atomic)

Removes items from the database by id.

 
var results = db.removeBatch(idsToRemove, false);
 if (db.allOk(results)) {
   return;
 }
 var failedIds = [];
 for (var i = 0; i < results.length; i++) {
   if (!results[i].successful()) {
     failedIds.push(idsToRemove[i]);
   }
 }
 // Handle the failed ids, perhaps showing an error message.
 

Parameters

NameTypeDescription
idsString[]
atomicBoolean

Return

MutationResult[] — an array of result objects indicating success or failure


save(item)

Saves a new item to the database.

 
var db = ScriptDb.getMyDb();
 var item = db.save({
   type: 'person',
   name: 'fred',
   age: 25,
   single: true
 });
 

Parameters

NameTypeDescription
itemObjectthe item to save

Return

ScriptDbMap — the saved item


save(item)

Saves an existing item to the database, updating it.

 
var db = ScriptDb.getMyDb();
 var item = db.load(someId);
 item.newValue = 23;
 db.save(item);
 

Parameters

NameTypeDescription
itemScriptDbMapthe item to save

Return

ScriptDbMap — the saved item


saveBatch(items, atomic)

Saves items to the database. The items can be a mix of new objects to add and existing ScriptDbMaps to update. If an item fails to save then a MutationResult will be in the corresponding index of the results. Calling allOk(mutateResults) on the results allows you to quickly determine if there were any problems.

 
var results = db.saveBatch(itemsToSave, false);
 if (db.allOk(results)) {
   return;
 }
 var failedItems = [];
 for (var i = 0; i < results.length; i++) {
   if (results[i].successful && !results[i].successful()) {
     failedItems.push(itemsToSave[i]);
   }
 }
 // Handle the failed items, perhaps showing an error message.
 

Parameters

NameTypeDescription
itemsObject[]the items to save
atomicBooleanwhether to write to the database atomically or not. Currently only the value false is allowed.

Return

Object[] — the saved object

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.