StoreQuery interface

A JavaScript object implementing the StoreQuery interface represents a query of objects within the object store, and can execute the query returning results as a StoreQueryResults object.

Construction

Use O.query().

Interface

function execute()

Executes the query, returning an object implementing the StoreQueryResults.

After this function is called, no other functions should be called.

function setSparseResults(sparse)

If you’re not going to use all the results, for example, if they’re paged, call setSparseResults(true) to only load references and the full objects on demand. You should then use ensureRangeLoaded() on the results object to load ranges of results efficiently.

If this function is not called, the default is false.

Returns itself, making the function suitable for chaining.

function sortBy(order)

Set the order of the objects in the results. Allowed values for order are date, date_asc, created_date, created_date_asc, modified_date, modified_date_asc, relevance, any, title and title_desc.

The default sort order is any, which returns the objects in whatever order is quickest for the object store.

Returns itself, making the function suitable for chaining.

There are also shortcut functions defined, sortByDate(), sortByDateAscending(), sortByCreatedDate(), sortByCreatedDateAscending(), sortByLastModificationDate(), sortByLastModificationDateAscending(), sortByRelevance(), sortByTitle() and sortByTitleDescending(), which set the order accordingly and return the object for chaining.

function queryDeletedObjects()

Set the query to return deleted objects which match the query. Only objects which have been deleted will be returned.

Returns itself, making the function suitable for chaining.

function includeArchivedObjects()

Set the query to include objects which are labelled with the ARCHIVED label in the search results. By default, these objects are omitted from query results.

Returns itself, making the function suitable for chaining.

function freeText(text, desc, qual)

Find objects which match the given free text. text must be a non-empty String. The search will use the usual rules, including case insensitivity and stemming of the terms.

The optional desc and qual arguments restrict the attributes which are searched.

This function is intended for performing searches based on queries entered by the user. If your intention is to find a specific object, use the object’s reference, or to find groups of specific objects, use the link() function.

Note that text indexing is performed in the background, so queries immediately after creating or updating an object may not find these new objects.

Returns itself, making the function suitable for chaining.

function exactTitle(title)

Finds objects with an exact given title. title must be a non-empty String. The search will normalise title, making it case and accent insensitive.

In the current implementation, searches for exact titles do not need to wait for text indexing to complete before they find new objects. However, this property should not be relied on by plugin code.

Returns itself, making the function suitable for chaining.

function link(ref, desc, qual)

Query for objects linked to a given object. Optional desc and qual arguments restrict the values which are searched.

ref may also be an array of Ref objects, when an or() subquery will be generated. If the array is empty, a clause will be added that matches nothing.

Returns itself, making the function suitable for chaining.

Examples:

var q = O.query();
q.link(T.Book, A.Type);         // search for objects of a given type
q.link(clientObject, A.Client); // search for objects linked to a client
var q2 = O.query();
q2.link([T.Book, T.Journal], A.Type); // either Books or Journals

function linkDirectly(ref, desc, qual)

Similar to the link() function, but only returns objects which link directly to the given ref, rather than the given ref or any of its child objects.

Normally you should use link() as, in general, returning objects linked to the given object and any child objects will return results which match the user’s expectations. linkDirectly() is useful when you are building user interfaces for hierarchical data and need to explicitly query the hierarchy.

Returns itself, making the function suitable for chaining.

function linkToAny(desc, qual)

Query for objects which are linked to any other object, used for checking for the presence of a link. desc must be specified, but qual is optional.

Returns itself, making the function suitable for chaining.

function identifier(identifier, desc, qual)

Query for objects which are identified using the given identifier text object, for example, an email address. Optional desc and qual arguments restrict the values which are searched.

This differs from text searches as the identifier is matched exactly, without natural language processing, using identifier specific equality rules.

It only works for text types which act as identifiers. These correspond to the types with names beginning T_IDENTIFIER in Text types.

Returns itself, making the function suitable for chaining.

This example builds a query to find People objects with a given email address:

var email = O.text(O.T_IDENTIFIER_EMAIL_ADDRESS, "joe@example.com");
var q = O.query();
q.link(T.Person, A.Type);
q.identifier(email, A.Email);

function or(fn)

Make an OR sub-clause, which matches objects matching any of its sub-clauses.

If the fn argument is a function, that function will be called with the sub-clause as an argument, and the object will return itself for chaining. Otherwise, the sub-clause is returned from this function.

This example shows both ways the sub-clause function can be used.

// Preferred style
var q = O.query().or(function(subquery) {
    subquery.link(T.Book, A.Type).
             link(clientObject, A.Client);
});
// Alternative style
var q = O.query();
var orClause = q.or();
orClause.link(T.Book, A.Type).
         link(clientObject, A.Client);
// And in either case, execute the top level query
var results = q.execute();

function and(fn)

Make an AND sub-clause, which matches objects matching all its sub-clauses.

If the fn argument is a function, that function will be called with the sub-clause as an argument, and the object will return itself for chaining. Otherwise, the sub-clause is returned from this function.

Use in a similar manner to the or() sub-clause. Given that the top level clause returned by O.query() is an AND clause, this is mainly useful nested within other clauses.

function not(fn)

Make a NOT sub-clause, which matches objects matching the first clause, but not any of the other clauses.

If you do not include at least two sub-clauses, an exception will be thrown when you execute the query.

If the fn argument is a function, that function will be called with the sub-clause as an argument, and the object will return itself for chaining. Otherwise, the sub-clause is returned from this function.

This example finds all books which do not have an author:

var anonymousBooks = O.query().not(function(subquery) {
    subquery.link(T.Book, A.Type).
             linkToAny(A.Author);
}).execute();

function linkToQuery(desc, qual, hierarchicalLink, fn)

Make a sub-clause which performs a sub-query, then finds all objects which link to any of the results. If desc and qual are given, only consider links in those values.. If hierarchicalLink is true (the default), then hierarchical links are used, otherwise the objects must link exactly.

desc, qual and hierarchicalLink are optional and may be omitted.

If the last argument is a function, that function will be called with the sub-clause as an argument, and the object will return itself for chaining. Otherwise, the sub-clause is returned from this function.

function linkFromQuery(desc, qual, fn)

Make a sub-clause which performs a sub-query, then finds all objects which any of the results contains a link to. If desc and qual are given, only consider links in those values.

desc and qual are optional and may be omitted.

If the last argument is a function, that function will be called with the sub-clause as an argument, and the object will return itself for chaining. Otherwise, the sub-clause is returned from this function.

function createdByUser(userOrUid)

Query for objects which were created by a given user. Pass in a numeric user ID, or a SecurityPrincipal object.

Returns itself, making the function suitable for chaining.

function dateRange(startDate, endDate, desc, qual)

Query for objects which have a date value in the given range. Values must satisfy startDate <= value < endDate.

startDate and endDate must be JavaScript Date objects. Either startDate or endDate can be null in which case the query is unbounded in that direction.

The optional desc and qual arguments restrict the values which are searched.

Returns itself, making the function suitable for chaining.

function lastUpdatedWithinDateRange(startDate, endDate)

Query for objects that have last been updated with the given range.

startDate and endDate must be JavaScript Date objects. Either startDate or endDate can be null in which case the query is unbounded in that direction.

function anyLabel(labels)

Query for objects which have one or more of the labels in the labels list, which is an array of Ref objects.

Returns itself, making the function suitable for chaining.

function allLabels(labels)

Query for objects which have all of the labels in the labels list, which is an array of Ref objects.

Returns itself, making the function suitable for chaining.

function notLabelled(labels)

Query for objects which have none of the labels in the labels list, which is an array of Ref objects.

Returns itself, making the function suitable for chaining.

function limit(maximumResults)

Limit the number of results which will be returned by this query. For paging results, see setSparseResults().

Returns itself, making the function suitable for chaining.