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 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).
addProperty adds a property to the list of properties/columns to be retrieved from the server. For additional details see the Working with Properties section of this guide.
addProperties adds the specified properties to the list of properties/columns to be retrieved from the server. For additional details see the Working with Properties section of this guide.
setProperties removes any previously added properties and sets the specified ones to be retrieved from the server. For additional details see the Working with Properties section of this guide.
excludeProperties Requests the server to exclude named properties from the response. For additional details see the Working with Properties section of this guide.
excludeProperty Requests the server to exclude the specified property from the response. For additional details see the Working with Properties section of this guide.
addAllProperties Requests the server to return all available properties. For additional details see the Working with Properties section of this guide.
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

// 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 );

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

Non-Blocking API

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

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: