Deprecated. ScriptDB was deprecated on May 15, 2014, and will be turned off on November 20, 2014. To move your data to a different type of database, see the guide to migrating from ScriptDB.
A JavaScript object database for permanently storing data. Use
to retrieve
items, query(query)
to create or update them, and save(item)
to delete them. When
modifying more than one item at a time use the batch methods. The methods that return
remove(item)
are used for constructing query objects and do not initiate requets to the
database.QueryOperator
Deprecated properties
Property | Type | Description |
---|---|---|
ASCENDING |
| Ascending sort direction. |
DESCENDING |
| Descending sort direction. |
LEXICAL |
| Lexical sort strategy. |
NUMERIC |
| Numeric sort strategy. |
Deprecated methods
Method | Return type | Brief description |
---|---|---|
| Boolean | Returns true if all of the items in the result set were successful. |
|
| Returns a query operator that evaluates to true if the field's value matches any of the passed in values. |
|
| Returns a query operator that evaluates to true if the field has any value. |
|
| Returns a query operator that evaluates to true if the field has a value in-between the two passed in values. |
| Integer | Returns the number of items that match the query. |
|
| Returns a query operator that evaluates to true if the field's value is greater than the passed in value. |
|
| Returns a query operator that evaluates to true if the field's value is greater than or equal to the passed in value. |
|
| Returns a query operator that evaluates to true if the field's value is less than the passed in value. |
|
| Returns a query operator that evaluates to true if the field's value is less than or equal to the passed in value. |
|
| Loads an item from the database by id. |
|
| Loads items from the database by id. |
|
| Returns a query operator that evaluates to true if the field's value does not match the passed in value. |
|
| Query the database for matching items. |
| void | Removes an item from the database. |
|
| Removes items from the database. |
| void | Removes an item from the database by id. |
|
| Removes items from the database by id. |
|
| Saves a new item to the database. |
|
| Saves an existing item to the database, updating it. |
| Object[] | Saves items to the database. |
Deprecated methods
allOk(mutateResults)
allOk(mutateResults)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
mutateResults | Object[] | the results from a batch mutation operation |
Return
Boolean
— true if all the items were successful, false if any item failed
anyOf(values)
anyOf(values)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
values | Object[] | the values to compare with |
Return
— a query operator to be used in a query objectQueryOperator
anyValue()
anyValue()
Deprecated. This function is deprecated and should not be used in new scripts.
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
— a query operator to be used in a query objectQueryOperator
between(value1, value2)
between(value1, value2)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
value1 | Object | the inclusive lower bound |
value2 | Object | the exclusive upper bound |
Return
— a query operator to be used in a query objectQueryOperator
count(query)
count(query)
Deprecated. This function is deprecated and should not be used in new scripts.
Returns the number of items that match the query. This accepts the same query objects as the
method.
query(query)
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
Name | Type | Description |
---|---|---|
query | Object | a query object |
Return
Integer
— the number of items that match the query
greaterThan(value)
greaterThan(value)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
value | Object | the value to compare with |
Return
— a query operator to be used in a query objectQueryOperator
greaterThanOrEqualTo(value)
greaterThanOrEqualTo(value)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
value | Object | the value to compare with |
Return
— a query operator to be used in a query objectQueryOperator
lessThan(value)
lessThan(value)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
value | Object | the value to compare with |
Return
— a query operator to be used in a query objectQueryOperator
lessThanOrEqualTo(value)
lessThanOrEqualTo(value)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
value | Object | the value to compare with |
Return
— a query operator to be used in a query objectQueryOperator
load(id)
load(id)
Deprecated. This function is deprecated and should not be used in new scripts.
Loads an item from the database by id.
var db = ScriptDb.getMyDb();
var item = db.load(someId);
Parameters
Name | Type | Description |
---|---|---|
id | String | the id of the item to load |
Return
— the item, or null if it cannot be foundScriptDbMap
load(ids)
load(ids)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
ids | String[] | the ids of the items to load |
Return
— the items with matching idsScriptDbMap[]
not(value)
not(value)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
value | Object | the value to compare with |
Return
— a query operator to be used in a query objectQueryOperator
query(query)
query(query)
Deprecated. This function is deprecated and should not be used in new scripts.
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
s to create more advanced queries.
QueryOperator
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
Name | Type | Description |
---|---|---|
query | Object | a query object |
Return
— an object used to retrieve the resultsScriptDbResult
remove(item)
remove(item)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
item |
| the item to remove |
removeBatch(items, atomic)
removeBatch(items, atomic)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
items |
| the items to remove |
atomic | Boolean | whether to write to the database atomically or not. Currently only the value false is allowed. |
Return
— an array of result objects indicating success or failureMutationResult[]
removeById(id)
removeById(id)
Deprecated. This function is deprecated and should not be used in new scripts.
Removes an item from the database by id.
var db = ScriptDb.getMyDb();
db.removeById(someId);
Parameters
Name | Type | Description |
---|---|---|
id | String | the id of the item to remove |
removeByIdBatch(ids, atomic)
removeByIdBatch(ids, atomic)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
ids | String[] | |
atomic | Boolean |
Return
— an array of result objects indicating success or failureMutationResult[]
save(item)
save(item)
Deprecated. This function is deprecated and should not be used in new scripts.
Saves a new item to the database.
var db = ScriptDb.getMyDb();
var item = db.save({
type: 'person',
name: 'fred',
age: 25,
single: true
});
Parameters
Name | Type | Description |
---|---|---|
item | Object | the item to save |
Return
— the saved itemScriptDbMap
save(item)
save(item)
Deprecated. This function is deprecated and should not be used in new scripts.
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
Name | Type | Description |
---|---|---|
item |
| the item to save |
Return
— the saved itemScriptDbMap
saveBatch(items, atomic)
saveBatch(items, atomic)
Deprecated. This function is deprecated and should not be used in new scripts.
Saves items to the database. The items can be a mix of new objects to add and existing
s to update. If an item fails to save then a ScriptDbMap
will
be in the corresponding index of the results. Calling MutationResult
on the results allows you
to quickly determine if there were any problems.
allOk(mutateResults)
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
Name | Type | Description |
---|---|---|
items | Object[] | the items to save |
atomic | Boolean | whether to write to the database atomically or not. Currently only the value false is allowed. |
Return
Object[]
— the saved object