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

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

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

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

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

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

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

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

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

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 omited from the results.

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

Parameters

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

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

Return

ScriptDbResult — an object used to retrieve the results

See also

• "https://developers.google.com/apps-script/scriptdb#querying_the_database"

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

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

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

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

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

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

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

Return

Object[] — the saved object