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.

Method - Type 1

GET

Method - Type 2

POST

Endpoint URL - GET Request

The xxxx.backendless.app is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.

https://xxxx.backendless.app/api/data/<table-name>?props=prop1,prop2,prop3&  
                                               loadRelations=relprop1,relprop2&  
                                               where=whereClause&  
                                               pageSize=XX&  
                                               sortBy=prop1,prop2&  
                                               offset=2&  
                                               having=havingClause&  
                                               distinct=column1&  
                                               relationsDepth=2&  
                                               relationsPageSize=XX&  
                                               groupBy=ag_function&  
                                               excludeProps=prop2

where:

Argument	Description
<table-name>	Name of the table where to search for the object.
props	References object properties which should be returned with every object. In this example, objects in the result will contain only the "prop1" and "prop2" properties.
loadRelations	References object properties which are relations and should be initialized and returned with the parent object. By default relations are not returned with the parent object and require a separate API call to load. Using the loadRelations query parameter Backendless pre-initializes the specified relations and returns them with the parent object.
where	Contains an SQL query (the where clause part) which is used to search for the objects. The value must be URL encoded.
pageSize	Sets the page size which is the number of objects to be returned in the response.
sortBy	Lists properties by which the returned collection should be sorted by.
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.
having	Sets a condition on a aggregate function to filter groups.
distinct	Used to return only unique values from a column.
relationsDepth	Sets the number of "levels" in the hierarchy of related objects to include into the response.
relationsPageSize	sets the number of related objects returned in the response.
groupBy	Sets the name of the columns to group the results by.
excludeProps	Requests the server to exclude named properties from the response. For additional details see the Working with Properties section of this guide.

Endpoint URL - POST Request

In general, it is considered good practice to use POST methods instead of the GET, because the latter provides less functionality and security when transferring data.

https://xxxx.backendless.app/api/data/<table-name>?props=prop1,prop2,prop3&  
                                               loadRelations=relprop1,relprop2&  
                                               where=whereClause&  
                                               pageSize=XX&  
                                               sortBy=prop1,prop2&  
                                               offset=1&  
                                               having=havingClause&  
                                               distinct=column1&  
                                               relationsDepth=2&  
                                               relationsPageSize=XX&  
                                               groupBy=ag_function&  
                                               excludeProps=prop2

Request Headers

user-token:value-of-the-user-token-header-from-login

where:

Argument	Description
user-token	Optional header. Contains a value returned by Backendless in a preceding user Login API call. If user-tokenis set in the request, the operation will be executed with the security policy associated with the currently logged in user. This means all permissions associated with the user and roles assigned to the user will be enforced by Backendless.

Request Body:

None

Codeless Reference

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:

• Search with where clause
• Using dates in search
• Retrieval with paging
• Retrieval with sorting
• Search by distance