Collection

Collection management can be done by using the following functions and properties.

Method/Property Description
monaca.cloud.Collection() Get a collection object
monaca.cloud.Collection.find() Find all users’ data in the collection
monaca.cloud.Collection.findMine() Fetch current user’s data
monaca.cloud.Collection.findOne() Fetch an item of the collection
monaca.cloud.Collection.findOneMine() Fetch an item of the current user from the collection
monaca.cloud.Collection.insert() Insert data into a collection
monaca.cloud.Collection.updatePermission() Bulk update the permissions of collection items.

Collection()

Get a Collection object with a specific name. Please note that collection is not created automatically. You are required to make a collection manually with the IDE.

monaca.cloud.Collection(collectionName: string) : Object

Parameter

Name Type Description
collectionName String The name of a collection

Return Value

  • Collection object

Example

The following example indicates how to get a collection object called "diary".

var Diary = monaca.cloud.Collection("diary"); // returns Collection object

Collection.find()

Find all users’ data in the collection.

Collection.find(criteria: Criteria or String, [orderBy: String or Array], [options: Object]): $.Promise

Parameter

Name Type Description
criteria String Criteria or String
orderBy String field_name ASC|DESC: For multiple orders, use array (e.g. ["title ASC", "author ASC"]).
options JSON Object Available options:
  • propertyNames: specify the preferred user properties. If not specified, all user properties are returned.
  • limit: Limit number of results.
  • page: Start from specified page.

Return Value

Type Description
$.Promise object Use done(), fail() and always() methods to get results.

Within the done() callback, there is a JSON Object which has the following properties:

  • totalItems: The number of the items
  • items: Array of CollectionItem

Errors Code

Errors are returned as Error object.

Code Description
-32602 Invalid params

Example

The following example denotes how to search data in the "diary" collection, then return a set of items that match the criteria and sort the results by "_createdAt" property in descending order. Moreover, the returned items only have 2 properties: "title" and "body".

var Diary = monaca.cloud.Collection("diary");
var Criteria = monaca.cloud.Criteria('title == "Monaca"');
Diary.find(Criteria, "_createdAt DESC", {propertyNames: ["title", "body"], limit: 5})
.done(function(result)
{
    console.log('Total items found: ' + result.totalItems);
    console.log('The body of the first item: ' + result.items[0].body);
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

Or just pass the string for the criteria:

var Diary = monaca.cloud.Collection("diary");
Diary.find('title == "Monaca"', "", {propertyNames: ["title", "body"], limit: 5})
.done(function(result)
{
    console.log('Total items found: ' + result.totalItems);
    console.log('The body of the first item: ' + result.items[0].body);
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

Collection.findMine()

Find the current user’s data in the collection.

Collection.findMine(criteria: Criteria or String, [orderBy: String or Array], [options: Object]): $.Promise

Parameter

Name Type Description
criteria String Criteria or String
orderBy String field_name ASC|DESC: For multiple orders, use array (e.g. ["title ASC", "author ASC"]).
options JSON Object Available options:
  • propertyNames: specify the preferred user properties. If not specified, all user properties are returned.
  • limit: Limit number of results.
  • page: Start from specified page.

Return Value

Type Description
$.Promise object Use done(), fail() and always() methods to get results.

Within the done() callback, there is a JSON Object which has the following properties:

  • totalItems: The number of the items
  • items: Array of CollectionItem

Errors Code

Errors are returned as Error object.

Code Description
-32602 Invalid params

Example

The following example denotes how to search data in the "diary" collection, then return a set of items which has the nickname "my nickname" and sort the results by "_createdAt" property in descending order. Moreover, the returned items only have 2 properties: "title" and "body".

var Diary = monaca.cloud.Collection("diary");
Diary.findMine('nickname == "my nickname"', "", {propertyNames: ["title", "body"], limit: 5})
.done(function(result)
{
    console.log('Total items found: ' + result.totalItems);
    console.log('The body of the first item: ' + result.items[0].body);
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

Collection.findOne()

Fetch an item from the Collection. The first item is returned if multiple items are matched.

Collection.findOne(criteria: Criteria or String, [orderBy: String or Array], [options: Object]): $.Promise

Parameter

Name Type Description
criteria String Criteria or String
orderBy String field_name ASC|DESC: For multiple orders, use array (e.g. ["title ASC", "author ASC"]).
options JSON Object Available options:
  • propertyNames: specify the preferred user properties. If not specified, all user properties are returned.

Return Value

Type Description
$.Promise object Use done(), fail() and always() methods to get results.

Within the done() callback, there is a JSON Object which has the following properties:

  • items: A CollectionItem (or null when no result)

Errors Code

Errors are returned as Error object.

Code Description
-32602 Invalid params

Example

The following example denotes how to search data in the "diary" collection, then return a set of items that match the criteria and sort the results by "_createdAt" property in descending order.

var Diary = monaca.cloud.Collection("diary");
Diary.findOne('title == "Monaca"', "_createdAt DESC")
.done(function(result)
{
    console.log('The body of the item: ' + result.body);
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

Collection.findOneMine()

Fetch a current user’s item from the Collection. The first item is returned if multiple items are matched.

Collection.findOneMine(criteria: Criteria or String, [orderBy: String or Array], [options: Object]): $.Promise

Parameter

Name Type Description
criteria String Criteria or String
orderBy String field_name ASC|DESC: For multiple orders, use array (e.g. ["title ASC", "author ASC"]).
options JSON Object
    Available options:
  • propertyNames: Filter to minimize fetched data size.

Return Value

Type Description
$.Promise object Use done(), fail() and always() methods to get results.

Within the done() callback, there is a JSON Object which has the following properties:

  • items: A CollectionItem (or null when no result)

Errors Code

Errors are returned as Error object.

Code Description
-32602 Invalid params

Example

The following example denotes how to search data in "diary" collection, then return a set of items that match the criteria and sort the results by "_createdAt" property in descending order.

var Diary = monaca.cloud.Collection("diary");
Diary.findOneMine('title == "Monaca"', "_createdAt DESC")
.done(function(result)
{
    console.log('The body of the item: ' + result.body);
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

Collection.insert()

Insert an item into the Collection.

Collection.insert(item: Object, [permission: Object]) : $.Promise

Whether the permission is set or not set, the owner of the user always have read-and-write permission.

Parameter

Name Type Description Requirement
item JSON Object User-defined data of the new item Key names must consist of [a-zA-Z0-9] characters and must start with [a-zA-Z]. Data size must not exceed the size limit (500KB).
permission JSON Object A permission object applied to the item. Each key of the permission object can be "public" (all users) or a user’s Oid. Each value of the permission object can be "r" (allow read) , "w" (allow write), "rw" (allow read and write) or "" (allow nothing). For instance: { "public": "rw", "oidOfUserA": "r", "oidOfUserB": "rw"}

Return Value

Type Description
$.Promise object Use done(), fail() and always() methods to get results.

Within the done() callback, there is a JSON Object which has the following properties:

  • items: Array of CollectionItem

Errors Code

Errors are returned as Error object.

Code Description
-32602 Invalid params
-14 Permission denied (When it’s not allowed to insert data from Apps)

Example

The following example denotes how to insert an item which has 3 fields (title, body, _createdAt) into "diary" collection and set permission for a user with id of x00000000-xxxx-xxxx-xxxx-xxxxxxxxxxxx to read-only for that item.

var Diary = monaca.cloud.Collection("diary");
var friendUserOid = "x00000000-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
var permission = {};
permission[friendUserOid] = "r";

Diary.insert({title: 'Any title', body: 'Hello World'}, permission)
.done(function(result)
{
    console.log("Inserted!");
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

Collection.updatePermission()

Bulk update the permissions of collection items

Collection.updatePermission(criteria: Criteria or String, permission: Object, [options: Object]) : $.Promise

Parameter

Name Type Description
criteria String Criteria or String
permission JSON Object The Object representing permission. rw is read/write, r is read-only, w is write-only and empty string is no permission. Available options:
  • forceOverwrite: (boolean)[default: false] Whether to overwrite current permission.

Return Value

Type Description
$.Promise object Use done(), fail() and always() methods to get results.

Within the done() callback, there is a JSON Object which has the following properties:

  • numUpdates : The number of updated items

Errors Code

Errors are returned as Error object.

Code Description
-32602 Invalid params
-14 Permission denied (When it’s not allowed to insert data from Apps)

Example

The following example denotes how to assign the read/write permission to the UserX and read-only permission to the UserY.

var Diary = monaca.cloud.Collection("diary");

var oids =
{
    userX: "x00000000-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    userY: "x00000000-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
};

var newPermission = {};
newPermission[oids.userX] = "rw";
newPermission[oids.userY] = "r";

Diary.updatePermission('group_id == 1', newPermission)
.done(function(result)
{
    console.log(result.numUpdates + " items updated");
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

See Also: