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 - 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
whereClause Sets a search query. A query must be in the SQL-92 syntax (the "where" clause part).
sortBy Sets an array of column names to sort the data objects in the response by.
related Sets an array of related columns names. Objects from the related columns are included into the response.
relationsDepth Sets the number of "levels" in the hierarchy of related objects to include into the response.
pageSize Sets the page size - which is the number of objects to return in the response. Maximum value is 100.
offset Sets the offset - an index in the server-side storage from where the data objects should be retrieved.
groupBy Used with Aggregate Functions. Sets the name of a column to group the results by.
havingClause 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:

- (void)findWithQueryBuilder:(DataQueryBuilder * _Nonnull)queryBuilder responseHandler:^(NSArray * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;

func find(queryBuilder: DataQueryBuilder, responseHandler: (([Any]) -> Void)!, errorHandler: ((Fault) -> Void)!)

- (void)findWithQueryBuilder:(DataQueryBuilder * _Nonnull)queryBuilder responseHandler:^(NSArray<NSDictionary<NSString *,id> *> * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;

func find(queryBuilder: DataQueryBuilder, responseHandler: (([[String : Any]]) -> Void)!, errorHandler: ((Fault) -> Void)!)

where:

Argument                Description
queryBuilder An instance of DataQueryBuilder - contains the search query and other search options.

Return Value

Returns a collection of strongly typed data objects retrieved as a result of the query execution.

Codeless Reference

data_service_load_objects_main

where:

Argument                Description
table name Name of the data table from where the objects are retrieved.
where clause A search query used by the server it to determine objects matching the condition.
having clause Sets a condition on a aggregate function to filter groups.
relations Name of the related property to load. For example, if table employees has a relation column homeAddress pointing to an object in the Address table, the value of the parameter would be homeAddress. The syntax allows to add relations of relations. For example, if the same Address table has a relation country pointing to the Country table, then homeAddress.country would instruct the backend to load the related Country object.
properties Names of the properties/columns for which  to load the corresponding values.
exclude properties Names of the properties/columns that should not be included in the response.
relations depth Depth of the relations to include into the response.
relations page size Sets the number of related objects returned in the response.
sort by Lists properties by which the returned collection should be sorted by.
group by Sets the name of the columns to group the results by.
page size Sets the page size which is the number of objects to be returned in the response.
page offset Zero-based index of the object in the persistent store from which to run the search. This parameter should be used when implementing paged access to data. Suppose the first request returned 20 objects (if pageSize is set to 20) and there are 100 objects total. The subsequent request can set offset to 20, so the next batch of objects is loaded sequentially.
distinct Used to return only unique values from a column.
file reference prefix This property allows replacing the default URL file prefix. For instance, when the operation returns a path to a file stored on the server ("https://yourdomain.backendless.app/my-file.jpg"), then you can reconstruct it by passing the new file name that must start with a slash - "/wonderful_forest.jpg". It is useful when you want the client application to open a specific file locally.

Examples

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