Query

Entity constructor functions

The constructor function returned by a persistence.define call cannot only be used to instantiate new objects, it also has some useful methods of its own:

• EntityName.all([session]) returns a query collection (see below) containing all persisted instances of that object. The session argument is optional and only required when persistence.js is used in a server-side context.
• EntityName.load([session], [tx], id, callback) loads an particular object from the database by id or returns null if it has not been found.
• EntityName.findBy([session], [tx], property, value, callback) searches for a particular object based on a property value (this is assumed to be unique), the callback function is called with the found object or null if it has not been found.

Query collections

A core concept of persistence.js is the QueryCollection. A QueryCollection represents a (sometimes) virtual collection that can be filtered, ordered or paginated. QueryCollections are somewhate inspired by Google AppEngine's Query class. A QueryCollection has the following methods:

• filter(property, operator, value)
  Returns a new QueryCollection that adds a filter, filtering a certain property based on an operator and value. Supported operators are '=', '!=', '<', '<=', '>', '>=', 'in' and 'not in'. Example: .filter('done', '=', true)
• or(filter)
  Returns a new QueryCollection that contains items either matching the filters specified before calling or, or the filter represented in the argument. The filter argument is of a Filter type, there are three types of filters:
  • persistence.PropertyFilter, which filters on properties (internally called when filter(...) is used.
    Example: new persistence.PropertyFilter('done', '=', true)
  • persistence.AndFilter, which is passed two filter objects as arguments, both of which should be true. Example: new persistence.AndFilter(new persistence.PropertyFilter('done', '=', true), new persistence.PropertyFilter('archived', '=', true))
  • persistence.OrFilter, which is passed two filter objects as arguments, one of which should be true. Example: new persistence.OrFilter(new persistence.PropertyFilter('done', '=', true), new persistence.PropertyFilter('archived', '=', true))
• and(filter)
  same as or(filter) except that both conditions should hold for items to be in the collection.
• order(property, ascending)
  Returns a new QueryCollection that will order its results by the property specified in either an ascending (ascending === true) or descending (ascending === false) order.
• limit(n)
  Returns a new QueryCollection that limits the size of the result set to n items. Useful for pagination.
• skip(n)
  Returns a new QueryCollection that skips the first n results. Useful for pagination.
• prefetch(rel)
  Returns a new QueryCollection that prefetches entities linked through relationship rel, note that this only works for one-to-one and many-to-one relationships.
• add(obj)
  Adds object obj to the collection.
• remove(obj)
  Removes object obj from the collection.
• list([tx], callback)
  Asynchronously fetches the results matching the formulated query. Once retrieved, the callback function is invoked with an array of entity objects as argument.
• each([tx], eachCallback)
  Asynchronously fetches the results matching the formulated query. Once retrieved, the eachCallback function is invoked on each element of the result objects.
• forEach([tx], eachCallback)
  Alias for each
• one([tx], callback) Asynchronously fetches the first element of the collection, or null if none.
• destroyAll([tx], callback) Asynchronously removes all the items in the collection. Important: this does not only remove the items from the collection, but removes the items themselves!
• count([tx], callback) Asynchronously counts the number of items in the collection. The arguments passed to the callback function is the number of items.

Query collections are returned by:

• EntityName.all(), e.g. Task.all()
• one-to-many and many-to-many relationships, e.g. task.tags
• Some plug-ins special functions, such as persistence.search.js's EntityName.search() function

Example:

var allTasks = Task.all().filter("done", '=', true).prefetch("category")
                         .order("name", false).limit(10);

allTasks.list(null, function (results) {
    results.forEach(function (r) {
        console.log(r.name)
        window.task = r;
    });
});