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 the options listed above with a special class - DataQueryBuilder. The class includes various properties to configure paging and sorting, specify a search query (the where clause), and/or to request retrieval of objects for specific related properties. The DataQueryBuilder class provides the following methods:

Argument	Description
`create`	creates a new instance of `DataQueryBuilder`.
`setWhereClause`	sets a search query. A query must be in the SQL-92 syntax (the "where" clause part).
`setSortBy`	sets an array of column names to sort the data objects in the response by.
`setRelated`	sets an array of related columns names. Objects from the related columns are included into the response. For information about relation retrieval, see the Relations (Retrieve) chapter of the documentation.
`setRelationsDepth`	sets the number of "levels" in the hierarchy of related objects to include into the response.
`setPageSize`	sets the page size - which is the number of objects to return in the response. Maximum value is 100. For more information on paging, see the Data retrieval with Paging section.
`setOffset`	sets the offset - an index in the server-side storage from where the data objects should be retrieved.
`setGroupBy`	Used with Aggregate Functions. Sets the name of the columns to group the results by.
`addGroupBy`	Used with Aggregate Functions. Add the name of the columns to the existing `groupBy` collection to group the results by.
`setHavingClause`	Used with Aggregate Functions. Sets a condition on a aggregate function to filter groups.

Method Signature¶

Blocking API

Using Java Map

// Return value from the server is a collection of java.util.Map objects; 
List<Map> result;

// The data table must be identified by name. The API
// returns a collection of Map objects.
DataQueryBuilder queryBuilder = DataQueryBuilder.create();
result = Backendless.Data.of( "TABLE-NAME" ).find( queryBuilder );

Custom Class

List<E> result = Backendless.Data.of( E ).find( DataQueryBuilder queryBuilder );

Non-Blocking API

Using Java Map

Backendless.Data.of( "TABLE-NAME" ).find( DataQueryBuilder query, 
                                          AsyncCallback<List<Map>> );

Custom Class

Backendless.Data.of( E ).find( DataQueryBuilder queryBuilder, 
                               AsyncCallback<List<E>> );

where:

Argument	Description
`TABLE-NAME`	Name of the table to retrieve data from.
`E`	Java class identifying the table to retrieve data from. The name of the class must match the name of the table.
`queryBuilder`	an instance of `DataQueryBuilder` - contains the search query and other search options.
`responder`	a responder object which will receive a callback when the search operation returns the result. Applies to the asynchronous method only.

Return Value¶

The synchronous method returns a collection of strongly typed objects found as a result of the query execution. The asynchronous call receives the return value through a callback executed on the AsyncCallback object.

Examples¶

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