Skip to content

General Object Retrieval API

Advanced search use-cases supported by Backendless include:

  • Search with a query (a "where clause" search) -retrieves data objects which satisfy a condition.
  • Paged data retrieval - retrieves a "page" of data of the given size from the specified offset.
  • Sorted data object retrieval - retrieves a collection of data objects sorted by specified properties.
  • Retrieval of related objects - fetching data objects through special "relation" properties. See retrieval of related data objects.
  • Calculating aggregate values for a collection of objects - retrieves sum, average, min, max or count for all or a subset of objects in a table. See Aggregate Functions for more details.

Backendless supports data retrieval options listed above with a special class - Backendless.DataQueryBuilder. An instance of DataQueryBuilder can be passed into the find operation to retrieve data from the server according to the options set in the query builder object. The class provides the following methods:

Argument                Description
create() Creates a new instance of Backendless.DataQueryBuilder.
setProperties( arrayOfStrings ) Sets the names of the properties which values must be retrieved from the server. The argument must be either an array of strings where each element of the array identifies a property/column to be retrieved. Alternatively, the argument can be a string in the following format: "propertyName1, propertyName2, , , propertyNameN".
setWhereClause( stringValue ) Sets a search query. A query must be in the SQL-92 syntax (the "where" clause part).
setSortBy( arrayOfStrings ) Sets an array of column names to sort the data objects in the response by.
addRelated( stringValue | arrayOfStrings ) adds a related column or an array of related columns. Objects from the related columns are included into the response
setRelated( arrayOfStrings ) Sets an array of related columns names. Objects from the related columns are included into the response.
setRelationsDepth( numericValue ) Sets the number of "levels" in the hierarchy of related objects to include into the response.
setPageSize( numericValue ) Sets the page size - which is the number of objects to return in the response. Maximum value is 100.
setOffset( numericValue ) Sets the offset - an index in the server-side storage from where the data objects should be retrieved.
setGroupBy( stringValue ) Used with Aggregate Functions. Sets the name of a column to group the results by.
setHavingClause( stringValue ) Used with Aggregate Functions. Sets a condition on a aggregate function to filter groups.

To run a query-based search, use the following API methods:

var queryBuilder = Backendless.DataQueryBuilder.create();

// set query builder properties
// queryBuilder.setXXXX

Backendless.Data.of( "TABLE-NAME" ).find( queryBuilder )
 .then( function( objectArray ) {
  })
 .catch( function( error ) {
 });

// define constructor function. Instances of the DataTypeX class
// are stored in the "DataTypeX" table
function DataTypeX() {
  // define class properties here
}

var queryBuilder = Backendless.DataQueryBuilder.create();

// set query builder properties
// queryBuilder.setXXXX

Backendless.Data.of( DataTypeX ).find( queryBuilder )
 .then( function( dataTypeXobjectArray ) {
  })
 .catch( function( error ) {
 });

where:

Argument                Description
DataTypeX A reference to a JavaScript constructor function defining a JavaScript class. Object(s) returned by functions will be of the specified type.
TABLE-NAME Name of the table where to retrieve objects from.
query An instance of Backendless.DataQueryBuilder described above. The object contains the search query and other search options.

Return Value

A collection of objects found by the query.

Examples

For examples on using the advanced object retrieval API, see the following sub-sections: